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, p

    Names 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: Yes
  • min..max

    The depth range in whole numbers, such as 1..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 of 0 or 1 returns the same records

    Required: Yes
  • direction

    OUTBOUND follows edges away from the start, INBOUND follows them towards it, and ANY follows both

    Required: Yes
  • start

    The quoted GID to start from, or a variable that holds one

    Required: Yes
  • edge collection

    The name of the edge collection, such as placed_by_edge, or schema.name_edge. Or GRAPH "name", which reads the default edges collection and keeps the edges that the named graph's labels allow

    Required: Yes
  • order

    BFS or DFS. See BFS and DFS

    Required: No
  • PRUNE …

    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
ErrorWhat happenedHow to recover
HTQL-1003The traversal is not written in HTQL's grammarCheck the range, the direction, the start and the edge collection
HTQL-2012The edge collection's name is not in lower snake caseWrite 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.