Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/
Documentation version: v5.3.2

# Graph element functions

The following GQL functions operate on graph elements. Examples use the [example dataset](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/#node_functions) | `element_id()`, `labels()`, `type()`
 | [Edge functions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/#edge_functions) | `multiedge_id()`, `left_node_id()`, `right_node_id()`, `start_node_id()`, `end_node_id()`, `labels()`, `type()`
 | [Path functions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/#path_functions) | `nodes()`, `edges()/relationships()`, `length()`, `cardinality()`

Note

Additionally, you can use the [ALL_DIFFERENT predicate](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/all_different/) and the [SAME predicate](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/same/) 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/list/#length) and [String function length()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/string/#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()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/list/#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.