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.

docs-source (opens in a new tab)

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

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.

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:

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.

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:

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

Example - neighbors.at_hop

Cypher load commands

You can create a simple graph database by running the following 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);

Input graph

The image below shows the above data as a graph:

Run commands

MATCH (p:Phoebe)
CALL neighbors.at_hop(p, [""], 3) YIELD nodes
RETURN nodes

Results

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

Example - neighbors.by_hop

Cypher load commands

You can create a simple graph database by running the following 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);

Input graph

The image below shows the above data as a graph:

Run commands

MATCH (p:Phoebe)
CALL neighbors.by_hop(p, ["FRIENDS"], 3) YIELD nodes
RETURN nodes

Results

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