Retrieves connected records crossing relationships. This works with both the Document and Graph API's, meaning that you can traverse relationships between say invoices and customers on a graph, without the need to model the domain using the Graph API.
|In many cases, you may find it more efficient to use
TRAVERSE <[class.]field>|*|any()|all() [FROM <target>] [ MAXDEPTH <number> | WHILE <condition> ] [LIMIT <max-records>] [STRATEGY <strategy>]
<fields>Defines the fields you want to traverse.
<target>Defines the target you want to traverse. This can be a class, one or more clusters, a single Record ID, set of Record ID's, or a sub-query.
MAXDEPTHDefines the maximum depth of the traversal.
0indicates that you only want to traverse the root node. Negative values are invalid.
WHILEDefines the condition for continuing the traversal while it is true.
LIMITDefines the maximum number of results the command can return.
STRATEGYDefines strategy for traversing the graph.
NOTE: The use of the
WHEREclause has been deprecated for this command.
NOTE: There is a difference between
WHILE DEPTH <= N: the
MAXDEPTHwill evaluate exactly N levels, while the
WHILEwill evaluate N+1 levels and will discard the N+1th, so the
MAXDEPTHin general has better performance.
In a social network-like domain, a user profile is connected to friends through links. The following examples consider common operations on a user with the record ID
Traverse all fields in the root record:
TRAVERSE * FROM #10:1234
Specify fields and depth up to the third level, using the
TRAVERSE out("Friend") FROM #10:1234 WHILE $depth <= 3 STRATEGY BREADTH_FIRST
Execute the same command, this time filtering for a minimum depth to exclude the first target vertex:
SELECT FROM (TRAVERSE out("Friend") FROM #10:1234 WHILE $depth <= 3) WHERE $depth >= 1
Combine traversal with
SELECTcommand to filter the result-set. Repeat the above example, filtering for users in Rome:
SELECT FROM (TRAVERSE out("Friend") FROM #10:1234 WHILE $depth <= 3) WHERE city = 'Rome'
Extract movies of actors that have worked, at least once, in any movie produced by J.J. Abrams:
SELECT FROM (TRAVERSE out("Actors"), out("Movies") FROM (SELECT FROM Movie WHERE producer = "J.J. Abrams") WHILE $depth <= 3) WHERE @class = 'Movie'
Display the current path in the traversal:
SELECT $path FROM ( TRAVERSE out() FROM V WHILE $depth <= 10 )
Defines the fields that you want to traverse. If set to
all() then it traverses all fields. This can prove costly to performance and resource usage, so it is recommended that you optimize the command to only traverse the pertinent fields.
In addition tot his, you can specify the fields at a class-level. Polymorphism is supported. By specifying
Person.city and the class
Customer extends person, you also traverse fields in
Field names are case-sensitive, classes not.
Targets for traversal can be,
<class>Defines the class that you want to traverse.
CLUSTER:<cluster>Defines the cluster you want to traverse.
<record-id>Individual root Record ID that you want to traverse.
[<record-id>,<record-id>,...]Set of Record ID's that you want to traverse. This is useful when navigating graphs starting from the same root nodes.
In addition to the above, you can use the following context variables in traversals:
$parentGives the parent context, if any. You may find this useful when traversing from a sub-query.
$currentGives the current record in the iteration. To get the upper-level record in nested queries, you can use
$depthGives the current depth of nesting.
$pathGives a string representation of the current path. For instance,
#5:0#.out. You can also display it through
SELECT $path FROM (TRAVERSE * FROM V)
$stackGives a list of operations in the stack. Use it to access the traversal history. It's a
List<OTraverseAbstractProcess<?>>, where the process implementations are:
OTraverseRecordSetProcessThe base target of traversal, usually the first given.
OTraverseRecordProcessThe traversed record.
OTraverseFieldProcessThe traversal through the record's fields.
OTraverseMultiValueProcessUse on fields that are multivalue, such as arrays, collections and maps.
$historyGives a set of records traversed as
For example, this query traverses the
follow relationship on Twitter accounts, getting the second level of friendship:
SELECT FROM (TRAVERSE out('follow') FROM TwitterAccounts WHILE $depth <= 2) WHERE $depth = 2
But, you could also express this same query using
SELECT operation, in a way that is also shorter and faster:
SELECT out('follow').out('follow') FROM TwitterAccounts
While you can use the
TRAVERSE command with any domain model, it provides the greatest utility in [Graph Databases[(Graph-Database-Tinkerpop.md) model.
This model is based on the concepts of the Vertex (or Node) as the class
V and the Edge (or Arc, Connection, Link, etc.) as the class
E. If you want to traverse in a direction, you have to use the class name when declaring the traversing fields. The supported directions are:
- Vertex to outgoing edges Using
outE('EdgeClassName'). That is, going out from a vertex and into the outgoing edges.
- Vertex to incoming edges Using
inE('EdgeClassName'). That is, going from a vertex and into the incoming edges.
- Vertex to all edges Using
bothE('EdgeClassName'). That is, going from a vertex and into all the connected edges.
- Edge to Vertex (end point) Using
inV(). That is, going out from an edge and into a vertex.
- Edge to Vertex (starting point) Using
outV(). That is, going back from an edge and into a vertex.
- Edge to Vertex (both sizes) Using
bothV(). That is, going from an edge and into connected vertices.
- Vertex to Vertex (outgoing edges) Using
out('EdgeClassName'). This is the same as
- Vertex to Vertex (incoming edges) Using
in('EdgeClassName'). This is the same as
- Vertex to Vertex (all directions) Using
For instance, traversing outgoing edges on the record
TRAVERSE out() FROM #10:3434
In a domain for emails, to find all messages sent on January 1, 2012 from the user Luca, assuming that they are stored in the vertex class
User and that the messages are contained in the vertex class
Message. Sent messages are stored as
out connections on the edge class
SELECT FROM (TRAVERSE outE(), inV() FROM (SELECT FROM User WHERE name = 'Luca') WHILE $depth
The deprecated syntax for the
TRAVERSE operator looks like this:
|WARNING: Beginning in version 2.1, OrientDB no longer supports this syntax.|
SELECT FROM <target> WHERE <field> TRAVERSE[(<minDeep> [,<maxDeep> [,<fields>]])] (<conditions>)
<target>Defines the query target.
<field>Defines the field to traverse. Supported fields are,
outGives outgoing edges.
inGives incoming edges.
any()Any field, including
all()All fields, including
- Any attribute of the vertex.
minDeepDefines the minimum depth-level to begin applying the conditions. This is usually
0for the root vertex, or
1for only the outgoing vertices.
maxDeepDefines the maximum depth-level to read. Default is
-1, for infinite depth.
[<field>, <field>,...]Defines a list of fields to traverse. Default is
<conditions>Defines conditions to check on any traversed vertex.
For more information, see SQL syntax.
Find all vertices that have at least one friend, (connected through
out), up to the third depth, that lives in Rome:
SELECT FROM Profile WHERE any() TRAVERSE(0,3) (city = 'Rome')
Alternatively, you can write the above as:
SELECT FROM Profile LET $temp = (SELECT FROM (TRAVERSE * FROM $current WHILE $depth <= 3) WHERE city = 'Rome') WHERE $temp.size() > 0
Consider an example using the Graph Query, with the following schema:
Vertex edge Vertex User----->Friends----->User Label='f'
Find the first-level friends of the user with the Record ID
SELECT DISTINCT(in.lid) AS lid,distinct(in.fid) AS fid FROM (TRAVERSE outE(), inV() FROM #10:11 WHILE $depth <=1) WHERE @class = 'Friends'
By changing the depth to 3, you can find the second-level friends of the user:
SELECT distinct(in.lid) AS lid, distinct(in.fid) AS fid FROM (TRAVERSE outE(), inV() FROM #10:11 WHILE $depth <=3) WHERE @class = 'Friends'
For more information, see