Merge pull request #998 from memgraph/E-add-neighbors-docs

[master < E-add-neighbors] Add docs for neighbors module
memgraph · Aug 31, 2023 · 599cdad · 599cdad
2 parents 4788471 + 1d6a3d0
commit 599cdad
Show file tree

Hide file tree

Showing 4 changed files with 255 additions and 0 deletions.
diff --git a/mage/data/query-modules/cpp/neighbors/neighbors.png b/mage/data/query-modules/cpp/neighbors/neighbors.png
diff --git a/mage/query-modules/cpp/neighbors.md b/mage/query-modules/cpp/neighbors.md
@@ -0,0 +1,253 @@
+---
+id: neighbors
+title: neighbors
+sidebar_label: neighbors
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import RunOnSubgraph from '../../templates/_run_on_subgraph.mdx';
+
+export const Highlight = ({children, color}) => (
+<span
+style={{
+  backgroundColor: color,
+  borderRadius: '2px',
+  color: '#fff',
+  padding: '0.2rem',
+}}>
+{children}
+</span>
+);
+
+The `neighbors` module provides tools for users to interact with and query nodes that have direct relationships to a specified node, enabling an examination of the immediate connections within the graph and thereby gaining insights into the network structure and connectivity.
+
+
+[![docs-source](https://img.shields.io/badge/source-neighbors-FB6E00?logo=github&style=for-the-badge)](https://github.com/memgraph/mage/tree/main/cpp/neighbors_module)
+
+| Trait               | Value                                                 |
+| ------------------- | ----------------------------------------------------- |
+| **Module type**     | <Highlight color="#FB6E00">**algorithm**</Highlight>  |
+| **Implementation**  | <Highlight color="#FB6E00">**C++**</Highlight>        |
+| **Graph direction** | <Highlight color="#FB6E00">**directed**</Highlight>/<Highlight color="#FB6E00">**undirected**</Highlight> |
+| **Edge weights**    | <Highlight color="#FB6E00">**weighted**</Highlight>/<Highlight color="#FB6E00">**unweighted**</Highlight> |
+| **Parallelism**     | <Highlight color="#FB6E00">**sequential**</Highlight> |
+
+### Procedures
+
+### `at_hop(node, rel_type, distance)`
+
+Returns nodes that are at a specific distance from a given node, considering only the relationships of a specified type.
+
+#### Input:
+
+- `node: Node` ➡ node for which neighborhood is being analyzed.
+- `rel_type: List[string]` ➡ list of relationship types to travel through; if empty, it is possible to travel through all types of relationships.
+- `distance: int` ➡ number of hops between nodes.
+
+:::info
+
+If '<' is added in front of the relationship type, only relationships coming into the node will be checked (e.g., "<KNOWS"), while if '>' is added at the end of the relationship type, only relationships coming from the node will be checked (e.g., "KNOWS>"). Furthermore, if the relationship type is not relevant, it is possible to enter only "<" or ">" to check ingoing or outgoing relationships.
+
+:::
+
+#### Output:
+
+- `nodes: Node` ➡ nodes at a specific distance from a given node.
+
+#### Usage:
+
+```cypher
+MATCH (p:Person)
+CALL neighbors.at_hop(p, ["KNOWS"], 3) YIELD nodes RETURN nodes;
+```
+
+
+### `by_hop(node, rel_type, distance)`
+
+Returns nodes that are at any or up to a specific distance from a given node, considering only the relationships of a specified type.
+
+#### Input:
+
+- `node: Node` ➡ node for which neighborhood is being analyzed.
+- `rel_type: List[string]` ➡ list of relationship types to travel through; if empty, it is possible to travel through all types of relationships.
+- `distance: int` ➡ maximum number of hops between nodes.
+
+:::info
+
+If '<' is added in front of the relationship type, only relationships coming into the node will be checked (e.g., "<KNOWS"), while if '>' is added at the end of the relationship type, only relationships coming from the node will be checked (e.g., "KNOWS>"). Furthermore, if the relationship type is not relevant, it is possible to enter only "<" or ">" to check ingoing or outgoing relationships.
+
+:::
+
+#### Output:
+
+- `nodes: List[Node]` ➡ list of nodes at a specific distance from a given node, starting from distance 1 up to a provided distance.
+
+#### Usage:
+
+```cypher
+MATCH (p:Person)
+CALL neighbors.by_hop(p, ["KNOWS"], 3) YIELD nodes RETURN nodes;
+```
+
+
+## Example - neighbors.at_hop
+
+<Tabs
+  groupId="at_hop_example"
+  defaultValue="input"
+  values={[
+    {label: 'Step 1: Cypher load commands', value: 'load'},
+    {label: 'Step 2: Input graph', value: 'input'},
+    {label: 'Step 3: Running command', value: 'run'},
+    {label: 'Step 4: Results', value: 'result'},
+  ]
+}>
+
+<TabItem value="load">
+
+You can create a simple graph database by running the following queries:
+
+```cypher
+MERGE (a:Rachel) MERGE (b:Monica) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Monica) MERGE (b:Ross) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Monica) MERGE (b:Chandler) CREATE (a)-[f:LOVERS]->(b);
+MERGE (a:Chandler) MERGE (b:Joey) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Monica) MERGE (b:Phoebe) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Rachel) MERGE (b:Ross) CREATE (a)-[f:LOVERS]->(b);
+```
+
+</TabItem>
+
+<TabItem value="input">
+
+The image below shows the above data as a graph:
+
+<img src={require('../../data/query-modules/cpp/neighbors/neighbors.png').default}/>
+
+</TabItem>
+
+<TabItem value="run">
+
+```cypher
+MATCH (p:Phoebe)
+CALL neighbors.at_hop(p, [""], 3) YIELD nodes
+RETURN nodes
+```
+
+</TabItem>
+
+<TabItem value="result">
+
+The results should be identical to the ones below, except for the
+`id` values that depend on the internal database `id` values:
+
+```plaintext
++----------------------------+
+| nodes                      |
++----------------------------+
+| {                          |    -> node at hop 3 with no relationship
+|     "id": 1,               |       types specified
+|     "labels": [            |
+|        "Joey"              |
+|     ],                     |
+|     "properties": {},      |
+|     "type": "node"         |
+| }                          |
++----------------------------+
+
+```
+
+</TabItem>
+
+</Tabs>
+
+
+## Example - neighbors.by_hop
+
+<Tabs
+  groupId="by_hop_example"
+  defaultValue="input2"
+  values={[
+    {label: 'Step 1: Cypher load commands', value: 'load2'},
+    {label: 'Step 2: Input graph', value: 'input2'},
+    {label: 'Step 3: Running command', value: 'run2'},
+    {label: 'Step 4: Results', value: 'result2'},
+  ]
+}>
+
+<TabItem value="load2">
+
+You can create a simple graph database by running the following queries:
+
+```cypher
+MERGE (a:Rachel) MERGE (b:Monica) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Monica) MERGE (b:Ross) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Monica) MERGE (b:Chandler) CREATE (a)-[f:LOVERS]->(b);
+MERGE (a:Chandler) MERGE (b:Joey) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Monica) MERGE (b:Phoebe) CREATE (a)-[f:FRIENDS]->(b);
+MERGE (a:Rachel) MERGE (b:Ross) CREATE (a)-[f:LOVERS]->(b);
+```
+
+</TabItem>
+
+<TabItem value="input2">
+
+The image below shows the above data as a graph:
+
+<img src={require('../../data/query-modules/cpp/neighbors/neighbors.png').default}/>
+
+</TabItem>
+
+<TabItem value="run2">
+
+```cypher
+MATCH (p:Phoebe)
+CALL neighbors.by_hop(p, ["FRIENDS"], 3) YIELD nodes
+RETURN nodes
+```
+
+</TabItem>
+
+<TabItem value="result2">
+
+The results should be identical to the ones below, except for the
+`id` values that depend on the internal database `id` values:
+
+```plaintext
++----------------------------+
+| nodes                      |
++----------------------------+
+| [{                         |    -> list of nodes at hop 1
+|     "id": 1,               |
+|     "labels": [            |
+|        "Monica"            |
+|     ],                     |
+|     "properties": {},      |
+|     "type": "node"         |
+| }]                         |
++----------------------------+
+| [{                         |    -> list of nodes at hop 2
+|     "id": 2,               |
+|     "labels": [            |
+|        "Ross"              |
+|     ],                     |
+|     "properties": {},      |
+|     "type": "node"         |
+| }, {                       |
+|     "id": 3,               |
+|     "labels": [            |
+|        "Rachel"            |
+|     ],                     |
+|     "properties": {},      |
+|     "type": "node"         |
+| }]                         |
++----------------------------+
+| []                         |    -> list of nodes at hop 3
++----------------------------+
+```
+
+</TabItem>
+
+</Tabs>
+
diff --git a/mage/templates/_mage_spells.mdx b/mage/templates/_mage_spells.mdx
@@ -18,6 +18,7 @@
 | [label](/mage/query-modules/cpp/label)                                                 | C++    | The label module provides an array of utilities for working with labels in a Memgraph database.                                                                                                                                   |
 | [map](/mage/query-modules/cpp/map)                                                     | C++    | The map module offers a versatile toolkit for manipulating collections of key-value pairs, enabling advanced data operations within a graph database context                                                                      |
 | [max_flow](/mage/query-modules/python/max-flow)                                        | Python | An algorithm for finding a flow through a graph such that it is the maximum possible flow.                                                                                                                                        |
+| [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.                                                                                                           |
 | [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.                                                                                                                           |

diff --git a/sidebars/sidebarsMAGE.js b/sidebars/sidebarsMAGE.js
@@ -54,6 +54,7 @@ module.exports = {
         "query-modules/python/max-flow",
         "query-modules/python/meta-util",
         "query-modules/python/migrate",
+        "query-modules/cpp/neighbors",
         "query-modules/python/node-classification-with-gnn",
         "query-modules/python/node2vec",
         "query-modules/python/node2vec-online",