Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/
Documentation version: v5.3.2

# 列表函数

本文描述悦数图数据库开发版中的列表函数用法，适用于持久图和临时图。

## length()

返回列表中的元素数量。

还可用于返回字符串中的字符数或返回路径的长度。更多信息，请参见[字符串函数`length()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/string/#length)和[图函数`length()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/#length)。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取列表中元素的数量

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

````

返回：

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

````

#### 获取一个空列表的长度

````
RETURN length(null)

````

返回：

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

````

#### 获取一个路径中点的数量

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

````

返回：

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

````

## cardinality()

返回列表或记录中的元素数量。

该函数还可以用于返回路径中的元素数量。更多信息，请参见[图函数`cardinality()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/#cardinality)。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取列表中元素的数量

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

````

返回：

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

````

#### 获取记录中元素的数量

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

````

返回：

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

````

## size()

返回列表中的元素数量、集合中的唯一元素数量、映射中的键值对（条目）数量，或表中的总行数。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取列表中的元素数量

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

````

返回：

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

````

#### 获取集合中的不重复元素数量

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

````

返回：

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

````

#### 获取映射中的不重复键值对数量

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

````

返回：

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

````

#### 获取表中的行数

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

````

返回：

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

````

关于表更新说明：如果在同一条语句中既包含对表的更新操作（例如使用`EXPORT`），又调用了`size()`函数，则`size()`返回的是该更新操作执行前的行数。

在下例（基于[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)）中，`size(result_table)`在`EXPORT`过程中被调用。尽管此时正在向表中增加行，但存储在`sz`中的值反映的是在该批次点导出之前表的快照状态。

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

````

返回：

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

````

## head()

返回列表的第一个元素。

NULL 行为：默认

### 函数签名

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

````

`E`指所有数据类型。

### 示例

#### 获取列表的第一个元素

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

````

返回：

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

````

#### 获取一个路径中的第一个点

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

````

返回：

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

````

## tail()

去除列表的第一个元素。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 去除列表的第一个元素

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

````

返回：

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

````

#### 去除点列表中的第一个点

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

````

返回：

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

````

## back()

返回列表的最后一个元素。

NULL 行为：默认

### 函数签名

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

````

`E`指所有数据类型。

### 示例

#### 获取列表的最后一个元素

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

````

返回：

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

````

#### 获取一个路径中的最后一个点

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

````

返回：

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

````

## range()

返回一个从`start`值到`end`值的整数列表，其中，任意两个连续值之间的差值称为步长`step`，是一个常量。

`step`的值可以是任何非零整数，默认为 1。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取具有默认步长的整数列表

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

````

返回：

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

````

#### 获取具有正步长的整数列表

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

````

返回：

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

````

#### 获取具有负步长的整数列表

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

````

返回：

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

````

#### 步长为 0 时返回错误

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

````

返回：

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

````

## list_slice()

返回一个从`start`值到`end`值的列表切片。

NULL 行为：默认

### 函数签名

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

````

`E`指所有数据类型。

### 参数

- `l`：要切片的源列表。
- `start`：列表 (`l`) 中切片的开始位置。从`0`开始计算源列表位置。
- `end`：列表 (`l`) 中切片的结束位置。从`0`开始计算源列表位置。
- `step`（可选）：任意两个连续值之间的差值，应为任何非零整数，默认为`1`。

参数`start`、`end`和`step`取值为正数时从列表开头开始计数，为负数时从列表末尾开始计数。

### 示例

#### 获取具有正步长的列表切片

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

````

返回：

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

````

#### 获取具有负步长的列表切片

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

````

返回：

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

````

#### 输入负值参数获取列表切片

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

````

返回：

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

````

#### 步长为 0 时返回错误

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

````

返回：

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

````

## trim()

从列表末尾去除指定数量的元素后返回列表。

该函数还可用于去除字符串左侧、右侧或两侧的指定字符串。更多信息，请参见[字符串函数`trim()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/string/#trim)。

NULL 行为：默认

### 函数签名

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

````

### 参数

- `l`：源列表。
- `trim_num`：从源列表末尾移除的元素数量。取值必须大于或等于0，小于`l`的长度。

### 示例

#### 从整数列表中去除末尾两个元素

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

````

返回：

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

````

#### 从嵌套列表中去除末尾两个元素

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

````

返回：

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

````

## zip()

将两个列表中对应位置的元素配对成列表，然后将这些列表组合成一个新的列表。

NULL 行为：默认

### 函数签名

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

````

### 参数

- `l1`、`l2`：源列表。`l1`和`l2`列表中的元素必须是相同数据类型。
- `l1`和`l2`列表中相同位置的元素会进行配对，如果`l1`和`l2`列表长度不同，则返回的列表长度与较短的列表相同，而较长列表中剩余的元素会被忽略。

### 示例

#### 将两个列表中的整数两两配对

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

````

返回：

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

````

#### 将两个列表中的字符串两两配对

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

````

返回：

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

````

## list_distinct()

从输入列表中移除重复值，然后返回一个新的列表。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 移除整型列表中的重复值

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

````

返回：

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

````

#### 移除字符串列表中的重复值

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

````

返回：

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

````

## list_except()

返回存在于列表 x 中但不存在于列表 y 中的元素组成的列表，并移除结果中的重复值。

NULL 行为：默认

### 函数签名

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

````

### 示例

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

````

返回：

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

````

## list_intersect()

返回列表 x 和列表 y 的交集元素组成的列表，并移除结果中的重复值。

NULL 行为：默认

### 函数签名

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

````

### 示例

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

````

返回：

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

````

## list_join()

使用指定的分隔符连接输入列表中的元素，可以使用可选字符串替换列表中的 NULL 值。

NULL 行为：默认

### 函数签名

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

````

- `delimiter`: 用于分隔输入列表中的元素的字符串。
- `replace_null`: 用于替换输入列表中 NULL 值的可选字符串。若未指定，则使用空字符串替代 NULL 值。

### 示例

#### 使用分隔符拼接整型列表

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

````

返回：

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

````

#### 使用分隔符拼接字符串列表，并将 NULL 替换为指定字符

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

````

返回：

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

````

## list_max()

返回输入列表中的最大值。如果列表中包含 NULL 值，则返回 NULL。有关值之间比较规则的更多信息，请参见[比较谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/)。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取整型列表中的最大值

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

````

返回：

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

````

#### 获取字符串列表中的最大值

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

````

返回：

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

````

#### 若列表中包含 NULL 值，则返回 NULL 值

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

````

返回：

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

````

## list_min()

返回输入列表中的最小值。如果列表中包含 NULL 值，则返回 NULL。有关值之间比较规则的更多信息，请参见[比较谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/)。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取整型列表中的最小值

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

````

返回：

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

````

#### 获取字符串列表中的最小值

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

````

返回：

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

````

#### 若列表中包含 NULL 值，则返回 NULL 值

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

````

返回：

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

````

## list_union()

返回列表 x 和列表 y 的并集元素组成的列表，并移除结果中的重复值。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取两个整型列表的并集

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

````

返回：

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

````

#### 获取两个字符串列表的并集

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

````

返回：

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

````

## list_sort()

返回按升序排序后的列表。有关值之间比较规则的更多信息，请参见[比较谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/comparison/)。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 对整型列表进行升序排序

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

````

返回：

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

````

#### 对字符串列表进行升序排序

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

````

返回：

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

````

## list_sum()

返回列表中所有非 NULL 元素的总和。如果列表中没有非 NULL 元素，则返回 0.0。该函数的行为类似于聚合函数 [sum()](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/aggregate/#sum)。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 获取整型列表的总和

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

````

返回：

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

````

#### 获取任意精度数列表的总和

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

````

返回：

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

````

## remove_nulls()

从输入列表中移除所有 NULL 值。

NULL 行为：默认

### 函数签名

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

````

### 示例

#### 移除整型列表中的 NULL 值

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

````

返回：

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

````

#### 移除字符串列表中的 NULL 值

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

````

返回：

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

````