Traversal
Follow the links between your records, from any starting record, to any depth you choose.
Syntax
Name the variables, the depth range, the direction, the start and the edge collection.
FOR v, e, p IN min..max OUTBOUND "gid://namespace/resource/id" name_edge
FOR v IN 1..3 INBOUND "gid://namespace/resource/id" name_edge
FOR v IN 1..2 ANY "gid://namespace/resource/id" name_edge
FOR v IN 1..2 OUTBOUND "gid://namespace/resource/id" GRAPH "name"Parameters and arguments
v, e, pNames for the vertex, the edge and the path, in that order. Choose any names. The vertex is required; the edge and path are optional
Required: Yesmin..maxThe depth range in whole numbers, such as
Required: Yes1..3. A depth above 10 is capped at 10. Depth counts steps from the start, so the first records are at depth 1, and a minimum of0or1returns the same recordsdirection
Required: YesOUTBOUNDfollows edges away from the start,INBOUNDfollows them towards it, andANYfollows bothstartThe quoted GID to start from, or a variable that holds one
Required: Yesedge collectionThe name of the edge collection, such as
Required: Yesplaced_by_edge, orschema.name_edge. OrGRAPH "name", which reads the defaultedgescollection and keeps the edges that the named graph's labels alloworder
Required: NoBFSorDFS. See BFS and DFSPRUNE …Stops following at a type of record. See Pruning
Required: No
Examples
Up to two steps outbound from an order. The content store holds no edges, so the answer shows the shape with no results.
Return type and behaviour
A traversal answers with startNode, direction, depth, resultCount and results. The depth is written as min..max after the cap, so 1..20 answers 1..10. Each result holds the vertex reached, the edge that reached it (gid, label, weight, metadata and provenance), its depth, the path (vertices, edges and weight) and the two ends' types, _from_type and _to_type.
A walk does not pass through the same record twice along one route, so a cycle in the data cannot make it run forever. Results are capped at 10,000 rows.
A start with no edges, or a collection that does not exist, returns resultCount: 0 and an empty results list.
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-1003 | The traversal is not written in HTQL's grammar | Check the range, the direction, the start and the edge collection |
HTQL-2012 | The edge collection's name is not in lower snake case | Write a name such as placed_by_edge |
Placement and context
A traversal is a statement of its own. PRUNE, a FILTER(…) and a RETURN follow the edge collection, in that order.
Limitations
- The depth is capped at 10.
- Only current edges are followed: an edge that has an end date is not.
- The edge collection's name is written in lower snake case, or as
schema.name. Any other form is refused.
Permissions and security
Edges classified above the caller's clearance are not followed.
Best practices
- Keep the depth small, and widen it only when the answer needs it.
- Start from one record.
- Use PRUNE to stop at a kind of record you do not need to pass.
- Name your edge collections for the relationship, so the statement reads as the question.