# neighbors 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. | Trait | Value | | ------------------- | ------------------- | | **Module type** | util | | **Implementation** | C++ | | **Graph direction** | directed/undirected | | **Edge weights** | weighted/unweighted | | **Parallelism** | sequential | ## Procedures ### `at_hop()` Returns nodes that are at a specific distance from a given node, considering only the relationships of a specified type. #### Input: - `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. If subgraph is not specified, the algorithm is computed on the entire graph by default. - `node: Node` ➡ The target node of neighborhood analysis. - `rel_type: List[string]` ➡ A list of relationship types to travel through. If the list is empty, the procedure will return all types of relationships. - `distance: int` ➡ The number of hops between nodes. 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: The following query will analysis the neighborhood of the persone nodes that are 3 hops away along the `KNOWS` relationship: ```cypher MATCH (p:Person) CALL neighbors.at_hop(p, ["KNOWS"], 3) YIELD nodes RETURN nodes; ``` ### `by_hop()` 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: - `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. If subgraph is not specified, the algorithm is computed on the entire graph by default. - `node: Node` ➡ The target node of neighborhood analysis. - `rel_type: List[string]` ➡ A list of relationship types to travel through. If the list is empty, the procedure will return all types of relationships. - `distance: int` ➡ The maximum number of hops between nodes. 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]` ➡ A list of nodes at a specific distance from a given node, starting from distance 1 up to the provided distance. #### Usage: The following query will analysis the neighborhood of the persone nodes that are up to 3 hops away along the `KNOWS` relationship: ```cypher MATCH (p:Person) CALL neighbors.by_hop(p, ["KNOWS"], 3) YIELD nodes RETURN nodes; ``` ## Example ### Database state The database contains the following data: ![](https://memgraph.com/docs/pages/advanced-algorithms/available-algorithms/neighbors/neighbors.png) Created with the following Cypher 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); ``` ### Analyse neighborhood specific hops away Use the following query to get the neighbor nodes that are 3 hops away from the `Pheobe` node along all the possible relationships: ```cypher MATCH (p:Phoebe) CALL neighbors.at_hop(p, [""], 3) 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 | +----------------------------+ | { | -> node at hop 3 with no relationship | "id": 1, | types specified | "labels": [ | | "Joey" | | ], | | "properties": {}, | | "type": "node" | | } | +----------------------------+ ``` ### Analyse neighborhood up to a certain hops away Use the following query to get the neighbor nodes that are up to 3 hops away from the `Pheobe` node along all the possible relationships: ```cypher MATCH (p:Phoebe) CALL neighbors.by_hop(p, ["FRIENDS"], 3) 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 | +----------------------------+ | [{ | -> 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 +----------------------------+ ```