path
The path
module allows users to explore different paths, filter relationships, and nodes based on specific criteria, and achieve more complex path-related tasks that go beyond the capabilities of native Cypher - whether you're seeking all possible paths between two nodes, subgraphs that meet certain conditions, or various other path-oriented operations.
Trait | Value |
---|---|
Module type | algorithm |
Implementation | C++ |
Graph direction | directed/undirected |
Edge weights | weighted/unweighted |
Parallelism | sequential |
Procedures
You can execute this algorithm on graph projections, subgraphs or portions of the graph.
create(start_node, relationships)
Creates a path from the given starting node and a list of relationships. Iteratively appends all relationships in the list to the new path until a relationship is null (as a result of optional match) or a relationship from the last node of the path to one of the nodes in the current relationship (the one that isn't the last one in the path) doesn't exist.
Input:
start_node: Node
- the starting node of the path.relationships: Map
- map with the keyrel
that contains a list of the given relationships. Seeusage
for more details.
Output:
path: Path
- the created path.
Usage:
MERGE (croatia:Country {name: 'Croatia'})
MERGE (madrid:City {name: 'Madrid'})
MERGE (kutina:City {name: 'Kutina'})
MERGE (real:Club {name: 'Real Madrid'})
MERGE (moslavina:Club {name: 'NK Moslavina'})
MERGE (kutina)-[:In_country]->(croatia)
MERGE (moslavina)-[:In_city]->(kutina)
MERGE (real)-[:In_city]->(madrid);
MATCH (club:Club) OPTIONAL MATCH (club)-[inCity:In_city]->(city:City) OPTIONAL MATCH (city)-[inCountry:In_country]->(:Country) CALL path.create(club, {rel:[inCity, inCountry]}) YIELD path return path;
+------------------------------------------------------------------------------------------------------------------+
| path |
+------------------------------------------------------------------------------------------------------------------+
| (:Club {name: 'Real Madrid'}-[:In_city]->(:City {name 'Madrid'})) |
+------------------------------------------------------------------------------------------------------------------+
| (:Club {name: 'NK Moslavina'}-[:In_city]->(:City {name 'Kutina'})-[:In_country]->(:Country {name 'Croatia'})) |
+------------------------------------------------------------------------------------------------------------------+
expand(start, relationships, labels, min_hops, max_hops)
Expand from the start node(s) following the given relationships and label filters, from min to max number of allowed hops. Return all paths inside the allowed number of hops, which satisfy relationship and label filters.
Input:
start: any
➡ node, node ID, or list of nodes and/or node IDs from which the function will expand.relationships: List[string]
➡ list of relationships which the expanding will follow.labels: List[string]
➡ list of labels which will define filtering.min_hops: int
➡ minimum number of hops for a path to be returned.max_hops: int
➡ maximum number of hops for a path to be returned.
Relationship filters:
Relationship filters are described in the table below:
Option | Explanation |
---|---|
TYPE | Path will expand with both outgoing and incoming relationships of this type. |
<TYPE | Path will expand with incoming relationships of this type. |
TYPE> | Path will expand with outgoing relationships of this type. |
> | Path will expand with all outgoing relationships. |
< | Path will expand will all incoming relationships. |
Anything else will result in an exception.
If the relationship filter is empty, all relationship types are allowed.
Relationship filtering examples:
Relationship list : [<LOVES, >]
: path will expand on all outgoing relationships, and incoming relationshipLOVES
.Relationship list : [<LOVES, LOVES]
: path will expand on incoming relationshipLOVES
, and all directions of relationshipLOVES
, making the first element in the relationship list functionally obsolete.Relationship list : []
: path will expand on all relationships.
Label filter:
Label filters are described in the table below:
Option | Explanation |
---|---|
+LABEL | Label is added to the whitelist. All nodes in the path must have a label in the whitelist. If the whitelist is empty, it is as if all nodes are whitelisted. |
>LABEL | Label is added to the end list. When end list has labels, only paths ending with these labels will be returned, but they can be expanded further, to return paths ending in nodes with end labels beyond it, but the expansion will only go through nodes with whitelisted labels. Labels in the end list do not have to respect the whitelist. |
-LABEL | Label is added to the blacklist. No node in the path will contain labels in the blacklist. The blacklist takes precedence over all other filters. |
/LABEL | Label is added to the termination list. When termination list contains labels, only paths ending with these labels will be returned, and any further expansion is stopped. Labels in the termination list do not have to respect the whitelist. |
Any other label syntax is added to the whitelist. For example, LABEL
will be added to the whitelist as LABEL
, and !LABEL
will be added to the whitelist as !LABEL
. NOTE: when deciding where the label will be added, it is done by looking at the first element of the label. For example, >LABEL>
will be added to the end list as LABEL>
.
Label filtering examples:
Consider the graph provided in the usage section below. In this subsection, number of hops will be limited from 0 to 2, and the starting node will be Dog
.
-
Label list: ["/Mouse"]
- this will return all the paths ending withMouse
. Because no labels were added to the whitelist, all labels are considered whitelisted. This filtering will return 3 paths:Dog->Cat->Mouse
,Dog<-Human->Mouse
,Dog->Mouse
. -
Label list: ["/Mouse", "Cat"]
- now, labelCat
is added to the whitelist, becoming the only whitelisted label. The meaning of the filter can now be represented as:"return all paths ending with Mouse, which expand through Cat and Cat only"
. This filtering will return two paths, one whereDog
connects to theMouse
directly(Dog->Mouse
), and one whereCat
is included(Dog->Cat->Mouse
). -
Label list: ["/Mouse", "-Cat", "-Human"]
- now, bothCat
andHuman
are blacklisted, and there is only one eligible path that can reachMouse
:Dog->Mouse
.
For the final example, the starting node will be Cat
, and the maximum number of hops will be increased to 4.
Label list: [">Dog", "+Human", "+Wolf"]
- now, only paths ending withDog
will be returned, but they can be further expaned through the nodes with whitelisted labels. This filtering returns 3 paths:Cat<-Dog
,Cat<-Dog<-Human->Wolf->Dog
,Cat<-Dog<-Wolf<-Human->Dog
.
Output:
result: Path
➡ all paths expanded from the start node.
Usage:
In this section, usage with Cypher will be demonstrated.
Graph used in examples
This is the graph used in the examples.
CREATE (w:Wolf)-[ca:CATCHES]->(d:Dog), (c:Cat), (m:Mouse), (h:Human);
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
WITH w, d, c, m, h
CREATE (d)-[:CATCHES]->(c)
CREATE (c)-[:CATCHES]->(m)
CREATE (d)-[:FRIENDS_WITH]->(m)
CREATE (h)-[:OWNS]->(d)
CREATE (h)-[:HUNTS]->(w)
CREATE (h)-[:HATES]->(m);
Usage example 1
Expand from Dog
on outgoing relationship CATCHES
and incoming relationship HATES
, with Mouse
and Human
being labels in end list. Whitelist is empty, hence, all labels are whitelisted.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.expand(d,["CATCHES>","<HATES"],[">Mouse", ">Human"],0,4) YIELD result RETURN result;
result |
---|
{"nodes":[{"id":1,"labels":["Dog"],"properties":{},"type":"node"},{"id":2,"labels":["Cat"],"properties":{},"type":"node"},{"id":3,"labels":["Mouse"],"properties":{},"type":"node"}],"relationships":[{"id":1,"start":1,"end":2,"label":"CATCHES","properties":{},"type":"relationship"},{"id":2,"start":2,"end":3,"label":"CATCHES","properties":{},"type":"relationship"}],"type":"path"} |
{"nodes":[{"id":1,"labels":["Dog"],"properties":{},"type":"node"},{"id":2,"labels":["Cat"],"properties":{},"type":"node"},{"id":3,"labels":["Mouse"],"properties":{},"type":"node"},{"id":4,"labels":["Human"],"properties":{},"type":"node"}],"relationships":[{"id":1,"start":1,"end":2,"label":"CATCHES","properties":{},"type":"relationship"},{"id":2,"start":2,"end":3,"label":"CATCHES","properties":{},"type":"relationship"},{"id":6,"start":4,"end":3,"label":"HATES","properties":{},"type":"relationship"}],"type":"path"} |
Usage example 2
Expand from Dog
only on incoming relationships. Also, Human
is blacklisted.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.expand(d,["<"],["-Human"],0,4) YIELD result RETURN result;
result |
---|
{"nodes":[{"id":1,"labels":["Dog"],"properties":{},"type":"node"},{"id":0,"labels":["Wolf"],"properties":{},"type":"node"}],"relationships":[{"id":0,"start":0,"end":1,"label":"CATCHES","properties":{},"type":"relationship"}],"type":"path"} |
Usage example 3
Expand from Dog
and Mouse
. Cat
is the termination label, and the maximum number of hops is 1. Also, mouse is passed as ID, to demonstrate that capability of expand function.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.expand([d, id(m)],[],["/Cat"],0,1) YIELD result RETURN result;
result |
---|
{"nodes":[{"id":1,"labels":["Dog"],"properties":{},"type":"node"},{"id":2,"labels":["Cat"],"properties":{},"type":"node"}],"relationships":[{"id":1,"start":1,"end":2,"label":"CATCHES","properties":{},"type":"relationship"}],"type":"path"} |
{"nodes":[{"id":3,"labels":["Mouse"],"properties":{},"type":"node"},{"id":2,"labels":["Cat"],"properties":{},"type":"node"}],"relationships":[{"id":2,"start":2,"end":3,"label":"CATCHES","properties":{},"type":"relationship"}],"type":"path"} |
subgraph_all(start_node, config)
Returns a subgraph in a form of nodes and relationships that can be reached from a given start node. While traversing the graph, the function evaluates nodes based on specified criteria: it adheres to a maximum hop limit, applies relationship and label filters, and ensures each node is visited only once.
Input:
start_node: Any
➡ node, node ID, or list of nodes and/or node IDs from which the traversing will start.config: Map (default={})
➡ configuration parameters explained below.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
minLevel | Int | 0 | The minimum number of hops in the traversal. Set to 0 if the start node should be included in the subgraph, or 1 otherwise. |
maxLevel | Int | -1 | The maximum number of hops in the traversal. |
relationshipFilter | List | [ ] | List of relationships which the subgraph formation will follow. Explained in detail below. |
labelFilter | List | [ ] | List of labels which will define filtering. Explained in detail below. |
filterStartNode | Bool | False | Whether the labelFilter applies to the start nodes. |
Relationship filters:
Relationship filters are described in the table below:
Option | Explanation |
---|---|
TYPE | Path will expand with both outgoing and incoming relationships of this type. |
<TYPE | Path will expand with incoming relationships of this type. |
TYPE> | Path will expand with outgoing relationships of this type. |
> | Path will expand with all outgoing relationships. |
< | Path will expand will all incoming relationships. |
Anything else will result in an exception.
If the relationship filter is empty, all relationship types are allowed.
Relationship filtering examples:
Relationship list : [<LOVES, >]
: path will expand on all outgoing relationships, and incoming relationshipLOVES
.Relationship list : [<LOVES, LOVES]
: path will expand on incoming relationshipLOVES
, and all directions of relationshipLOVES
, making the first element in the relationship list functionally obsolete.Relationship list : []
: path will expand on all relationships.
Label filters:
Label filters are described in the table below:
Option | Explanation |
---|---|
+LABEL | Label is added to the whitelist. All nodes in the path must have a label in the whitelist. If the whitelist is empty, it is as if all nodes are whitelisted. |
>LABEL | Label is added to the end list. When end list has labels, only paths ending with these labels will be returned, but they can be expanded further, to return paths ending in nodes with end labels beyond it, but the expansion will only go through nodes with whitelisted labels. Labels in the end list do not have to respect the whitelist. |
-LABEL | Label is added to the blacklist. No node in the path will contain labels in the blacklist. The blacklist takes precedence over all other filters. |
/LABEL | Label is added to the termination list. When termination list contains labels, only paths ending with these labels will be returned, and any further expansion is stopped. Labels in the termination list do not have to respect the whitelist. |
Any other label syntax is added to the whitelist. For example, LABEL
will be added to the whitelist as LABEL
, and !LABEL
will be added to the whitelist as !LABEL
. NOTE: when deciding where the label will be added, it is done by looking at the first element of the label. For example, >LABEL>
will be added to the end list as LABEL>
.
Label filtering examples:
Consider the graph provided in the usage section below. In this subsection, number of hops will be limited from 0 to 2, and the starting node will be Dog
.
-
Label list: ["/Mouse"]
- this will return all the paths ending withMouse
. Because no labels were added to the whitelist, all labels are considered whitelisted. This filtering will return 3 paths:Dog->Cat->Mouse
,Dog<-Human->Mouse
,Dog->Mouse
. -
Label list: ["/Mouse", "Cat"]
- now, labelCat
is added to the whitelist, becoming the only whitelisted label. The meaning of the filter can now be represented as:"return all paths ending with Mouse, which expand through Cat and Cat only"
. This filtering will return two paths, one whereDog
connects to theMouse
directly(Dog->Mouse
), and one whereCat
is included(Dog->Cat->Mouse
). -
Label list: ["/Mouse", "-Cat", "-Human"]
- now, bothCat
andHuman
are blacklisted, and there is only one eligible path that can reachMouse
:Dog->Mouse
.
For the final example, the starting node will be Cat
, and the maximum number of hops will be increased to 4.
Label list: [">Dog", "+Human", "+Wolf"]
- now, only paths ending withDog
will be returned, but they can be further expaned through the nodes with whitelisted labels. This filtering returns 3 paths:Cat<-Dog
,Cat<-Dog<-Human->Wolf->Dog
,Cat<-Dog<-Wolf<-Human->Dog
.
Output:
nodes: List[Node]
➡ list of nodes which form the subgraph.rels: List[Relationship]
➡ list of relationships which form the subgraph.
Usage:
In this section, usage with Cypher will be demonstrated.
Graph used in examples
This is the graph used in the examples.
CREATE (w:Wolf)-[ca:CATCHES]->(d:Dog), (c:Cat), (m:Mouse), (h:Human);
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
WITH w, d, c, m, h
CREATE (d)-[:CATCHES]->(c)
CREATE (c)-[:CATCHES]->(m)
CREATE (d)-[:FRIENDS_WITH]->(m)
CREATE (h)-[:OWNS]->(d)
CREATE (h)-[:HUNTS]->(w)
CREATE (h)-[:HATES]->(m);
Usage example 1
Create a subgraph from Dog
on outgoing relationship CATCHES
and incoming
relationship HATES
, with Mouse
and Human
being labels in end list.
Whitelist is empty, hence, all labels are whitelisted.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.subgraph_all(d, {
relationshipFilter: ["CATCHES>","<HATES"],
labelFilter: [">Mouse", ">Human"],
minLevel: 0,
maxLevel: 4
})
YIELD nodes, rels
RETURN nodes, rels;
The results should be identical to the ones below, except for the id
values that depend on the internal database id
values.
+----------------------------+----------------------------+
| nodes | rels |
+----------------------------+----------------------------+
| { | { |
| "id": 3, | "id": 6, |
| "labels": [ | "start": 4, |
| "Mouse" | "end": 3, |
| ], | "label": "HATES", |
| "properties": {}, | "properties": {}, |
| "type": "node" | "type": "relationship" |
| } | } |
+----------------------------+----------------------------+
| { | |
| "id": 4, | |
| "labels": [ | |
| "Human" | |
| ], | |
| "properties": {}, | |
| "type": "node" | |
| } | |
+----------------------------+----------------------------+
Usage example 2
Create subgraph from Dog
only on incoming relationships. Also, Human
is blacklisted.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.subgraph_all(d, {
relationshipFilter: ["<"],
labelFilter: ["-Human"],
minLevel: 0,
maxLevel: 4
})
YIELD nodes, rels
RETURN nodes, rels;
The results should be identical to the ones below, except for the id
values that depend on the internal database id
values.
+----------------------------+----------------------------+
| nodes | rels |
+----------------------------+----------------------------+
| { | { |
| "id": 1, | "id": 0, |
| "labels": [ | "start": 0, |
| "Dog" | "end": 1, |
| ], | "label": "CATCHES", |
| "properties": {}, | "properties": {}, |
| "type": "node" | "type": "relationship" |
| } | } |
+----------------------------+----------------------------+
| { | |
| "id": 0, | |
| "labels": [ | |
| "Wolf" | |
| ], | |
| "properties": {}, | |
| "type": "node" | |
| } | |
+----------------------------+----------------------------+
subgraph_nodes(start_node, config)
Returns a subgraph in a form of only nodes that can be reached from a given start node. While traversing the graph, the function evaluates nodes based on specified criteria: it adheres to a maximum hop limit, applies relationship and label filters, and ensures each node is visited only once.
Input:
start_node: Any
➡ node, node ID, or list of nodes and/or node IDs from which the traversing will start.config: Map (default={})
➡ configuration parameters explained below.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
minLevel | Int | 0 | The minimum number of hops in the traversal. Set to 0 if the start node should be included in the subgraph, or 1 otherwise. |
maxLevel | Int | -1 | The maximum number of hops in the traversal. |
relationshipFilter | List | [ ] | List of relationships which the subgraph formation will follow. Explained in detail below. |
labelFilter | List | [ ] | List of labels which will define filtering. Explained in detail below. |
filterStartNode | Bool | False | Whether the labelFilter applies to the start nodes. |
Relationship filters:
Relationship filters are described in the table below:
Option | Explanation |
---|---|
TYPE | Path will expand with both outgoing and incoming relationships of this type. |
<TYPE | Path will expand with incoming relationships of this type. |
TYPE> | Path will expand with outgoing relationships of this type. |
> | Path will expand with all outgoing relationships. |
< | Path will expand will all incoming relationships. |
Anything else will result in an exception.
If the relationship filter is empty, all relationship types are allowed.
Relationship filtering examples:
Relationship list : [<LOVES, >]
: path will expand on all outgoing relationships, and incoming relationshipLOVES
.Relationship list : [<LOVES, LOVES]
: path will expand on incoming relationshipLOVES
, and all directions of relationshipLOVES
, making the first element in the relationship list functionally obsolete.Relationship list : []
: path will expand on all relationships.
Label filter:
Label filters are described in the table below:
Option | Explanation |
---|---|
+LABEL | Label is added to the whitelist. All nodes in the path must have a label in the whitelist. If the whitelist is empty, it is as if all nodes are whitelisted. |
>LABEL | Label is added to the end list. When end list has labels, only paths ending with these labels will be returned, but they can be expanded further, to return paths ending in nodes with end labels beyond it, but the expansion will only go through nodes with whitelisted labels. Labels in the end list do not have to respect the whitelist. |
-LABEL | Label is added to the blacklist. No node in the path will contain labels in the blacklist. The blacklist takes precedence over all other filters. |
/LABEL | Label is added to the termination list. When termination list contains labels, only paths ending with these labels will be returned, and any further expansion is stopped. Labels in the termination list do not have to respect the whitelist. |
Any other label syntax is added to the whitelist. For example, LABEL
will be added to the whitelist as LABEL
, and !LABEL
will be added to the whitelist as !LABEL
. NOTE: when deciding where the label will be added, it is done by looking at the first element of the label. For example, >LABEL>
will be added to the end list as LABEL>
.
Label filtering examples:
Consider the graph provided in the usage section below. In this subsection, number of hops will be limited from 0 to 2, and the starting node will be Dog
.
-
Label list: ["/Mouse"]
- this will return all the paths ending withMouse
. Because no labels were added to the whitelist, all labels are considered whitelisted. This filtering will return 3 paths:Dog->Cat->Mouse
,Dog<-Human->Mouse
,Dog->Mouse
. -
Label list: ["/Mouse", "Cat"]
- now, labelCat
is added to the whitelist, becoming the only whitelisted label. The meaning of the filter can now be represented as:"return all paths ending with Mouse, which expand through Cat and Cat only"
. This filtering will return two paths, one whereDog
connects to theMouse
directly(Dog->Mouse
), and one whereCat
is included(Dog->Cat->Mouse
). -
Label list: ["/Mouse", "-Cat", "-Human"]
- now, bothCat
andHuman
are blacklisted, and there is only one eligible path that can reachMouse
:Dog->Mouse
.
For the final example, the starting node will be Cat
, and the maximum number of hops will be increased to 4.
Label list: [">Dog", "+Human", "+Wolf"]
- now, only paths ending withDog
will be returned, but they can be further expaned through the nodes with whitelisted labels. This filtering returns 3 paths:Cat<-Dog
,Cat<-Dog<-Human->Wolf->Dog
,Cat<-Dog<-Wolf<-Human->Dog
.
Output:
nodes: Node
➡ nodes which form the subgraph.
Usage:
In this section, usage with Cypher will be demonstrated.
Graph used in examples
This is the graph used in the examples.
CREATE (w:Wolf)-[ca:CATCHES]->(d:Dog), (c:Cat), (m:Mouse), (h:Human);
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
WITH w, d, c, m, h
CREATE (d)-[:CATCHES]->(c)
CREATE (c)-[:CATCHES]->(m)
CREATE (d)-[:FRIENDS_WITH]->(m)
CREATE (h)-[:OWNS]->(d)
CREATE (h)-[:HUNTS]->(w)
CREATE (h)-[:HATES]->(m);
Usage example 1
Create a subgraph from Dog
on outgoing relationship CATCHES
and incoming relationship HATES
, with Mouse
and Human
being labels in end list. Whitelist is empty, hence, all labels are whitelisted.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.subgraph_nodes(d, {
relationshipFilter: ["CATCHES>","<HATES"],
labelFilter: [">Mouse", ">Human"],
minLevel: 0,
maxLevel: 4
})
YIELD nodes
RETURN nodes;
The results should be identical to the ones below, except for the id
values that depend on the internal database id
values.
+----------------------------+
| nodes |
+----------------------------+
| { |
| "id": 3, |
| "labels": [ |
| "Mouse" |
| ], |
| "properties": {}, |
| "type": "node" |
| } |
+----------------------------+
| { |
| "id": 4, |
| "labels": [ |
| "Human" |
| ], |
| "properties": {}, |
| "type": "node" |
| } |
+----------------------------+
Usage example 2
Create subgraph from Dog
only on incoming relationships. Also, Human
is blacklisted.
MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human)
CALL path.subgraph_nodes(d, {
relationshipFilter: ["<"],
labelFilter: ["-Human"],
minLevel: 0,
maxLevel: 4
})
YIELD nodes
RETURN nodes
The results should be identical to the ones below, except for the id
values that depend on the internal database id
values.
+----------------------------+
| nodes |
+----------------------------+
| { |
| "id": 1, |
| "labels": [ |
| "Dog" |
| ], |
| "properties": {}, |
| "type": "node" |
| } |
+----------------------------+
| { |
| "id": 0, |
| "labels": [ |
| "Wolf" |
| ], |
| "properties": {}, |
| "type": "node" |
| } |
+----------------------------+