4.14. TQL Row Access Control in Queries

A TQL query will only access vertices, edges, or rows that the authenticated user initiating the query has permission to view. Frames that have row access control enabled may have security labels attached to each row and a row is only visible to a query if the user has the necessary security labels in their label set. The label set of a user will be configured by the administrator as described in Configuring Groups and Labels.

Row access means that the result of the same query may vary for different users. For example, when running a query to count the number of occurrences of a pattern, a user with more labels in their label set might see a higher count value than a user with fewer labels.

If a TQL query accessed frames with row security to produce a result, the results table will also have row security enabled. Each row of the results table is protected by the union of security labels found on any input row used to produce the resulting row. For example, for the simple query shown below, each output row has the same security labels as the corresponding input vertex row from the frame VertexFrame.

MATCH (v:VertexFrame)
WHERE v.id > 2000
RETURN v
ORDER BY v.age
INTO QueryResults

For the following query, each result row is obtained by accessing vertices v and w in VertexFrame and an edge e in EdgeFrame. Therefore, attached to each result row will be the union of row labels attached to the vertex v, the vertex w, and the edge e that contributed to the match.

MATCH (v:VertexFrame)-[e:EdgeFrame]->(w:VertexFrame)
WHERE v.val = 2000 AND e.duration > 10
RETURN v.id AS vid, v.val AS vertex_value, e.duration AS duration
INTO QueryResults

For the aggregate query shown below, the labels of the single result row will be the union of labels attached to any edge in EdgeFrame that the user has permission to see and the labels of any source or target vertex of such an edge in VertexFrame. Note that in order to have permission to see an edge, the user must also have permission to see both its source and target vertex. If these frames had other elements not viewable by the user, they will not affect the labels attached to the result. For example, if the query accessed vertices VertexFrame with labels “label1”, “label3”, “label5” and accessed edges in EdgeFrame with labels “label5”, “label6”, then the result row would have attached labels “label1”, “label3”, “label5”, “label6”.

MATCH (v:VertexFrame)-[e:EdgeFrame]->(w:VertexFrame)
WHERE v.val = 2000 AND e.duration > 10
RETURN count(*)
INTO QueryResults

As described in section Access Control, the universe of possible labels that can be attached to any row of a frame is set during frame creation and cannot be changed. Therefore, if the results table has been created before running a TQL query, its row label universe must contain all labels that will be attached to any of its rows during the query. Otherwise, xGT will report an error. The maximum number of security labels in a frame’s row label universe is 128. Running a query that would produce a results table with more than 128 unique row labels will produce an error. This might occur, for example, in the count query above if there were 100 unique security labels attached to vertices of VertexFrame accessed during the query and 100 different unique security labels attached to edges of EdgeFrame accessed during the query. If the table named in the INTO clause doesn’t already exist, it will be created with the appropriate row label universe.