Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

Graph element functions

The following GQL functions operate on graph elements. Examples use the example dataset.

Note

The identifiers returned by graph element functions are generated by the system and unique only within the same system.

Categories

Category Functions
Node functions element_id(), labels(), type()
Edge functions multiedge_id(), left_node_id(), right_node_id(), start_node_id(), end_node_id(), labels(), type()
Path functions nodes(), edges()/relationships(), length(), cardinality()

Note

Additionally, you can use the ALL_DIFFERENT predicate and the SAME predicate to check the consistency of graph elements.

Node functions

element_id()

Returns the unique identifier of a node in the graph.

Null behavior: default

Function signature

element_id(n: NODE) -> INT64

Examples

Return the IDs of nodes with the node type Actor
USE movie MATCH (v@Actor) RETURN element_id(v) LIMIT 5

Return:

+--------------------+
| element_id(v)      |
+--------------------+
| 288493283984801793 |
| 288493365589180417 |
| 288493421423755265 |
| 288493447193559041 |
| 288493623287218177 |
+--------------------+

labels()

Returns all labels of a node.

Null behavior: default

Function signature

labels(n: NODE) -> LIST<STRING>

Examples

Return the labels of nodes
'''
USE movie
MATCH (v)-[]->(m)
WHERE v.id = 133
RETURN labels(m) AS m_labels
'''

Return:

+----------+
| m_labels |
+----------+
| [Movie]  |
+----------+

type()

Returns the node type name.

Null behavior: default

Function signature

type(n: NODE) -> STRING

Examples

Return the node type names of nodes
'''
USE movie
MATCH (v:Person)
RETURN DISTINCT type(v) AS node_types
'''

Return:

+------------+
| node_types |
+------------+
| Director   |
| User       |
| Actor      |
+------------+

Edge functions

multiedge_id()

Returns the unique identifier generated based on the multi-edge key for distinguishing between parallel edges. If the edge type does not allow parallel edges, 0 is returned.

Null behavior: default

Function signature

multiedge_id(e: EDGE) -> INT64

Examples

Return the IDs when there are no parallel edges
'''
USE movie 
MATCH ()-[e]->() RETURN multiedge_id(e) AS e LIMIT 5
'''

Return:

+---+
| e |
+---+
| 0 |
| 0 |
| 0 |
| 0 |
| 0 |
+---+

The return value is 0 because the graph used in the preceding statement does not contain any parallel edges.

Return the IDs for parallel edges
'''
// Create a graph type with a multi-edge key
CREATE GRAPH TYPE IF NOT EXISTS multi_edges AS { 
    NODE Person (LABEL Person {id INT64, name STRING, PRIMARY KEY (id)}) , 
    EDGE `Like` (Person)-[:`Like` {rate FLOAT, MULTIEDGE KEY (rate)}]->(Person) }
'''

'''
// Create a graph
CREATE GRAPH IF NOT EXISTS multiedges TYPED multi_edges
'''

'''
// Insert 2 nodes and 2 parallel edges between them
USE multiedges 
INSERT (n@Person{id:3, name:"Alice"})-[@`Like`{rate: 3.1}]->(m@Person{id:4, name:"Bob"}), 
(n)-[@`Like`{rate: 3.3}]->(m)
'''

'''
// Query the multi-edge IDs for parallel edges
USE multiedges MATCH (@Person{id:3})-[e]->(@Person{id:4}) RETURN multiedge_id(e) AS a
'''

Return:

+------------+
| a          |
+------------+
| 1078355558 |
| 1079194419 |
+------------+

left_node_id()

Returns the unique identifier of the left node corresponding to an edge in a given path.

Null behavior: error

Function signature

left_node_id(e: EDGE) -> INT64

Examples

Return the left node ID of an edge in a given path
'''
USE movie MATCH p = (v)<-[e]-(m) 
RETURN left_node_id(e) AS left_id, element_id(v) AS v_id, e AS edge 
LIMIT 5
'''

Return:

+--------------------+--------------------+----------------------------------------------------------+
| left_id            | v_id               | edge                                                     |
+--------------------+--------------------+----------------------------------------------------------+
| 289329634376417282 | 289329634376417282 | (288247435761811457)-[0@Act:Act{}]->(289329634376417282) |
| 289329634376417282 | 289329634376417282 | (288249956907614209)-[0@Act:Act{}]->(289329634376417282) |
| 289329634376417282 | 289329634376417282 | (288264602746093569)-[0@Act:Act{}]->(289329634376417282) |
| 289329634376417282 | 289329634376417282 | (288266148934320129)-[0@Act:Act{}]->(289329634376417282) |
| 289329634376417282 | 289329634376417282 | (288346404693213185)-[0@Act:Act{}]->(289329634376417282) |
+--------------------+--------------------+----------------------------------------------------------+

