数组函数
本页收录 SQL 查询中可用的数组（List 类型）标量函数。多数函数同时提供 array_* 与 list_* 两套等价别名，行为完全相同，可互换使用。
| 函数 | 别名 | 说明 |
|---|---|---|
array_any_value |
list_any_value |
返回数组中第一个非 null 元素 |
array_append |
list_append、array_push_back、list_push_back |
将元素追加到数组末尾 |
array_concat |
array_cat、list_concat、list_cat |
将多个数组连接成一个数组 |
array_dims |
list_dims |
返回由数组各维度组成的数组 |
array_distance |
list_distance |
返回两个等长数组间的欧几里得距离 |
array_distinct |
list_distinct |
返回数组去重后的值 |
array_element |
array_extract、list_element、list_extract |
返回数组中指定下标处的元素 |
array_except |
list_except |
返回在第一个数组但不在第二个数组中的元素 |
array_has |
list_has、array_contains、list_contains |
数组包含指定元素时返回 true |
array_has_all |
list_has_all |
第一个数组包含第二个数组全部元素时返回 true |
array_has_any |
list_has_any |
两个数组有任意共同元素时返回 true |
array_intersect |
list_intersect |
返回两个数组的交集 |
array_length |
list_length |
返回数组指定维度的长度 |
array_ndims |
list_ndims |
返回数组的维度数 |
array_pop_back |
list_pop_back |
返回移除最后一个元素后的数组 |
array_pop_front |
list_pop_front |
返回移除第一个元素后的数组 |
array_position |
list_position、array_indexof、list_indexof |
返回指定元素在数组中首次出现的位置 |
array_positions |
list_positions |
返回指定元素所有出现位置组成的列表 |
array_prepend |
list_prepend、array_push_front、list_push_front |
将元素插入到数组开头 |
array_remove |
list_remove |
移除数组中第一个等于给定值的元素 |
array_remove_all |
list_remove_all |
移除数组中所有等于给定值的元素 |
array_remove_n |
list_remove_n |
移除数组中前 n 个等于给定值的元素 |
array_repeat |
list_repeat |
返回将元素重复 count 次组成的数组 |
array_replace |
list_replace |
将指定元素的首次出现替换为另一指定元素 |
array_replace_all |
list_replace_all |
将所有出现的指定元素替换为另一元素 |
array_replace_n |
list_replace_n |
将前 n 次出现的指定元素替换为另一元素 |
array_resize |
list_resize |
调整数组大小为指定的元素个数 |
array_reverse |
list_reverse |
返回元素顺序反转后的数组 |
array_slice |
list_slice |
返回数组的指定区间切片 |
array_sort |
list_sort |
对数组排序 |
array_to_string |
list_to_string、array_join、list_join |
将数组每个元素转换为其文本表示 |
array_union |
list_union |
返回两个数组的并集（去重） |
cardinality |
— | 返回数组中元素的总数 |
empty |
array_empty、list_empty |
空数组返回 true，非空数组返回 false |
flatten |
— | 将嵌套数组转换为扁平数组 |
generate_series |
— | 与 range 函数类似，但包含上界 |
make_array |
make_list |
使用指定的输入表达式构造数组 |
range |
— | 生成指定起止与步长的数组 |
string_to_array |
string_to_list |
按分隔符将字符串拆分为子串数组 |
array_any_value
返回数组中第一个非 null 的元素。
语法：array_any_value(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_any_value
示例：
1> select array_any_value([NULL, 1, 2, 3]) AS array_any_value;
2+-----------------+
3| array_any_value |
4+-----------------+
5| 1 |
6+-----------------+array_append
将一个元素追加到数组的末尾。
语法：array_append(array, element)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：要追加到数组末尾的元素。
别名：list_append、array_push_back、list_push_back
示例：
1> select array_append([1, 2, 3], 4) AS array_append;
2+--------------+
3| array_append |
4+--------------+
5| [1, 2, 3, 4] |
6+--------------+array_concat
将多个数组连接成一个数组。
语法：array_concat(array[, ..., array_n])
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。array_n：要连接的其他数组表达式。
别名：array_cat、list_concat、list_cat
示例：
1> select array_concat([1, 2], [3, 4], [5, 6]) AS array_concat;
2+--------------------+
3| array_concat |
4+--------------------+
5| [1, 2, 3, 4, 5, 6] |
6+--------------------+array_dims
返回一个由该数组的各维度组成的数组。
语法：array_dims(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_dims
示例：
1> select array_dims([[1, 2, 3], [4, 5, 6]]) AS array_dims;
2+------------+
3| array_dims |
4+------------+
5| [2, 3] |
6+------------+array_distance
返回两个等长输入数组之间的欧几里得距离（Euclidean distance）。
语法：array_distance(array1, array2)
参数：
array1：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。array2：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_distance
示例：
1> select array_distance([1, 2], [1, 4]) AS array_distance;
2+----------------+
3| array_distance |
4+----------------+
5| 2.0 |
6+----------------+array_distinct
去除重复元素后，返回数组中的不同值。
语法：array_distinct(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_distinct
示例：
1> select array_distinct([1, 3, 2, 3, 1, 2, 4]) AS array_distinct;
2+----------------+
3| array_distinct |
4+----------------+
5| [1, 2, 3, 4] |
6+----------------+array_element
返回数组中指定下标处的元素。下标从 1 开始；越界返回 NULL；负数下标从末尾开始计数。
语法：array_element(array, index)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。index：要返回元素的下标（从 1 开始）。
别名：array_extract、list_element、list_extract
示例：
1> select array_element([5, 6, 7, 8], 2) AS array_element;
2+---------------+
3| array_element |
4+---------------+
5| 6 |
6+---------------+
7> select array_element([5, 6, 7, 8], 10) AS array_element;
8+---------------+
9| array_element |
10+---------------+
11| |
12+---------------+array_except
返回一个数组，其元素出现在第一个数组中、但不出现在第二个数组中。
语法：array_except(array1, array2)
参数：
array1：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。array2：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_except
示例：
1> select array_except([1, 2, 3, 4], [3, 4, 5, 6]) AS array_except;
2+--------------+
3| array_except |
4+--------------+
5| [1, 2] |
6+--------------+array_has
如果数组包含该元素，则返回 true。
语法：array_has(array, element)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：标量或数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_has、array_contains、list_contains
示例：
1> select array_has([1, 2, 3], 2) AS array_has;
2+-----------+
3| array_has |
4+-----------+
5| true |
6+-----------+array_has_all
如果第一个数组包含第二个数组的所有元素，则返回 true。
语法：array_has_all(array, sub_array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。sub_array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_has_all
示例：
1> select array_has_all([1, 2, 3, 4], [2, 3]) AS array_has_all;
2+---------------+
3| array_has_all |
4+---------------+
5| true |
6+---------------+array_has_any
如果两个数组存在任意共同元素，则返回 true。
语法：array_has_any(array1, array2)
参数：
array1：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。array2：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_has_any
示例：
1> select array_has_any([1, 2, 3], [3, 4, 5]) AS array_has_any;
2+---------------+
3| array_has_any |
4+---------------+
5| true |
6+---------------+array_intersect
返回两个数组的交集（同时出现在两个数组中的元素）。
语法：array_intersect(array1, array2)
参数：
array1：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。array2：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_intersect
示例：
1> select array_intersect([1, 2, 3, 4], [3, 4, 5, 6]) AS array_intersect;
2+-----------------+
3| array_intersect |
4+-----------------+
5| [3, 4] |
6+-----------------+array_length
返回数组指定维度的长度。
语法：array_length(array, dimension)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。dimension：数组维度。
别名：list_length
示例：
1> select array_length([1, 2, 3, 4, 5], 1) AS array_length;
2+--------------+
3| array_length |
4+--------------+
5| 5 |
6+--------------+array_ndims
返回数组的维度数。
语法：array_ndims(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_ndims
示例：
1> select array_ndims([[1, 2, 3], [4, 5, 6]]) AS array_ndims;
2+-------------+
3| array_ndims |
4+-------------+
5| 2 |
6+-------------+array_pop_back
返回移除最后一个元素后的数组。
语法：array_pop_back(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_pop_back
示例：
1> select array_pop_back([1, 2, 3]) AS array_pop_back;
2+----------------+
3| array_pop_back |
4+----------------+
5| [1, 2] |
6+----------------+array_pop_front
返回移除第一个元素后的数组。
语法：array_pop_front(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_pop_front
示例：
1> select array_pop_front([1, 2, 3]) AS array_pop_front;
2+-----------------+
3| array_pop_front |
4+-----------------+
5| [2, 3] |
6+-----------------+array_position
返回指定元素在数组中第一次出现的位置。
语法：array_position(array, element)、array_position(array, element, index)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：要在数组中查找位置的元素。index：开始搜索的索引位置。
别名：list_position、array_indexof、list_indexof
示例：
1> select array_position([1, 2, 2, 3, 1, 4], 2) AS array_position;
2+----------------+
3| array_position |
4+----------------+
5| 2 |
6+----------------+
7> select array_position([1, 2, 2, 3, 1, 4], 2, 3) AS array_position;
8+----------------+
9| array_position |
10+----------------+
11| 3 |
12+----------------+array_positions
返回指定元素在数组中所有出现位置组成的列表（位置从 1 开始）。
语法：array_positions(array, element)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：要在数组中查找位置的元素。
别名：list_positions
示例：
1> select array_positions([1, 2, 2, 3, 2], 2) AS array_positions;
2+-----------------+
3| array_positions |
4+-----------------+
5| [2, 3, 5] |
6+-----------------+array_prepend
将一个元素插入到数组的开头。
语法：array_prepend(element, array)
参数：
element：要插入到数组开头的元素。array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_prepend、array_push_front、list_push_front
示例：
1> select array_prepend(1, [2, 3, 4]) AS array_prepend;
2+---------------+
3| array_prepend |
4+---------------+
5| [1, 2, 3, 4] |
6+---------------+array_remove
从数组中移除第一个等于给定值的元素。
语法：array_remove(array, element)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：要从数组中移除的元素。
别名：list_remove
示例：
1> select array_remove([1, 2, 2, 3, 2, 1, 4], 2) AS array_remove;
2+--------------------+
3| array_remove |
4+--------------------+
5| [1, 2, 3, 2, 1, 4] |
6+--------------------+array_remove_all
移除数组中所有等于给定值的元素。
语法：array_remove_all(array, element)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：要从数组中移除的元素。
别名：list_remove_all
示例：
1> select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2) AS array_remove_all;
2+------------------+
3| array_remove_all |
4+------------------+
5| [1, 3, 1, 4] |
6+------------------+array_remove_n
移除数组中前 n 个等于给定值的元素。
语法：array_remove_n(array, element, max)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。element：要从数组中移除的元素。max：最多移除的元素个数。
别名：list_remove_n
示例：
1> select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2) AS array_remove_n;
2+-----------------+
3| array_remove_n |
4+-----------------+
5| [1, 3, 2, 1, 4] |
6+-----------------+array_repeat
返回一个包含元素重复 count 次的数组。
语法：array_repeat(element, count)
参数：
element：元素表达式。可以是常量、列或函数，以及数组运算符的任意组合。count：元素重复的次数。
别名：list_repeat
示例：
1> select array_repeat(1, 3) AS array_repeat;
2+--------------+
3| array_repeat |
4+--------------+
5| [1, 1, 1] |
6+--------------+array_replace
将指定元素的第一次出现替换为另一个指定元素。
语法：array_replace(array, from, to)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。from：初始元素。to：最终元素。
别名：list_replace
示例：
1> select array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5) AS array_replace;
2+-----------------------+
3| array_replace |
4+-----------------------+
5| [1, 5, 2, 3, 2, 1, 4] |
6+-----------------------+array_replace_all
将数组中所有出现的指定元素替换为另一元素。
语法：array_replace_all(array, from, to)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。from：初始元素。to：最终元素。
别名：list_replace_all
示例：
1> select array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5) AS array_replace_all;
2+-----------------------+
3| array_replace_all |
4+-----------------------+
5| [1, 5, 5, 3, 5, 1, 4] |
6+-----------------------+array_replace_n
将数组中前 n 次出现的指定元素替换为另一元素。
语法：array_replace_n(array, from, to, max)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。from：初始元素。to：最终元素。max：最多替换的次数。
别名：list_replace_n
示例：
1> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2) AS array_replace_n;
2+-----------------------+
3| array_replace_n |
4+-----------------------+
5| [1, 5, 5, 3, 2, 1, 4] |
6+-----------------------+array_resize
调整列表大小，使其包含 size 个元素。新元素用 value 初始化；若未设置 value，则以空值初始化。
语法：array_resize(array, size, value)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。size：给定数组的新大小。value：定义新元素的值；若未设置 value，则为空。
别名：list_resize
示例：
1> select array_resize([1, 2, 3], 5, 0) AS array_resize;
2+-----------------+
3| array_resize |
4+-----------------+
5| [1, 2, 3, 0, 0] |
6+-----------------+array_reverse
返回元素顺序反转后的数组。
语法：array_reverse(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_reverse
示例：
1> select array_reverse([1, 2, 3, 4]) AS array_reverse;
2+---------------+
3| array_reverse |
4+---------------+
5| [4, 3, 2, 1] |
6+---------------+array_slice
返回数组的指定区间切片（下标从 1 开始，含 begin 与 end）。
语法：array_slice(array, begin, end[, stride])
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。begin：切片起始下标（从 1 开始，包含）。end：切片结束下标（包含）。stride：可选。切片步长。
别名：list_slice
示例：
1> select array_slice([1, 2, 3, 4, 5], 2, 4) AS array_slice;
2+-------------+
3| array_slice |
4+-------------+
5| [2, 3, 4] |
6+-------------+array_sort
对数组排序。
语法：array_sort(array, desc, nulls_first)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。desc：是否按降序排序（ASC或DESC）。nulls_first：是否将 null 排在前面（NULLS FIRST或NULLS LAST）。
别名：list_sort
示例：
1> select array_sort([3, 1, 2]) AS array_sort;
2+------------+
3| array_sort |
4+------------+
5| [1, 2, 3] |
6+------------+array_to_string
将数组中每个元素转换为其文本表示。
语法：array_to_string(array, delimiter[, null_string])
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。delimiter：数组元素分隔符。null_string：可选。用于替换数组中 null 值的字符串。若未提供，null 将按默认行为处理。
别名：list_to_string、array_join、list_join
示例：
1> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ',') AS array_to_string;
2+-----------------+
3| array_to_string |
4+-----------------+
5| 1,2,3,4,5,6,7,8 |
6+-----------------+array_union
返回两个数组的并集（去重）。
语法：array_union(array1, array2)
参数：
array1：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。array2：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：list_union
示例：
1> select array_union([1, 2, 3], [3, 4, 5]) AS array_union;
2+-----------------+
3| array_union |
4+-----------------+
5| [1, 2, 3, 4, 5] |
6+-----------------+cardinality
返回数组中元素的总数。
语法：cardinality(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
示例：
1> select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]) AS cardinality;
2+-------------+
3| cardinality |
4+-------------+
5| 8 |
6+-------------+empty
空数组返回 true，非空数组返回 false。
语法：empty(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
别名：array_empty、list_empty
示例：
1> select empty([1]) AS empty;
2+-------+
3| empty |
4+-------+
5| false |
6+-------+flatten
将数组的数组转换为扁平数组。
- 适用于任意深度的嵌套数组
- 不会改变已经是扁平的数组
扁平化后的数组包含所有源数组中的全部元素。
语法：flatten(array)
参数：
array：数组表达式。可以是常量、列或函数，以及数组运算符的任意组合。
示例：
1> select flatten([[1, 2], [3, 4]]) AS flatten;
2+--------------+
3| flatten |
4+--------------+
5| [1, 2, 3, 4] |
6+--------------+generate_series
与 range 函数类似，但包含上界。
语法：generate_series(start, stop, step)
参数：
start：序列的起点。支持整数、时间戳、日期，或可强制转换为 Date32 的字符串类型。stop：序列的终点（包含）。类型必须与 start 相同。step：步长（不能为 0）。小于一天的步长仅在时间戳范围下支持。
示例：
1> select generate_series(1, 3) AS generate_series;
2+-----------------+
3| generate_series |
4+-----------------+
5| [1, 2, 3] |
6+-----------------+make_array
使用指定的输入表达式构造并返回一个数组。
语法：make_array(expression1[, ..., expression_n])
参数：
expression_n：要包含在输出数组中的表达式。可以是常量、列或函数，以及算术或字符串运算符的任意组合。
别名：make_list
示例：
1> select make_array(1, 2, 3, 4, 5) AS make_array;
2+-----------------+
3| make_array |
4+-----------------+
5| [1, 2, 3, 4, 5] |
6+-----------------+range
返回一个从 start 到 stop、步长为 step 的数组。区间 start..stop 包含所有满足 start <= x < stop 的值；若 start >= stop 则为空。step 不能为 0。
语法：range(start, stop, step)
参数：
start：范围的起点。支持整数、时间戳、日期，或可强制转换为 Date32 的字符串类型。stop：范围的终点（不包含）。类型必须与 start 相同。step：步长（不能为 0）。小于一天的步长仅在时间戳范围下支持。
示例：
1> select range(2, 10, 3) AS range;
2+-----------+
3| range |
4+-----------+
5| [2, 5, 8] |
6+-----------+string_to_array
按分隔符将字符串拆分为子串数组。与可选参数 null_str 匹配的子串会被替换为 NULL。
语法：string_to_array(str, delimiter[, null_str])
参数：
str：要拆分的字符串表达式。delimiter：用于拆分的分隔符字符串。null_str：要被替换为NULL的子串值。
别名：string_to_list
示例：
1> select string_to_array('abc##def', '##') AS string_to_array;
2+-----------------+
3| string_to_array |
4+-----------------+
5| [abc, def] |
6+-----------------+评价此篇文章