Graph Functions¶

Overview ¶

Graph functions are used to extract information from graph paths when querying graph data using MATCH clauses. These functions operate on path variables to retrieve vertices, edges, and their properties.

The main graph functions are:

relationships() - Returns a list of edges in a path
nodes() - Returns a list of vertices in a path
path_comp() - Performs path comprehension to extract and transform data from graph patterns

These functions are typically used in combination with:

list_comp() - For list comprehensions to process edges/vertices
property_of() - To extract specific properties from edges or vertices
first() - To get the first element from a list
last() - To get the last element from a list

NODES ¶

nodes(path_variable)¶

The nodes() function returns a list of all vertices in a graph path. This function can only be used with path variables from MATCH clauses.

Parameters:: path_variable – A path variable from a MATCH clause (e.g., pth in MATCH pth=(v1)-[e]->(v2))
Return type:: LIST of vertices

Note

The nodes() function requires exactly one argument, which must be a path variable. It cannot accept NULL, scalars, lists, or non-path variables.

Basic Usage Examples¶

Example 1: Get first and last nodes in paths of length 2 or 3

First, let’s set up the test data:

CREATE EDGE TABLE Knows (
    id INT NOT NULL AUTO_INCREMENT,
    source INT,
    destination INT,
    remark STRING
);

CREATE VERTEX TABLE Person (
    id INT,
    firstName STRING,
    lastName STRING,
    age INT
);

INSERT VERTEX INTO Person VALUES (0, 'Jerry', 'Madonna', 10);
INSERT VERTEX INTO Person VALUES (1, 'John', 'Doe', 20);
INSERT VERTEX INTO Person VALUES (2, 'Alice', 'Johnson', 40);
INSERT VERTEX INTO Person VALUES (3, NULL, NULL, NULL);

INSERT EDGE FROM (SELECT Person FROM Person WHERE id = 0)
              TO (SELECT Person FROM Person WHERE id = 1)
            INTO Knows VALUES (1, 0, 1, 'best friend');
INSERT EDGE FROM (SELECT Person FROM Person WHERE id = 1)
              TO (SELECT Person FROM Person WHERE id = 2)
            INTO Knows VALUES (2, 1, 2, 'worst friend');
INSERT EDGE FROM (SELECT Person FROM Person WHERE id = 2)
              TO (SELECT Person FROM Person WHERE id = 0)
            INTO Knows VALUES (3, 2, 0, 'most hated');
INSERT EDGE FROM (SELECT Person FROM Person WHERE id = 2)
              TO (SELECT Person FROM Person WHERE id = 1)
            INTO Knows VALUES (4, 2, 1, 'close friend');
INSERT EDGE FROM (SELECT Person FROM Person WHERE id = 0)
              TO (SELECT Person FROM Person WHERE id = 3)
            INTO Knows VALUES (5, 0, 3, 'distant friend');

Now, collect node IDs in paths of length 2 or 3:

SELECT property_of(first(nodes(pth)), lastName, Person) AS first_node,
       property_of(last(nodes(pth)), lastName, Person) AS last_node
FROM MATCH pth=(p1:Person)-[k:Knows {2,3}]->(p2:Person)
ORDER BY first_node, last_node;

This query extracts all vertices from paths of length 2 or 3, then uses the first() and last() functions to get the first and last nodes’ lastName property.

Example 2: First and last node in reversed path

SELECT property_of(first(nodes(pth)), lastName, Person) AS first_node,
       property_of(last(nodes(pth)), lastName, Person) AS last_node
FROM MATCH pth=(p1:Person)<-[k:Knows {1,2}]-(p2:Person)
ORDER BY first_node, last_node;

This query finds paths with edges going in the reverse direction (using <- instead of ->) and extracts the first and last node names.

Example 3: Filter paths containing a specific person

SELECT property_of(first(nodes(pth)), lastName, Person) AS first_node
FROM MATCH pth=(p1:Person)-[k:Knows {1,3}]->(p2:Person)
WHERE 3 IN list_comp(n IN nodes(pth) | property_of(n, id, Person))
ORDER BY first_node;

This query finds paths of length 1-3 and filters for those that include a person with ID 3. The nodes() function is used within a list comprehension to extract all node IDs in the path.

Error Conditions¶

The nodes() function will return an error in the following cases:

Error 1: Non-path variable argument

SELECT nodes(p1)
FROM MATCH pth=(p1:Person)-[k:Knows {1,3}]->(p2:Person);

This is invalid because p1 is a vertex variable, not a path variable. Only path variables (like pth) can be passed to nodes().

Error 2: Scalar or NULL argument

SELECT nodes(1)
FROM MATCH pth=(p1:Person)-[k:Knows {1,3}]->(p2:Person);

This is invalid because nodes() requires a path variable, not a scalar value or NULL.

RELATIONSHIPS ¶

relationships(path_variable)¶

The relationships() function returns a list of all edges in a graph path. This function can only be used with path variables from MATCH clauses.

Parameters:: path_variable – A path variable from a MATCH clause (e.g., pth in MATCH pth=(v1)-[e]->(v2))
Return type:: LIST of edges

Note

The relationships() function requires exactly one argument, which must be a path variable. It cannot accept NULL, scalars, lists, or non-path variables.

Basic Usage Examples¶

Example 1: Collect edge IDs in paths of length 2 or 3

Using the same test data setup as in the nodes() examples above, find paths of length 2 or 3 and collect the edge IDs:

SELECT list_comp(e IN relationships(pth) | property_of(e, id, Knows)) AS edge_ids
FROM MATCH pth=(p1:Person)-[k:Knows {2,3}]->(p2:Person)
ORDER BY edge_ids;

This query extracts all edges from paths of length 2 or 3, then uses list comprehension to get the ID of each edge.

Example 2: Reversed path traversal

SELECT list_comp(e IN relationships(pth) | property_of(e, id, Knows)) AS edge_ids
FROM MATCH pth=(p1:Person)<-[k:Knows {1,2}]-(p2:Person)
ORDER BY edge_ids;

This query finds paths with edges going in the reverse direction (using <- instead of ->).

Example 3: Filtering paths by edge properties

SELECT property_of(first(relationships(pth)), id, Knows) AS edge_id
FROM MATCH pth=(p1:Person)-[k:Knows {1,3}]->(p2:Person)
WHERE 2 IN list_comp(e IN relationships(pth) | property_of(e, id, Knows))
ORDER BY edge_id;

This query finds paths of length 1-3 and filters for those that include an edge with ID 2.

Error Conditions¶

The relationships() function will return an error in the following cases:

Error 1: Non-path variable argument

SELECT relationships(p1)
FROM MATCH pth=(p1:Person)-[k:Knows {1,3}]->(p2:Person);

This is invalid because p1 is a vertex variable, not a path variable. Only path variables (like pth) can be passed to relationships().

Error 2: Scalar or NULL argument

SELECT relationships(1)
FROM MATCH pth=(p1:Person)-[k:Knows {1,3}]->(p2:Person);

This is invalid because relationships() requires a path variable, not a scalar value or NULL.

PATH_COMP ¶

path_comp(pattern [WHERE condition] | expression [ORDER BY ordering])¶

The path_comp() function performs path comprehension on graph patterns, allowing you to extract and transform data from matched paths. It’s similar to list comprehension but operates directly on graph patterns.

Parameters:

pattern – One or more graph patterns to match (e.g., (a:Person)->(b:Person))
condition – Optional WHERE clause to filter matched paths
expression – Expression to evaluate for each matched path (e.g., a.name)
ordering – Optional ORDER BY clause to sort results

Return type:

LIST of values

Note

The path_comp() function allows you to specify graph patterns inline and extract data from vertices and edges without explicitly using MATCH clauses.

Basic Usage Examples¶

Example 1: Simple path comprehension

Using the same test data setup as in the nodes() examples above, extract names from a simple pattern:

SELECT path_comp((a:Person)->(b:Person) | a.firstName);

This returns the first names of all vertices that have outgoing edges to other Person vertices.

Example 2: Path comprehension with named edges

SELECT path_comp((a:Person)-[e:Knows]->(b:Person) | a.firstName);

This is similar to Example 1 but explicitly names the edge variable and specifies the edge label.

Example 3: Path comprehension with ORDER BY

SELECT path_comp((a:Person)-[e:Knows]->(b:Person) | a.firstName ORDER BY 1);

This returns first names sorted in ascending order (ORDER BY 1 means order by the first column).

Example 4: Path comprehension with explicit column ordering

SELECT path_comp((a:Person)-[e:Knows]->(b:Person) | a.firstName ORDER BY a.firstName ASC);

This explicitly orders by the firstName attribute in ascending order.

Example 5: Filtering by vertex property with WHERE

SELECT path_comp((a:Person)->(b:Person) WHERE a.firstName > 'Alex' | a.firstName);

This filters paths where the source vertex has firstName greater than ‘Alex’.

Error Conditions¶

The path_comp() function will return an error in the following cases:

Error 1: Missing expression after pipe

SELECT path_comp((a:Person)->(b:Person) | );

This is invalid because the expression after the pipe operator is required.

Error 2: Invalid pattern syntax

SELECT path_comp(a:Person | a.firstName);

This is invalid because the pattern must include relationship specification (e.g., (a:Person)->(b:Person)).

Graph Functions¶

Overview ¶

NODES ¶

Basic Usage Examples¶

Error Conditions¶

See Also¶

RELATIONSHIPS ¶

Basic Usage Examples¶

Error Conditions¶

See Also¶

PATH_COMP ¶

Basic Usage Examples¶

Error Conditions¶

See Also¶

Graph Functions¶

Overview¶

NODES¶

Basic Usage Examples¶

Error Conditions¶

See Also¶

RELATIONSHIPS¶

Basic Usage Examples¶

Error Conditions¶

See Also¶

PATH_COMP¶

Basic Usage Examples¶

Error Conditions¶

See Also¶

Overview ¶

NODES ¶

RELATIONSHIPS ¶

PATH_COMP ¶