diff --git a/mage/data/query-modules/cpp/path/graph.png b/mage/data/query-modules/cpp/path/graph.png new file mode 100644 index 00000000000..0f59e799b85 Binary files /dev/null and b/mage/data/query-modules/cpp/path/graph.png differ diff --git a/mage/data/query-modules/cpp/path/graph_usage1.png b/mage/data/query-modules/cpp/path/graph_usage1.png new file mode 100644 index 00000000000..fb2388b6ee9 Binary files /dev/null and b/mage/data/query-modules/cpp/path/graph_usage1.png differ diff --git a/mage/data/query-modules/cpp/path/graph_usage2.png b/mage/data/query-modules/cpp/path/graph_usage2.png new file mode 100644 index 00000000000..02f2671cadf Binary files /dev/null and b/mage/data/query-modules/cpp/path/graph_usage2.png differ diff --git a/mage/data/query-modules/cpp/path/graph_usage3.png b/mage/data/query-modules/cpp/path/graph_usage3.png new file mode 100644 index 00000000000..8a37ad910dd Binary files /dev/null and b/mage/data/query-modules/cpp/path/graph_usage3.png differ diff --git a/mage/data/query-modules/cpp/path/subgraphall1.png b/mage/data/query-modules/cpp/path/subgraphall1.png new file mode 100644 index 00000000000..564ad2178c7 Binary files /dev/null and b/mage/data/query-modules/cpp/path/subgraphall1.png differ diff --git a/mage/data/query-modules/cpp/path/subgraphall2.png b/mage/data/query-modules/cpp/path/subgraphall2.png new file mode 100644 index 00000000000..d57d77998f2 Binary files /dev/null and b/mage/data/query-modules/cpp/path/subgraphall2.png differ diff --git a/mage/data/query-modules/cpp/path/subgraphnodes1.png b/mage/data/query-modules/cpp/path/subgraphnodes1.png new file mode 100644 index 00000000000..aa87745c5c4 Binary files /dev/null and b/mage/data/query-modules/cpp/path/subgraphnodes1.png differ diff --git a/mage/data/query-modules/cpp/path/subgraphnodes2.png b/mage/data/query-modules/cpp/path/subgraphnodes2.png new file mode 100644 index 00000000000..8fa8442da3f Binary files /dev/null and b/mage/data/query-modules/cpp/path/subgraphnodes2.png differ diff --git a/mage/query-modules/cpp/path.md b/mage/query-modules/cpp/path.md new file mode 100644 index 00000000000..6f0bbaa067d --- /dev/null +++ b/mage/query-modules/cpp/path.md @@ -0,0 +1,801 @@ +--- +id: path +title: path +sidebar_label: path +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import RunOnSubgraph from '../../templates/_run_on_subgraph.mdx'; + +export const Highlight = ({children, color}) => ( + +{children} + +); + +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. + +[![docs-source](https://img.shields.io/badge/source-path-FB6E00?logo=github&style=for-the-badge)](https://github.com/memgraph/mage/tree/main/cpp/path_module) + +| Trait | Value | +| ------------------- | ----------------------------------------------------- | +| **Module type** | **algorithm** | +| **Implementation** | **C++** | +| **Graph direction** | **directed**/**undirected** | +| **Edge weights** | **weighted**/**unweighted** | +| **Parallelism** | **sequential** | + +### Procedures + +### `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 key `rel` that contains a list of the given relationships. See `usage` for more details. + +#### Output + +- `path: Path` - the created path. + +#### Usage + +```cypher + +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); +``` +```cypher +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; +``` + +```plaintext ++------------------------------------------------------------------------------------------------------------------+ +| 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. | +| `` | 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 : []` : path will expand on all outgoing relationships, and incoming relationship `LOVES`. +- `Relationship list : [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 with `Mouse`. 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, label `Cat` 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 where `Dog` connects to the `Mouse` directly(`Dog->Mouse`), and one where `Cat` is included(`Dog->Cat->Mouse`). + +- `Label list: ["/Mouse", "-Cat", "-Human"]` - now, both `Cat` and `Human` are blacklisted, and there is only one eligible path that can reach `Mouse`: `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 with `Dog` 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. + + + + + +```cypher +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. + + + + + + +```cypher +MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human) +CALL path.expand(d,["CATCHES>","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. + + + + + +```cypher +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. + + + + + +```cypher +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. | +| `` | 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 : []` : path will expand on all outgoing relationships, and incoming relationship `LOVES`. +- `Relationship list : [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 with `Mouse`. 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, label `Cat` 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 where `Dog` connects to the `Mouse` directly(`Dog->Mouse`), and one where `Cat` is included(`Dog->Cat->Mouse`). + +- `Label list: ["/Mouse", "-Cat", "-Human"]` - now, both `Cat` and `Human` are blacklisted, and there is only one eligible path that can reach `Mouse`: `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 with `Dog` 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. + + + + + +```cypher +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. + + + + + +```cypher +MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human) +CALL path.subgraph_all(d, { + relationshipFilter: ["CATCHES>","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. + +```plaintext + +----------------------------+----------------------------+ + | 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. + + + + + +```cypher +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. + + +```plaintext + +----------------------------+----------------------------+ + | 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. | +| `` | 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 : []` : path will expand on all outgoing relationships, and incoming relationship `LOVES`. +- `Relationship list : [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 with `Mouse`. 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, label `Cat` 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 where `Dog` connects to the `Mouse` directly(`Dog->Mouse`), and one where `Cat` is included(`Dog->Cat->Mouse`). + +- `Label list: ["/Mouse", "-Cat", "-Human"]` - now, both `Cat` and `Human` are blacklisted, and there is only one eligible path that can reach `Mouse`: `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 with `Dog` 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. + + + + + +```cypher +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. + + + + + + +```cypher +MATCH (w:Wolf), (d:Dog), (c:Cat), (m:Mouse), (h:Human) +CALL path.subgraph_nodes(d, { + relationshipFilter: ["CATCHES>","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. + +```plaintext + +----------------------------+ + | 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. + + + + + +```cypher +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. + + +```plaintext + +----------------------------+ + | nodes | + +----------------------------+ + | { | + | "id": 1, | + | "labels": [ | + | "Dog" | + | ], | + | "properties": {}, | + | "type": "node" | + | } | + +----------------------------+ + | { | + | "id": 0, | + | "labels": [ | + | "Wolf" | + | ], | + | "properties": {}, | + | "type": "node" | + | } | + +----------------------------+ + ``` + + + + + diff --git a/mage/templates/_mage_spells.mdx b/mage/templates/_mage_spells.mdx index d0b89999366..68caaf11a65 100644 --- a/mage/templates/_mage_spells.mdx +++ b/mage/templates/_mage_spells.mdx @@ -21,6 +21,7 @@ | [neighbors](/mage/query-modules/cpp/neighbors) | C++ | The neighbors module allows users to interact with and query nodes that have direct relationships to a specified node. | | [node_similarity](/mage/query-modules/cpp/node-similarity) | C++ | A module that contains similarity measures for calculating the similarity between two nodes. | | [pagerank](/mage/query-modules/cpp/pagerank) | C++ | Algorithm that yields the influence measurement based on the recursive information about the connected nodes influence. | +| [path](/mage/query-modules/cpp/path) | C++ | A module for working with intricate connections in graph-like structures. It provides functions and procedures to navigate and analyze paths, helping users uncover insights from complex data relationships. | | [set_cover](/mage/query-modules/python/set-cover) | Python | An algorithm for finding the minimum cost subcollection of sets that covers all elements of a universe. | | [temporal](/mage/query-modules/python/temporal) | Python | A module that provides functions to handle temporal (time-related) operations and offers extended capabilities compared to the date module. | | [text](/mage/query-modules/cpp/text) | C++ | A module for manipulating strings. | diff --git a/sidebars/sidebarsMAGE.js b/sidebars/sidebarsMAGE.js index 229d7e59b8b..0907a8750c6 100644 --- a/sidebars/sidebarsMAGE.js +++ b/sidebars/sidebarsMAGE.js @@ -62,6 +62,7 @@ module.exports = { "query-modules/python/nxalg", "query-modules/cpp/pagerank", "query-modules/cpp/pagerank-online", + "query-modules/cpp/path", "query-modules/cpp/periodic", "query-modules/python/set-cover", "query-modules/python/temporal",