列表函数¶
本文描述悦数图数据库开发版中的列表函数用法，适用于持久图和临时图。
length()¶
返回列表中的元素数量。
还可用于返回字符串中的字符数或返回路径的长度。更多信息，请参见字符串函数length()和图函数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()。
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()返回的是该更新操作执行前的行数。
在下例（基于示例数据集）中，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()。
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。有关值之间比较规则的更多信息，请参见比较谓词。
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。有关值之间比较规则的更多信息，请参见比较谓词。
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()¶
返回按升序排序后的列表。有关值之间比较规则的更多信息，请参见比较谓词。
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()。
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] |
+---------+