K-Hop template khop().<path_template> employs a path template of fixed length as shortest path when querying for k-hop neighbors. It is a batch processing of k-hop query for each initial-node found by the 1st n(), and its parameter limit() is limiting the number of neighbors of each initial-node in each subquery, but not that of all initial nodes of each subquery.

Upon achieving the same query function, K-Hop template yields better performance than path template.

Syntax:

• Statement alias: supported (NODE)
• Prefix: OPTIOANL (returns null for any subquery that finds no result)
• The 1st n() for initial-node must have filtering rules
• [<steps>] in multi-edge template must be a definite value, namely [N]
• Inter-step filtering of any type is not supported, no matter using prev_n, prev_e or preceding custom alias defined in the current path template

For instance, the khop() query introduced in previous article is unable to describe such 3-step paths where the nodes and edges each has different filtering condition. But a KHop template will do:

khop()
  .n({_id in ["C001","C002"]}).re({@has}).n({@acct})
  .re({@use}).n({@phone})
  .le({@use}).n({@acct}) as n

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

create().node_schema("country").node_schema("movie").node_schema("director").edge_schema("filmedIn").edge_schema("direct")
create().node_property(@*, "name")
insert().into(@country).nodes([{_id:"C001", _uuid:1, name:"France"}, {_id:"C002", _uuid:2, name:"USA"}])
insert().into(@movie).nodes([{_id:"M001", _uuid:3, name:"Léon"}, {_id:"M002", _uuid:4, name:"The Terminator"}, {_id:"M003", _uuid:5, name:"Avatar"}])
insert().into(@director).nodes([{_id:"D001", _uuid:6, name:"Luc Besson"}, {_id:"D002", _uuid:7, name:"James Cameron"}])
insert().into(@filmedIn).edges([{_uuid:1, _from_uuid:3, _to_uuid:1}, {_uuid:2, _from_uuid:4, _to_uuid:1}, {_uuid:3, _from_uuid:3, _to_uuid:2}, {_uuid:4, _from_uuid:4, _to_uuid:2}, {_uuid:5, _from_uuid:5, _to_uuid:2}])
insert().into(@direct).edges([{_uuid:6, _from_uuid:6, _to_uuid:3}, {_uuid:7, _from_uuid:7, _to_uuid:4}, {_uuid:8, _from_uuid:7, _to_uuid:5}])

Batch KHop

Example: Find neighbors of each country reached through 2-step shortest paths @country-@movie-@director, return the table of country name and director name

khop()
  .n({@country} as a).le({@filmedIn}).n({@movie})
  .le({@direct}).n({@director}) as b
return table(a.name, b.name)

| a.name |     b.name    |
|--------|---------------|
| France | Luc Besson    |
| France | James Cameron |
| USA    | Luc Besson    |
| USA    | James Cameron |

limit()

Example: Find one neighbor of each country reached through 2-step shortest paths @country-@movie-@director, return the table of country name and director name

khop()
  .n({@country} as a).le({@filmedIn}).n({@movie})
  .le({@direct}).n({@director}).limit(1) as b
return table(a.name, b.name)

| a.name |   b.name   |
|--------|------------|
| France | Luc Besson |
| USA    | Luc Besson |

OPTIONAL

Example: Find neighbors of each country reached through 3-step shortest paths @country-@movie-@country-@movie, return the table of country name and director name; return null for subquery if no return

find().nodes({@country}) as a
optional khop()
  .n(a).le({@filmedIn}).n({@movie})
  .re({@filmedIn}).n({@country})
  .le({@filmedIn}).n({@movie}) as b
return table(a.name, b.name)

| a.name | b.name |
|--------|--------|
| France | Avatar |
| USA    | null   |

Analysis: The 2nd row of table will not be returned if not using OPTIONAL.