SQL - `TRAVERSE`

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 `SELECT`, which can result in shorter and faster queries. For more information, see `TRAVERSE` versus `SELECT` below.

Syntax

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.
MAXDEPTH Defines the maximum depth of the traversal. 0 indicates that you only want to traverse the root node. Negative values are invalid.
WHILE Defines the condition for continuing the traversal while it is true.
LIMIT Defines the maximum number of results the command can return.
STRATEGY Defines strategy for traversing the graph.

NOTE: The use of the WHERE clause has been deprecated for this command.

NOTE: There is a difference between MAXDEPTH N and WHILE DEPTH <= N: the MAXDEPTH will evaluate exactly N levels, while the WHILE will evaluate N+1 levels and will discard the N+1th, so the MAXDEPTH in general has better performance.

Examples

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 #10:1234.

Traverse all fields in the root record:
```
orientdb> TRAVERSE * FROM #10:1234
```

Specify fields and depth up to the third level, using the BREADTH_FIRST strategy:

orientdb> TRAVERSE out("Friend") FROM #10:1234 MAXDEPTH 3 
          STRATEGY BREADTH_FIRST

Execute the same command, this time filtering for a minimum depth to exclude the first target vertex:
```
orientdb> SELECT FROM (TRAVERSE out("Friend") FROM #10:1234 MAXDEPTH 3) 
          WHERE $depth >= 1
```
NOTE: You can also define the maximum depth in the SELECT command, but it's much more efficient to set it at the inner TRAVERSE statement because the returning record sets are already filtered by depth.
Combine traversal with SELECT command to filter the result-set. Repeat the above example, filtering for users in Rome:
```
orientdb> SELECT FROM (TRAVERSE out("Friend") FROM #10:1234 MAXDEPTH 3) 
          WHERE city = 'Rome'
```

Extract movies of actors that have worked, at least once, in any movie produced by J.J. Abrams:

orientdb> SELECT FROM (TRAVERSE out("Actors"), out("Movies") FROM (SELECT FROM 
          Movie WHERE producer = "J.J. Abrams") MAXDEPTH 3) WHERE 
          @class = 'Movie'

Display the current path in the traversal:

orientdb> SELECT $path FROM ( TRAVERSE out() FROM V MAXDEPTH 10 )

Supported Variables

Fields

Defines the fields that you want to traverse. If set to *, any() or 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 to 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 Customer.

Field names are case-sensitive, classes not.

Target

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.

Context Variables

In addition to the above, you can use the following context variables in traversals:

$parent Gives the parent context, if any. You may find this useful when traversing from a sub-query.
$current Gives the current record in the iteration. To get the upper-level record in nested queries, you can use $parent.$current.
$depth Gives the current depth of nesting.
$path Gives a string representation of the current path. For instance, #5:0#.out. You can also display it through SELECT:
```
orientdb> SELECT $path FROM (TRAVERSE * FROM V)
```

Use Cases

`TRAVERSE` versus `SELECT`

When you already know traversal information, such as relationship names and depth-level, consider using SELECT instead of TRAVERSE as it is faster in some cases.

For example, this query traverses the follow relationship on Twitter accounts, getting the second level of friendship:

orientdb> SELECT FROM (TRAVERSE out('follow') FROM TwitterAccounts MAXDEPTH 2 )
          WHERE $depth = 2

But, you could also express this same query using SELECT operation, in a way that is also shorter and faster:

orientdb> SELECT out('follow').out('follow') FROM TwitterAccounts

`TRAVERSE` with the Graph Model and API

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() or outE('EdgeClassName'). That is, going out from a vertex and into the outgoing edges.
Vertex to incoming edges Using inE() or inE('EdgeClassName'). That is, going from a vertex and into the incoming edges.
Vertex to all edges Using bothE() or 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() or out('EdgeClassName'). This is the same as outE().inV()
Vertex to Vertex (incoming edges) Using in() or in('EdgeClassName'). This is the same as outE().inV()
Vertex to Vertex (all directions) Using both() or both('EdgeClassName').

For instance, traversing outgoing edges on the record #10:3434:

orientdb> 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 SentMessage:

orientdb> SELECT FROM (TRAVERSE outE(), inV() FROM (SELECT FROM User WHERE 
          name = 'Luca') MAXDEPTH 2 AND (@class = 'Message' or 
          (@class = 'SentMessage' AND sentOn = '01/01/2012') )) WHERE 
          @class = 'Message'

For more information, see

Java-Traverse page.

SQL Commands

OrientDB