Traversal
From Neo4j Wiki
This page is in work right now. Don't consider it correct until this notice is deleted.
Contents |
[edit] Summary
- Traversals visit each node in the closure exactly once. For nodes with multiple paths only one path will be traversed.
- Traversals are lazy.
- Traversals need a transactional context and are done in the same thread.
- API reference
[edit] Traversal Java API Notes
The Node.traverse(...) methods creates a new Traverser object and positions it at the start node (the node on which the traverse method was invoked), then returns it immediately. The Traverser object traverses the graph lazily as the nodes are requested through its Iterator.
[edit] The Traverser object
Traversals are always executed in the same thread as the next() method of its iterator. This means that it is executed within the same transactional context as the code that iterates through the returnable nodes of the traversal. The implications of this is that iterating over a Traverser has to be done in the context of a transaction, and that a Traverser object is not safe to share between multiple threads.
The Traverser extends the Iterable interface to make it convenient to use in the Java for-each loop, but due to the fact that you sometimes want to be able to access the TraversalPosition of the current node, it is not possible to implement the Iterable interface to it's full extent. Usually the semantics of an Iterable is something that can be iterated through over and over again, often even with multiple simultaneous iterators, but a Traverser can only be iterated through once.
Traverser traverser = startNode.traverse( ... );
for ( Node node : traverser )
{
TraversalPosition currentPosition = traverser.currentPosition();
// Do something with the node and/or its position in the traversal
}
The object returned by traverser.currentPosition() is guaranteed to reflect the position of the last node returned by the iterator, even after the iterator has moved on to the next node. This means that in order to get the accurate current position you need to invoke traverser.currentPosition() within the loop, but on the other hand it also means that the TraversalPosition object can be kept around and used later on without having to deep copy it.
[edit] The ReturnableEvaluator callback
[edit] The StopEvaluator callback
[edit] TraversalPosition objects
- The depth() method returns the traversal depth of the position it represents. Note that the depth of a node is dependent on the traversal order, see the gotcha related to this.
- The returnedNodesCount() method returns the number of nodes that had been returned up until the point when the TraversalPosition object was created.
[edit] Traversal use cases
[edit] Extracting a subgraph
To extract a full subgraph including all the relationships between the included nodes, you can use a traverser to get the nodes, but will then have to use the different Node.getRelationships() methods to also get all relationships.
Depending on the exact use case you may have to deal with leaf and non-leaf nodes in different ways. For example, in a visualization you maybe want to include relationships between nodes at the maximum depth, even though that would exceed the maximum depth by one. This applies to a social network visualization, where end users may find it strange if two persons are visible in the graph, but not their (existing) connection!
