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.

Source code

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:

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:

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:

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:

MATCH (p:Person)
CALL neighbors.by_hop(p, ["KNOWS"], 3) YIELD nodes RETURN nodes;

Example

Database state

The database contains the following data:

Created with the following Cypher queries:

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);

Analyise 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:

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:

+----------------------------+
| nodes                      |
+----------------------------+
| {                          |    -> node at hop 3 with no relationship
|     "id": 1,               |       types specified
|     "labels": [            |
|        "Joey"              |
|     ],                     |
|     "properties": {},      |
|     "type": "node"         |
| }                          |
+----------------------------+

Analyise 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:

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:

+----------------------------+
| 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
+----------------------------+