Traversal Framework

The Neo4j Traversal Framework Java API is a callback-based, lazily-executed way of specifying desired movements through a graph in Java. Some traversal examples can be found in Traversing a graph.

Main concepts

A traversal takes a start node on a graph and returns a set of paths representing the visited nodes and their relationships. Traversals are defined by a traversal description, which may contain the following elements:

Starting node — defines where the traversal begins.
Pathexpander — defines what to traverse, typically in terms of relationship direction and type.
Uniqueness — defines the restrictions of previously traversed nodes and relationships on the graph.
Evaluator — decides what to return and whether to stop or continue the traversal beyond its current position.
Order — defines in which order paths are expanded, for example, depth-first or breadth-first.

Using the Traversal Framework

The Traversal Framework can be used embedded in Java applications. It can also be used when extending Neo4j with a User-defined Procedure. For an example, see User-defined procedure with a Traversal Framework.

Traversal Framework vs Cypher

Although the Traversal Framework is less readable and more complex than the Cypher query language, it offers a powerful approach to traversing the graph. This is because the Traversal Framework can dynamically make custom choices at each step of the traversal, thus making the process more expressive and potentially more performant than Cypher.

Some of the advantages of using the Traversal Framework over Cypher include:

The Traversal Framework allows the use of any desired Java library to help in the evaluation of the traversal.
It allows customized pruning during the traversal of a path, which could potentially improve the performance of a traversal. See Evaluator for more information.
With Cypher, it is not possible to specify the order in which paths are expanded (e.g. depth-first). However, with the Traversal Framework, it is possible to specify the order of paths traversed.
With Cypher, relationships are only traversed when RELATIONSHIP_GLOBAL uniqueness is specified. By using the Traversal Framework, it is possible to specify the uniqueness constraints on the path traversed.

It is generally recommended to use Cypher wherever it is possible. However, when using the Traversal Framework, keep in mind that:

Cypher uses memory tracking that allows a query to be aborted if it occupies too much memory. However, when mixing Cypher with Java in the Traversal API (e.g. on a function), you may run out of memory.
Do not reuse objects fetched during a traversal in another transaction. Instead, use their IDs to fetch new ones.