As the preceding statement specifies the path (v)<-[e]-(m), the left node ID of the edge [e] in this path is the ID of the node (v).

right_node_id()

Returns the unique identifier of the right node corresponding to an edge in a given path.

Null behavior: error

Function signature

right_node_id(e: EDGE) -> INT64

Examples

Return the right node ID of an edge in a given path
'''
USE movie MATCH p = (v)<-[e]-(m) 
RETURN right_node_id(e) AS right_id, element_id(m) AS m_id, e AS edge 
LIMIT 5
'''

Return:

+--------------------+--------------------+----------------------------------------------------------+
| right_id           | m_id               | edge                                                     |
+--------------------+--------------------+----------------------------------------------------------+
| 288238622488920065 | 288238622488920065 | (288238622488920065)-[0@Act:Act{}]->(289131417340739586) |
| 288243608945950721 | 288243608945950721 | (288243608945950721)-[0@Act:Act{}]->(289131417340739586) |
| 288317563987820545 | 288317563987820545 | (288317563987820545)-[0@Act:Act{}]->(289131417340739586) |
| 288324427345559553 | 288324427345559553 | (288324427345559553)-[0@Act:Act{}]->(289131417340739586) |
| 288345352426225665 | 288345352426225665 | (288345352426225665)-[0@Act:Act{}]->(289131417340739586) |
+--------------------+--------------------+----------------------------------------------------------+

As the preceding statement specifies the path (v)<-[e]-(m), the right node ID of the edge [e] in this path is the ID of the node (m).

start_node_id()

Returns the start node ID of an edge. For a directed edge, returns the source node ID. For an undirected edge, returns the smaller of the two node IDs.

Null behavior: default

Function signature

start_node_id(e: EDGE) -> INT64

Examples

Determine path direction

The following example is based on the movie example dataset. It uses start_node_id() to check whether each edge in an undirected path points away from or toward the current node, constructing the path topology with node names and edge type labels.

'''
USE movie MATCH p= TRAIL (a:Person{name:"Al Pacino"})-[:Act|Direct]-{1,3}()
RETURN range(0,length(p)) AS range,
       nodes(p) AS nodes,
       edges(p) AS edges
NEXT USE movie RETURN
       reduce(range, "", (state, i) -> state || "(" || (nodes[i]).name || ":" || type(nodes[i]) || ")" || case when i+1=size(range) then "" else case when start_node_id(edges[i])=element_id(nodes[i]) then "-["|| type(edges[i]) || "]->" else "<-[" || type(edges[i]) || "]-" end end)
       AS path_topology
LIMIT 5
'''

Return:

+---------------------------------------------------------------------------------------------------------------+
| path_topology                                                                                                 |
+---------------------------------------------------------------------------------------------------------------+
| (Al Pacino:Actor)-[Act]->(The Godfather II:Movie)                                                             |
| (Al Pacino:Actor)-[Act]->(The Godfather Coda: The Death of Michael Corleone:Movie)                            |
| (Al Pacino:Actor)-[Act]->(Ocean's Thirteen:Movie)                                                             |
| (Al Pacino:Actor)-[Act]->(Der Pate:Movie)                                                                     |
| (Al Pacino:Actor)-[Act]->(The Godfather Coda: The Death of Michael Corleone:Movie)<-[Act]-(Talia Shire:Actor) |
+---------------------------------------------------------------------------------------------------------------+

The example uses undirected edge matching -[:Act|Direct]- to traverse paths. start_node_id() determines the direction of each edge relative to the current node: if start_node_id(edges[i]) equals the current node's ID, the edge originates from the current node (->); otherwise, the edge points toward the current node (<-). For directed edges, start_node_id() always returns the source node ID.

end_node_id()

Returns the end node ID of an edge. For a directed edge, returns the destination node ID. For an undirected edge, returns the larger of the two node IDs.

Null behavior: default

Function signature

end_node_id(e: EDGE) -> INT64

Examples

Determine path direction

The following example is based on the movie example dataset. It uses end_node_id() to reconstruct the topology of each path traversed by a TRAIL match, showing edge directions as -> or <-.

'''
USE movie MATCH p= TRAIL (a:Person{name:"Al Pacino"})-[:Act]-{1,3}()
RETURN range(0,length(p)) AS range,
       nodes(p) AS nodes,
       edges(p) AS edges
NEXT USE movie RETURN
       reduce(range, "", (state, i) -> state || (nodes[i]).name || case when i+1=size(range) then "" else case when end_node_id(edges[i])<>element_id(nodes[i]) then "->" else "<-" end end)
       AS path_topology
LIMIT 5
'''

Return:

+--------------------------------------------------------------+
| path_topology                                                |
+--------------------------------------------------------------+
| Al Pacino->Der Pate                                          |
| Al Pacino->Ocean's Thirteen                                  |
| Al Pacino->The Godfather II                                  |
| Al Pacino->The Godfather Coda: The Death of Michael Corleone |
| Al Pacino->The Godfather II<-Lee Strasberg                   |
+--------------------------------------------------------------+

The example uses undirected edge matching -[:Act]- to traverse paths. For the directed edge Act (Actor→Movie), if end_node_id(edges[i]) equals the current node's ID, the edge points toward the current node (<-); otherwise, the edge originates from the current node (->). For undirected edges, end_node_id() returns the larger of the two node IDs.

labels()

Returns all labels of an edge.

Null behavior: default

Function signature

labels(e: EDGE) -> LIST<STRING>

Examples

Return the labels of edges
'''
USE movie
MATCH (v)-[e]->(m)
WHERE v.id = 133
RETURN labels(e) AS e_labels
'''

Return:

+----------+
| e_labels |
+----------+
| [Watch]  |
+----------+

type()

Returns the edge type name.

Null behavior: default

Function signature

type(e: EDGE) -> STRING

Examples

Return the edge type names of edges
'''
USE movie
MATCH ()-[e]->()
RETURN DISTINCT type(e) AS edge_types
'''

Return:

+------------+
| edge_types |
+------------+
| Direct     |
| Act        |
| Watch      |
| WithGenre  |
+------------+

Path functions

nodes()

Returns the list containing all the nodes in a path.

Null behavior: default

Function signature

nodes(p: PATH) -> LIST<NODE>

Examples

Return the nodes in paths that contain two nodes
USE movie MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) RETURN nodes(p) LIMIT 5

