K-Hop Template

Overview

The k-hop template clause khop().n()...n() utilizes a path template to query for k-hop neighbors of the start nodes in the paths.

With the defined path template, the value of k depends on the shortest distance between two nodes, same as explained in the k-hop clause. Additionally, the returned nodes must satisfy the condition set for the destination nodes in the path template.

K-Hop vs. K-Hop Template

Path Template vs. K-Hop Template

While achieving the same query function, the K-Hop template generally offers better performance than the path template.

For example, the two UQLs return the same results - the number of distinct ads clicked by a user. It's important to note that the destination nodes returned by the path template are not automatically deduplicated, whereas the results of the k-hop template are deduplicated.

UQL
// Path Template
n({_id == "u316591"}).e({@clicks}).n({@ad} as ads)
return count(DISTINCT ads)

// K-Hop Template
khop().n({_id == "u316591"}).e({@clicks}).n({@ad}) as ads
with count(ads)

Syntax

• Clause alias: NODE type
• Regarding the path template:
  • The initial n() must have a valid filter which can specify multiple nodes.
  • The [<steps>] in multi-edge templates e()[<steps>] and e().nf()[<steps>] don't support the format of [*:N], as the k-hop query automatically traverses through the shortest paths.
  • Inter-step filtering is not supported, whether using system alias (prev_n, prev_e) or custom alias.
• Methods:

Examples

Example Graph

Run these UQLs row by row in an empty graphset to create this graph:

UQL
create().node_schema("country").node_schema("movie").node_schema("director").node_schema("actor").edge_schema("filmedIn").edge_schema("direct").edge_schema("cast").edge_schema("bornIn")
create().node_property(@*, "name")
Click to expand

Set Fixed-Length Path

Find the 2-hop neighbors of each country that can be reached through a certain path.

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

Result:

Set Non-Fixed-Length Path

Find the 1- and 2-hop neighbors of each country that can be reached through a certain path.

UQL
khop().n({@country} as a).e({!@direct})[:2].n({!@country}) as b
return table(a.name, b.name)

Result:

Destination Node Filtering

Find the 2-hop @director neighbors of each country.

UQL
khop().n({@country} as a).e()[2].n({@director}) as b
return table(a.name, b.name)

Result:

Take the Shortest Path

Find the 2-hop @country neighbors of one actor.

UQL
khop().n({@actor.name == "Zoe Saldaña"}).e()[2].n({@country}) as a return a

Result: No return data.

Even though there exists a 2-step path from the actor to a country (Zoe Saldaña - [@cast] - Avatar - [filmedIn]- USA), that's not the shortest path (Zoe Saldaña - [@bornIn] - USA) between them.

Use limit()

Find one 1-hop neighbor for each director that can be reached through a certain path.

UQL
khop().n({@director} as a).e({@direct}).n().limit(1) as b
return table(a.name, b.name)

Result:

Use OPTIONAL

Find the 2-hop @actor neighbors of each country that can be reached through a certain path. Return null if no neighbors are found.

UQL
find().nodes({@country}) as cty
optional khop().n(cty).e({!@bornIn})[2].n({@actor}) as actor
return table(cty.name, actor.name)

Result: