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

# List functions

## length()

Returns the number of elements in a list.

The function `length()` can also be used to return the number of characters in a string or the length of a path. For more information, see [String function length()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/string/#length) and [Graph function length()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/#length).

Null behavior: default

### Function signature

````
length(l: LIST) -> INT32

````

### Examples

#### Get the length of a list

````
RETURN length(LIST [1,2, null ,4]) AS len

````

Return:

````
+-----+
| len |
+-----+
| 4   |
+-----+

````

#### Get the length of a list that is null

````
RETURN length(null)

````

Return:

````
+--------------+
| length(null) |
+--------------+
| null         |
+--------------+

````

#### Get the number of nodes in a path

````
'''
USE movie 
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p) 
RETURN length(a) AS len LIMIT 1
'''

````

Return:

````
+-----+
| len |
+-----+
| 2   |
+-----+

````

## cardinality()

Returns the number of elements in a list or record.

The function `cardinality()` can also be used to return the number of elements in a path. For more information, see [Graph function cardinality()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/#cardinality).

Null behavior: default

### Function signature

````
cardinality(input: LIST | RECORD) -> INT32

````

### Examples

#### Get the number of elements in a list

````
RETURN cardinality([2,2,3]) AS a

````

Return:

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

````

#### Get the number of elements in a record

````
RETURN cardinality({a:1, b:true, c:null, d:null, e: 1}) AS a

````

Return:

````
+---+
| a |
+---+
| 5 |
+---+

````

## size()

Returns the number of elements in a list, unique elements in a set, key-value pairs in a map, or the total rows in a table.

Null behavior: default

### Function signature

````
size(list) -> INT32
size(set) -> INT32
size(map) -> INT32
size(table) -> INT64

````

### Examples

#### Get the number of elements in a list

````
RETURN size(LIST[1,2,3]) AS l

````

Return:

````
+---+
| l |
+---+
| 3 |
+---+

````

#### Get the number of unique elements in a set

````
RETURN size(SET{1,2,3,2,1}) AS s

````

Return:

````
+---+
| s |
+---+
| 3 |
+---+

````

#### Get the number of unique key-value pairs in a map

````
RETURN size(MAP{"a":1, "b":2, "c":3, "a":1}) AS m 

````

Return:

````
+---+
| m |
+---+
| 3 |
+---+

````

#### Get the number of rows in a table

````
TABLE t {s, d, id} = (1, 10, 1), (2, 20, 2) RETURN size(t) as s

````

Return:

````
+---+
| s |
+---+
| 2 |
+---+ 

````

Note on table updates: If a single statement performs both an update to a table (e.g., via EXPORT) and a call to `size()`, the `size()` function returns the row count before the update is applied.

In the following example (based on the [example dataset](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/example-dataset/) ), `size(result_table)` is called during the `EXPORT` process. Even though rows are being added to the table, the value stored in `sz` reflects the state of the table before the current set of nodes was exported.

````
CREATE TEMPORARY GRAPH IF NOT EXISTS #movie_temporary_graph AS COPY OF movie

"""
USE #movie_temporary_graph {
  TABLE result_table TYPED TABLE {id INT, sz INT64}
  MATCH (a)
  PER NODE (a) {
  EXPORT a.id, size(result_table) INTO result_table
  }

  FOR x IN result_table
  RETURN DISTINCT x.sz AS ori_size, size(result_table) AS now_size
}
"""

````

Return:

````
+----------+----------+
| ori_size | now_size |
+----------+----------+
| 0        | 4589     |
+----------+----------+

````

## head()

Returns the first element of a list.

Null behavior: default

### Function signature

````
head(l: LIST) -> E

````

`E` refers to all data types.

### Examples

#### Get the first element of a list

````
RETURN head(LIST [1,2,null,4]) AS item

````

Return:

````
+------+
| item |
+------+
| 1    |
+------+

````

#### Get the first node in a path

````
'''
USE movie 
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p) 
RETURN head(a) LIMIT 1
'''

````

Return:

````
+----------------------------------------------------------------------+
| head(a)                                                              |
+----------------------------------------------------------------------+
| (289159802779598849@Movie:Movie{id:648,name:"Beauty and the Beast"}) |
+----------------------------------------------------------------------+

````

## tail()

Removes the first element of a list.

Null behavior: default

### Function signature

````
tail(l: LIST) -> LIST

````

### Examples

#### Remove the first element of a list

````
RETURN tail(LIST [1,2,null,4]) AS item

````

Return:

````
+------------+
| item       |
+------------+
| [2,null,4] |
+------------+

````

#### Remove the first node in a list of nodes

````
'''
USE movie 
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p) 
RETURN tail(a) LIMIT 1
'''

````

Return:

````
+--------------------------------------------+
| tail(a)                                    |
+--------------------------------------------+
| [(289042090610917378@User:Person{id:521})] |
+--------------------------------------------+

````

## back()

Returns the last element of a list.

Null behavior: default

### Function signature

````
back(l: LIST) -> E

````

`E` refers to all data types.

### Examples

#### Get the last element of a list

````
RETURN back(LIST [1,2,null,4]) AS item

````

Return:

````
+------+
| item |
+------+
| 4    |
+------+

````

#### Get the last node in a path

````
'''
USE movie 
MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) LET a = nodes(p) 
RETURN back(a) LIMIT 1
'''

````

Return:

````
+------------------------------------------+
| back(a)                                  |
+------------------------------------------+
| (288997977001820161@User:Person{id:229}) |
+------------------------------------------+

````

## range()

Returns a list of integers that starts from the `start` value and ends at the `end` value, where the difference `step` between any two consecutive values is a constant.

The value of `step` can be any non-zero integer and defaults to 1.

Null behavior: default

### Function signature

````
range(start: INT, end: INT [, step: INT]) -> LIST<INT>

````

### Examples

#### Get a list of integers with the default step

````
RETURN range(-3,2) AS l

````

Return:

````
+------------------+
| l                |
+------------------+
| [-3,-2,-1,0,1,2] |
+------------------+

````

#### Get a list of integers with a positive step

````
RETURN range(-3,2,2) AS l

````

Return:

````
+-----------+
| l         |
+-----------+
| [-3,-1,1] |
+-----------+

````

#### Get a list of integers with a negative step

````
RETURN range(10,0,-2) AS l

````

Return:

````
+----------------+
| l              |
+----------------+
| [10,8,6,4,2,0] |
+----------------+

````

#### Returns an error if the step is 0

````
RETURN range(10, 0, 0)

````

Return:

````
Error: [NR003]: Invalid function argument: 0

````

## list_slice()

Returns a slice of a list that starts from the `start` value and ends at the `end` value.

Null behavior: default

### Function signature

````
list_slice(l: LIST<E>, start: INT32, end: INT32 [, step: INT32]) -> LIST<E>

````

`E` refers to all data types.

### Parameters

- `l`: The source list to be sliced.
- `start`: The zero-based position in the list (`l`) where the slice begins.
- `end`: The zero-based position in the list (`l`) where the slice ends.
- `step`(optional): The difference between any two consecutive values, which should be any non-zero integer and defaults to `1`. 

Positive values of the parameters `start`, `end` and `step` count from the start of the list, while negative values from the end.

### Examples

#### Get a slice with a positive step

````
'''
LET input = ["hello", "my", "beautiful", "garden"] 
RETURN list_slice(input, 0, 3, 2) AS a
'''

````

Return:

````
+-------------------+
| a                 |
+-------------------+
| [hello,beautiful] |
+-------------------+

````

#### Get a slice with a negative step

````
'''
LET input = range(1,6) 
RETURN list_slice(input, 5, 3, -2) AS a
''' 

````

Return:

````
+-------+
| a     |
+-------+
| [6,4] |
+-------+

````

#### Get a slice with negative input parameters

````
'''
LET input = range(1,6) 
RETURN list_slice(input, -3, -1) AS a
'''

````

Return:

````
+---------+
| a       |
+---------+
| [4,5,6] |
+---------+

````

#### Returns an error if the step is zero

````
'''
LET input = range(1,6) 
RETURN list_slice(input, 1, 4, 0) AS a
'''

````

Return:

````
Error: [NR003]: Invalid function argument: Slice step cannot be zero

````

## trim()

Returns a list after removing a specified number of elements from the end of the list.

The function `trim()` can also be used to return a string with the leading, trailing, or both characters removed. For more information, see [String function `trim()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/string/#trim).

Null behavior: default

### Function signature

````
trim(l: LIST, trim_num: INT32) -> LIST

````

### Parameters

- `l`: The source list.
- `trim_num`: The number of elements to be removed from the end of the source list. The number must be greater than or equal to 0 and less than the length of the source list.

### Examples

#### Remove the last 2 elements from a list of integers

````
RETURN trim([1,2,3,4], 2) AS a

````

Return:

````
+-------+
| a     |
+-------+
| [1,2] |
+-------+

````

#### Remove the last 2 elements from a nested list

````
RETURN trim([[1.1,2,3], [3.0, null],[4.4,5,6]],2) AS a

````

Return:

````
+-------------+
| a           |
+-------------+
| [[1.1,2,3]] |
+-------------+

````

## zip()

Combines two lists, element for element, into a list of lists.

Null behavior: default

### Function signature

````
zip(l1: LIST, l2: LIST) -> LIST

````

### Parameters

- `l1` or `l2`: The source list. The elements in `l1` and `l2` must be of the same data type. 
- The elements at the same positions in `l1` and `l2` are paired together. If `l1` and `l2` differ in length, the result matches the length of the shorter list, ignoring extra elements in the longer list.

### Examples

#### Pair elements from two lists of integers

````
RETURN zip([1,2,3],[4,5,6]) AS res

````

Return:

````
+---------------------+
| res                 |
+---------------------+
| [[1,4],[2,5],[3,6]] |
+---------------------+

````

#### Pair elements from two lists of strings

````
RETURN zip(["The","is","not"],["apple","big"]) AS lis  

````

Return:

````
+------------------------+
| lis                    |
+------------------------+
| [[The,apple],[is,big]] |
+------------------------+

````

## list_distinct()

Removes duplicate values from the input list and then returns a new list.

Null behavior: default

### Function signature

````
list_distinct(l: LIST) -> LIST

````

### Examples

#### Remove duplicate values from a list of integers

````
RETURN list_distinct([1,2,3,2,1,3,1,2,null]) AS res

````

Return:

````
+--------------+
| res          |
+--------------+
| [3,1,2,null] |
+--------------+

````

#### Remove duplicate values from a list of strings

````
RETURN list_distinct(["a","b","a","c","b"]) AS res

````

Return:

````
+---------+
| res     |
+---------+
| [a,c,b] |
+---------+

````

## list_except()

Returns a list of the elements in list x but not in list y, without duplicates. 

Null behavior: default

### Function signature

````
list_except(x: LIST, y: LIST) -> LIST

````

### Examples

````
RETURN list_except([1,2,3,4,5],[3,4,4,4,4,4,null]) AS res

````

Return:

````
+---------+
| res     |
+---------+
| [1,2,5] |
+---------+

````

## list_intersect()

Returns a list of the elements in the intersection of list x and list y, without duplicates.

Null behavior: default

### Function signature

````
list_intersect(x: LIST, y: LIST) -> LIST

````

### Examples

````
RETURN list_intersect([null,1,2,3],[2,3,null,4]) AS res

````

Return:

````
+------------+
| res        |
+------------+
| [null,2,3] |
+------------+

````

## list_join()

Concatenates the elements of the input list using the delimiter and an optional string to replace nulls.

Null behavior: default

### Function signature

````
list_join(l: LIST, delimiter: STRING, replace_null: STRING) -> STRING

````

- `delimiter`: A string used to separate the elements in the input list.
- `replace_null`: An optional string used to replace null values in the input list. If not specified, null values are replaced with empty strings.

### Examples

#### Join a list of integers with a delimiter

````
RETURN list_join([1,null,3], ",") AS res

````

Return:

````
+------+
| res  |
+------+
| 1,,3 |
+------+

````

#### Join a list of strings with a delimiter and replace nulls with a string

````
RETURN list_join([1,2,null,4], "-", "?") AS res

````

Return:

````
+---------+
| res     |
+---------+
| 1-2-?-4 |
+---------+

````

## list_max()

Returns the maximum value of the input list. Returns null if the list contains any null value. For more information about the comparison between values, see [Comparison predicate](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/comparison/).

Null behavior: default

### Function signature

````
list_max(l: LIST) -> E

````

### Examples

#### Get the maximum value of a list of integers

````
RETURN list_max([-5,-3,-1,0,1,3,5]) AS res

````

Return:

````
+-----+  
| res |
+-----+  
| 5   |
+-----+  

````

#### Get the maximum value of a list of strings

````
RETURN list_max(["a","b","c"]) AS res

````

Return:

````
+-----+
| res |
+-----+
| c   |
+-----+

````

#### Return null if the list contains any null value

````
RETURN list_max([1,2,null,3,null,4]) AS res

````

Return:

````
+------+
| res  |
+------+
| null |
+------+

````

## list_min()

Returns the minimum value of the input list. Returns null if the list contains any null value. For more information about the comparison between values, see [Comparison predicate](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/comparison/).

Null behavior: default

### Function signature

````
list_min(l: LIST) -> E

````

### Examples

#### Get the minimum value of a list of integers

````
RETURN list_min([-5,-3,-1,0,1,3,5]) AS res

````

Return:

````
+-----+  
| res |
+-----+  
| -5  |
+-----+  

````

#### Get the minimum value of a list of strings

````
RETURN list_min(["a","b","c"]) AS res

````

Return:

````
+-----+
| res |
+-----+
| a   |
+-----+

````

#### Return null if the list contains any null value

````
RETURN list_min([1,2,null,3,null,4]) AS res

````

Return:

````
+------+
| res  |
+------+
| null |
+------+

````

## list_union()

Returns a list of the elements in the union of x and y, without duplicates.

Null behavior: default

### Function signature

````
list_union(x: LIST, y: LIST) -> LIST

````

### Examples

#### Get the union of two lists of integers

````
RETURN list_union([1,2,3],[3,4,5]) AS res

````

Return:

````
+-------------+
| res         |
+-------------+
| [1,2,3,4,5] |
+-------------+

````

#### Get the union of two lists of strings

````
RETURN list_union(["a","b","c"],["c","d","e"]) AS res

````

Return:

````
+-------------+
| res         |
+-------------+
| [a,b,c,d,e] |
+-------------+

````

## list_sort()

Returns the list sorted by values in ascending order. For more information about the comparison between values, see [Comparison predicate](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/comparison/).

Null behavior: default

### Function signature

````
list_sort(l: LIST) -> LIST

````

### Examples

#### Sort a list of integers in ascending order

````
RETURN list_sort([3,1,null,2,null]) AS res

````

Return:

````
+-------------------+
| res               |
+-------------------+
| [1,2,3,null,null] |
+-------------------+

````

#### Sort a list of strings in ascending order

````
RETURN list_sort(["b","a",null,"c"]) AS res

````

Return:

````
+--------------+
| res          |
+--------------+
| [a,b,c,null] |
+--------------+

````

## list_sum()

Returns the sum of all non-null elements of the list. If there is no non-null elements, returns 0.0. The behavior is similar to aggregation function [sum()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/aggregate/#sum). 

Null behavior: default

### Function signature

````
list_sum(l: LIST) -> UINT64 | INT64 | DOUBLE | DECIMAL

````

### Examples

#### Get the sum of a list of integers

````
RETURN list_sum([1,2,3,4,5]) AS res

````

Return:

````
+-----+
| res |
+-----+
| 15  |
+-----+

````

#### Get the sum of a list of arbitrary-precision numbers

````
RETURN list_sum([1.1,2.2,3.3]) AS res

````

Return:

````
+-----+
| res |
+-----+
| 6.6 |
+-----+

````

## remove_nulls()

Removes all null values from the input list.

Null behavior: default

### Function signature

````
remove_nulls(l: LIST) -> LIST

````

### Examples

#### Remove null values from a list of integers

````
RETURN remove_nulls([1,2,null,3,null,4]) AS res

````

Return:

````
+-----------+
| res       |
+-----------+
| [1,2,3,4] |
+-----------+

````

#### Remove null values from a list of strings

````
RETURN remove_nulls(["a",null,"b","c",null]) AS res

````

Return:

````
+---------+
| res     |
+---------+
| [a,b,c] |
+---------+

````