Return:

+--------------------------------------------------------------------------------------------------------------------------------+
| nodes(p)                                                                                                                       |
+--------------------------------------------------------------------------------------------------------------------------------+
| [(289219219357171713@Movie:Movie{id:651,name:M*A*S*H}),(288991745004273665@User:Person{id:188})]                               |
| [(289222513597087745@Movie:Movie{id:473,name:Pi}),(288982321846026242@User:Person{id:162})]                                    |
| [(289315070142316545@Movie:Movie{id:252,name:"Willy Wonka & the Chocolate Factory"}),(288993205293154307@User:Person{id:269})] |
| [(289159802779598849@Movie:Movie{id:648,name:"Beauty and the Beast"}),(288990585363103745@User:Person{id:444})]                |
| [(289222513597087745@Movie:Movie{id:473,name:Pi}),(288990585363103745@User:Person{id:444})]                                    |
+--------------------------------------------------------------------------------------------------------------------------------+

edges()/relationships()

Returns the list containing all the edges in a path.

Null behavior: default

Function signature

edges(p: PATH) | relationships(p: PATH) -> LIST<EDGE>

Examples

Return the edges in paths that contain two nodes
USE movie MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) RETURN edges(p) AS p LIMIT 5

or

USE movie MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) RETURN relationships(p) AS p LIMIT 5

Return:

+------------------------------------------------------------------------+
| p                                                                      |
+------------------------------------------------------------------------+
| [(288975157840576514)-[0@Watch:Watch{rate:5.0}]->(289169659729543169)] |
| [(288975157840576514)-[0@Watch:Watch{rate:5.0}]->(289158106267516929)] |
| [(288985753524895745)-[0@Watch:Watch{rate:4.0}]->(289100304597647361)] |
| [(288985753524895745)-[0@Watch:Watch{rate:4.0}]->(289078181221105665)] |
| [(288985753524895745)-[0@Watch:Watch{rate:4.0}]->(289159802779598849)] |
+------------------------------------------------------------------------+

length()

Returns the length of a path, which is defined as the number of edges in the path.

The function length() can also be used to return the number of elements in a list or the number of characters in a string. For more information, see List function length() and String function length().

Null behavior: default

Function signature

length(p: PATH) -> INT32

Examples

Return the lengths of a path that consists of three nodes
'''
USE movie 
MATCH p=(v@Genre)-[e2]-(m@Movie)-[e1]-(n@`User`) 
RETURN length(p) 
LIMIT 2
'''

Return:

+-----------+
| length(p) |
+-----------+
| 2         |
| 2         |
+-----------+

cardinality()

Returns the number of elements in a path.

The function cardinality() can also be used to return the number of elements in a list or a record. For more information, see List function cardinality().

Null behavior: default

Function signature

cardinality(input: PATH) -> INT32

Examples

Return the number of elements in a path
'''
USE movie 
MATCH p=(a:Movie{name:"Unpromised Land"})-[e:WithGenre]->{1,2}(b:Genre) RETURN cardinality(p) AS a 
'''

Return:

+---+
| a |
+---+
| 3 |
| 3 |
+---+

The preceding example returns the number of all elements in each path, each of which contains 2 nodes and 1 edge.