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.

TraitValue
Module typeutil
ImplementationC++
Graph directiondirected/undirected
Edge weightsweighted/unweighted
Parallelismsequential

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

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

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

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:

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

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:

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