Query khop().src().depth() can find and return nodes that an initial-node can reach in K hops/steps the shortest, by specifying k-index (depth of shortest path), applying filters on the initial-node, all edges and all neighbor nodes. The number of result of subquery can be limited.

K-Hop is a basic concept in graph theory, when the conditions on nodes and edges are specified, the k-index of a node regarding the initial-node is either unique or non-existent. Ultipa implements K-Hop query using BFS (Breadth First Search) algorithm to guarantee the paths that reach the neighbors are the shortest.

(Yellow, green and blue nodes are the 1hop, 2hop and 3hop neighbors of the red node in the center)
K-Hop is a graph neighbor query function with an optimized and greatly improved performance, it is always suggested to use K-Hop instead of other path query methods when querying neighbor nodes.

Syntax:

• Statement alias: supported (NODE)
• Prefix: OPTIOANL (returns null for any subquery that finds no result)
• All parameters:

Sample graph: (to be used for the following examples)

create().edge_property(@default, "weight", int32)
insert().into(@default).nodes([{_id:"A", _uuid:1}, {_id:"B", _uuid:2}, {_id:"C", _uuid:3}, {_id:"D", _uuid:4}, {_id:"E", _uuid:5}, {_id:"F", _uuid:6}])
insert().into(@default).edges([{_uuid:1, _from_uuid:1, _to_uuid:3, weight:1}, {_uuid:2, _from_uuid:5, _to_uuid:2 , weight:1}, {_uuid:3, _from_uuid:1, _to_uuid:5 , weight:4}, {_uuid:4, _from_uuid:4, _to_uuid:3 , weight:2}, {_uuid:5, _from_uuid:5, _to_uuid:4 , weight:3}, {_uuid:6, _from_uuid:2, _to_uuid:1 , weight:2}, {_uuid:7, _from_uuid:6, _to_uuid:1 , weight:4}])

Filter Depth

Example: Find 3-Hop neighbors of node D, carry all properties

khop().src({_id == "D"}).depth(3) as n
return n{*}

| _id | _uuid |
|-----|-------|
| F   |   6   |

Example: Find 1~3-Hop neighbors of node D, carry all properties

khop().src({_id == "D"}).depth(:3) as n
return n{*}

| _id | _uuid |
|-----|-------|
| E   |   5   |
| C   |   3   |
| A   |   1   |
| B   |   2   |
| F   |   6   |

Analysis: khop() returns neighbor nodes from shallow to deep. Node C and E are from 1-Hop, node A and B are from 2-Hop, and node F is from 3-Hop.

Example: Find 2~3-Hop neighbors of node D, carry all properties

khop().src({_id == "D"}).depth(2:3) as n
return n{*}

| _id | _uuid |
|-----|-------|
| A   |   1   |
| B   |   2   |
| F   |   6   |

Filter Neighbor Nodes

Example: Find 3-Hop neighbors of node D, whose shortest path does not pass node E, carry all properties

khop().src({_id == "D"}).depth(3)
  .node_filter({_id != "E"}) as n
return n{*}

| _id | _uuid |
|-----|-------|
| B   |   2   |
| F   |   6   |

Analysis: When the shortest path are not allowed to pass node E, it is equivalent to removing node E and its adjacent edges 2, 3 and 5 from the graph, in which case node B moves to 3-Hop of node D.

Filter Edges

Example: Find 3-Hop neighbors of node D, whose shortest path does not pass edge 5, carry all properties

khop().src({_id == "D"}).depth(3)
  .edge_filter({_uuid != 5}) as n
return n{*}

| _id | _uuid |
|-----|-------|
| E   |   5   |
| B   |   2   |
| F   |   6   |

Analysis: When the shortest path are not allowed to pass edge 5, it is equivalent to removing edge 5 from the graph, in which case node E and B move to 3-Hop of node D.

Filter Edge Direction

Example: Find 1~2-Hop neighbors of node D, with all edges right-pointing, carry all properties

khop().src({_id == "D"}).depth(:2)
  .direction(right) as n
return n{*}

| _id | _uuid |
|-----|-------|
| C   |   3   |

Analysis: When all edges in the shortest path are right-pointing (outbound), node D has only one 1-Hop neighbor C, and has no neighbor from 2-Hop or deeper since node C has no outbound edge.

Example: Find 1~2-Hop neighbors of node D, with all edges left-pointing, carry all properties

khop().src({_id == "D"}).depth(:2)
  .direction(left) as n
return n{*}

| _id | _uuid |
|-----|-------|
| E   |   5   |
| A   |   1   |

Analysis: When all edges in the shortest path are left-pointing (inbound), node D has a 1-Hop neighbor E and a 2-Hop neighbor A.

limit()

Example: Find three 1~3-Hop neighbors of node D, carry all properties

khop().src({_id == "D"}).depth(:3).limit(3) as n
return n{*}

| _id | _uuid |
|-----|-------|
| E   |   5   |
| C   |   3   |
| A   |   1   |

OPTIONAL

Example: Find 2-Hop neighbors of node D, with all edges right-pointing, carry all properties; return null if no result

optional khop().src({_id == "D"}).depth(2)
  .direction(right) as n
return n{*}

null

Analysis: This query will give no return if not using OPTIONAL.