SQL 数组函数

使用数组函数在 SQL 查询中创建和操作 Arrow 数组或列表。

• array_any_value
• array_append
• array_cat
• array_concat
• array_contains
• array_dims
• array_distance
• array_distinct
• array_element
• array_empty
• array_except
• array_extract
• array_has
• array_has_all
• array_has_any
• array_indexof
• array_intersect
• array_join
• array_length
• array_max
• array_min
• array_ndims
• array_pop_back
• array_pop_front
• array_position
• array_positions
• array_prepend
• array_push_back
• array_push_front
• array_remove
• array_remove_all
• array_remove_n
• array_repeat
• array_replace
• array_replace_all
• array_replace_n
• array_resize
• array_reverse
• array_slice
• array_sort
• array_to_string
• array_union
• arrays_overlap
• cardinality
• empty
• flatten
• generate_series
• list_any_value
• list_append
• list_cat
• list_concat
• list_contains
• list_dims
• list_distance
• list_distinct
• list_element
• list_empty
• list_except
• list_extract
• list_has
• list_has_all
• list_has_any
• list_indexof
• list_intersect
• list_join
• list_length
• list_max
• list_ndims
• list_pop_back
• list_pop_front
• list_position
• list_positions
• list_prepend
• list_push_back
• list_push_front
• list_remove
• list_remove_all
• list_remove_n
• list_repeat
• list_replace
• list_replace_all
• list_replace_n
• list_resize
• list_reverse
• list_slice
• list_sort
• list_to_string
• list_union
• make_array
• make_list
• range
• string_to_array
• string_to_list

array_any_value

返回数组中的第一个非空元素。

array_any_value(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_any_value

SELECT array_any_value([NULL, 1, 2, 3]) AS array_any_value

array_append

将元素附加到数组的末尾。

array_append(array, element)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要附加到数组的元素。

别名

• list_append
• array_push_back
• list_push_back

SELECT array_append([1, 2, 3], 4) AS array_append

array_cat

array_concat 的别名。

array_concat

将多个数组连接成一个数组。

array_concat(array[, ..., array_n])

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• array_n：要连接的后续数组列或字面数组。

别名

• array_cat
• list_concat
• list_cat

SELECT array_concat([1, 2], [3, 4], [5, 6]) AS array_concat

array_contains

array_has 的别名。

array_dims

返回数组维度的数组。

array_dims(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_dims

SELECT array_dims([[1, 2, 3], [4, 5, 6]]) AS array_dims

array_distance

返回两个等长输入数组之间的欧几里得距离。

array_distance(array1, array2)

参数

• array1：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• array2：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_distance

SELECT array_distance([1, 2], [1, 4]) AS array_distance

array_distinct

返回数组中的唯一值，并删除重复项。

array_distinct(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_distinct

SELECT array_distinct([1, 3, 2, 3, 1, 2, 4]) AS array_distinct

array_element

从数组中提取索引为 n 的元素。

array_element(array, index)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• index：用于从数组中提取元素的索引。

别名

• array_extract
• list_element
• list_extract

SELECT array_element([1, 2, 3, 4], 3) AS array_element

array_empty

empty 的别名。

array_except

返回一个数组，其中包含第一个数组中不存在于第二个数组中的元素。

array_except(array1, array2)

参数

• array1：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• array2：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_except

SELECT array_except([1, 2, 3, 4], [5, 6, 3, 4]) AS array_except

array_extract

array_element 的别名。

array_has

如果数组包含该元素，则返回 true。

array_has(array, element)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：标量或数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_has
• array_contains
• list_contains

SELECT array_has([1, 2, 3], 2) AS array_has

array_has_all

如果子数组的所有元素都存在于数组中，则返回 true。

array_has_all(array, sub-array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• sub-array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_has_all

SELECT array_has_all([1, 2, 3, 4], [2, 3]) AS array_has_all

array_has_any

如果至少一个元素同时出现在两个数组中，则返回 true。

array_has_any(array, sub-array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• sub-array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_has_any
• arrays_overlap

SELECT array_has_any([1, 2, 3], [3, 4]) AS array_has_any

array_indexof

array_position 的别名。

array_intersect

返回一个数组，其中仅包含同时出现在 array1 和 array2 中的元素。

array_intersect(array1, array2)

参数

• array1：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• array2：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_intersect

SELECT array_intersect([1, 2, 3, 4], [5, 6, 3, 4]) AS array_intersect

SELECT array_intersect([1, 2, 3, 4], [5, 6, 7, 8]) AS array_intersect

array_join

array_to_string 的别名。

array_length

返回数组维度的长度。

array_length(array, dimension)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• dimension：数组维度。默认为 1。

别名

• list_length

SELECT array_length([1, 2, 3, 4, 5]) AS array_length

WITH vars AS (
  SELECT [
    [1, 2, 3, 4, 5],
    [5, 6, 7, 8, 9]
  ] AS example_array
)

SELECT
  array_length(example_array, 1) AS 'dim1_length',
  array_length(example_array, 2) AS 'dim2_length'
FROM vars

array_max

返回数组中的最大值。

array_max(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_max

SELECT array_max([3,1,4,2]) AS array_max

array_min

返回数组中的最小值。

array_min(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

SELECT array_min([3,1,4,2]) AS array_min

array_ndims

返回数组的维度数。

array_ndims(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_ndims

SELECT array_ndims([[1, 2, 3], [4, 5, 6]]) AS array_ndims

array_pop_back

返回不包含最后一个元素的数组。

array_pop_back(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_pop_back

SELECT array_pop_back([1, 2, 3]) AS array_pop_back

array_pop_front

返回不包含第一个元素的数组。

array_pop_front(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_pop_front

SELECT array_pop_front([1, 2, 3]) AS array_pop_front

array_position

返回指定元素在数组中第一次出现的_位置_，如果未找到则返回 NULL。

array_position(array, element, index)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要在数组中搜索位置的元素。
• index：开始搜索的索引（从 1 开始）。默认为 1。

别名

• list_position
• array_indexof
• list_indexof

SELECT array_position([1, 2, 2, 3, 1, 4], 2) AS array_position

SELECT array_position([1, 2, 2, 3, 1, 4], 2, 3) AS array_position

array_positions

搜索数组中的元素，并返回每个出现的位置或索引。

array_positions(array, element)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要在数组中搜索位置的元素。

别名

• list_positions

SELECT array_positions(['John', 'Jane', 'James', 'John'], 'John') AS array_positions

array_prepend

将元素添加到数组的开头。

array_prepend(element, array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要添加到数组开头的元素。

别名

• list_prepend
• array_push_front
• list_push_front

SELECT array_prepend(1, [2, 3, 4]) AS array_prepend

array_push_back

array_append 的别名。

array_push_front

array_prepend 的别名。

array_remove

删除数组中第一个等于给定值的元素。

array_remove(array, element)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要从数组中删除的元素。

别名

• list_remove

SELECT array_remove([1, 2, 2, 3, 2, 1, 4], 2) AS array_remove

array_remove_all

删除数组中所有等于指定值的元素。

array_remove_all(array, element)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要从数组中删除的元素。

别名

• list_remove_all

SELECT array_remove_all([1, 2, 2, 3, 2, 1, 4], 2) AS array_remove_all

array_remove_n

从数组中删除最多 max 个等于指定值的元素。

array_remove_n(array, element, max)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• element：要从数组中删除的元素。
• max：要删除的最大出现次数。

别名

• list_remove_n

SELECT array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2) AS array_remove_n

array_repeat

返回一个包含 count 次的元素的数组。

array_repeat(element, count)

参数

• element：元素表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• count：重复元素的次数。

别名

• list_repeat

SELECT array_repeat(1, 3) AS array_repeat

SELECT array_repeat('John', 3) AS array_repeat

SELECT array_repeat([1, 2], 2) AS array_repeat

array_replace

将指定元素第一次出现的位置替换为另一个指定元素。

array_replace(array, from, to)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• from：要替换的元素。
• to：替换元素。

别名

• list_replace

SELECT array_replace(['John', 'Jane', 'James', 'John'], 'John', 'Joe') AS array_replace

array_replace_all

将指定元素的所有出现位置替换为另一个指定元素。

array_replace_all(array, from, to)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• from：要替换的元素。
• to：替换元素。

别名

• list_replace_all

SELECT array_replace_all(['John', 'Jane', 'James', 'John'], 'John', 'Joe') AS array_replace_all

array_replace_n

将指定元素最多 max 次的出现位置替换为另一个指定元素。

array_replace_n(array, from, to, max)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• from：要替换的元素。
• to：替换元素。
• max：要替换的最大出现次数。

别名

• list_replace_n

SELECT array_replace_n(['John', 'Jane', 'James', 'John', 'John'], 'John', 'Joe', 2) AS array_replace_n

array_resize

将列表的大小调整为包含 size 个元素。使用 value 初始化新元素。将数组大小调整为指定大小。如果扩展，则用指定值（或 NULL，如果未提供）填充新元素。如果收缩，则截断多余的元素。

array_resize(array, size, value)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• size：数组的新大小。
• value：用于新元素的值。默认为 NULL。

别名

• list_resize

SELECT array_resize([1, 2, 3], 5, 0) AS array_resize

array_reverse

返回元素顺序颠倒的数组。

array_reverse(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_reverse

SELECT array_reverse([1, 2, 3, 4]) AS array_reverse

array_slice

根据从 1 开始的起始和结束位置返回数组的切片。

array_slice(array, begin, end)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• begin：第一个元素的索引。如果为负数，则从数组末尾开始倒数。
• end：最后一个元素的索引。如果为负数，则从数组末尾开始倒数。
• stride：数组切片的步幅。默认为 1。

别名

• list_slice

SELECT array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6) AS array_slice

array_sort

对数组中的元素进行排序。如果元素是数字，则按数值顺序排序。如果元素是字符串，则按字典顺序排序。

array_sort(array, sort_order, sort_nulls)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• sort_order：排序顺序（'ASC' _（默认）_ 或 'DESC'）。
• sort_nulls：将 NULL 值排在前面或后面（'NULLS FIRST' _（默认）_ 或 'NULLS LAST'）。

别名

• list_sort

SELECT array_sort([3, 1, 2]) AS array_sort

SELECT array_sort(['banana', 'apple', 'cherry'], 'DESC') AS array_sort

SELECT
  array_sort(
    ['banana', 'apple', NULL, 'cherry', NULL],
    'ASC',
    'NULLS LAST'
  ) AS array_sort

array_to_string

通过使用指定的分隔符连接所有元素，将数组转换为字符串。

array_to_string(array, delimiter[, null_string])

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• delimiter：数组元素分隔符。
• null_string：可选。用于替换数组中 NULL 值的字符串。如果未提供，则忽略 NULL 元素。

别名

• list_to_string
• array_join
• list_join

SELECT array_to_string([1,2,3,4,5,6,7,8], ',') AS array_to_string

SELECT array_to_string([[1,2,3,4,5,NULL,7,8,NULL]], '-', '?') AS array_to_string

array_union

返回一个包含两个数组中都存在的元素的数组（所有元素来自）。返回一个包含两个输入数组中的所有唯一元素的数组，并删除重复项。

array_union(array1, array2)

参数

• array1：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。
• array2：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• list_union

SELECT array_union([1, 2, 3, 4], [5, 6, 3, 4]) AS array_union

arrays_overlap

array_has_any 的别名。

cardinality

返回数组中的总元素数。

cardinality(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

SELECT cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]) AS cardinality

empty

对于空数组返回 true，对于非空数组返回 false。

empty(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

别名

• array_empty
• list_empty

SELECT empty(['apple']) AS empty

flatten

将嵌套数组展平成单层数组。

• 递归地展平任何嵌套深度的数组
• 如果数组已经是扁平的，则不变地返回

结果包含所有嵌套数组中的所有元素，形成一个扁平的数组。

flatten(array)

参数

• array：数组表达式。可以是常量、列或函数，以及任何数组运算符的组合。

SELECT flatten([[1, 2], [3, 4]]) AS flattened

generate_series

返回一个在指定 start 和 stop 值之间生成的，以指定 step 为间隔的数组。

范围 start..stop 包含所有大于或等于 start 且小于或等于 stop 的值（start <= x <= stop）。如果 start 大于或等于 stop（start >= stop），则函数返回一个空数组。

generate_series 类似于 range，但包含上界（stop）在输出数组中。

generate_series(start, stop, step)

参数

• start：序列的开始。支持整数、时间戳、日期或可强制转换为 Date32 的字符串类型。
• stop：序列的上限。支持整数、时间戳、日期或可强制转换为 Date32 的字符串类型。类型必须与 start 相同。
• step：以 step 递增（不能为 0）。小于一天的步长仅支持 TIMESTAMP 类型的范围。

相关函数

range

SELECT generate_series(1,5) AS generate_series

SELECT
  generate_series(
    DATE '2025-03-01',
    DATE '2025-08-01',
    INTERVAL '1 month'
  ) AS generate_series

SELECT
  generate_series(
    '2025-01-01T00:00:00Z'::timestamp,
    '2025-01-01T06:00:00Z'::timestamp,
    INTERVAL '2 hours'
  ) AS generate_series

list_any_value

array_any_value 的别名。

list_append

array_append 的别名。

list_cat

array_concat 的别名。

list_concat

array_concat 的别名。

list_contains

array_has 的别名。

list_dims

array_dims 的别名。

list_distance

array_distance 的别名。

list_distinct

array_distinct 的别名。

list_element

array_element 的别名。

list_empty

empty 的别名。

list_except

array_except 的别名。

list_extract

array_element 的别名。

list_has

array_has 的别名。

list_has_all

array_has_all 的别名。

list_has_any

array_has_any 的别名。

list_indexof

array_position 的别名。

list_intersect

array_intersect 的别名。

list_join

array_to_string 的别名。

list_length

array_length 的别名。

list_max

array_max 的别名。

list_ndims

array_ndims 的别名。

list_pop_back

array_pop_back 的别名。

list_pop_front

array_pop_front 的别名。

list_position

array_position 的别名。

list_positions

array_positions 的别名。

list_prepend

array_prepend 的别名。

list_push_back

array_append 的别名。

list_push_front

array_prepend 的别名。

list_remove

array_remove 的别名。

list_remove_all

array_remove_all 的别名。

list_remove_n

array_remove_n 的别名。

list_repeat

array_repeat 的别名。

list_replace

array_replace 的别名。

list_replace_all

array_replace_all 的别名。

list_replace_n

array_replace_n 的别名。

list_resize

array_resize 的别名。

list_reverse

array_reverse 的别名。

list_slice

array_slice 的别名。

list_sort

array_sort 的别名。

list_to_string

array_to_string 的别名。

list_union

array_union 的别名。

make_array

使用指定的输入表达式创建数组。

make_array(expression1[, ..., expression_n])

参数

• expression_n：要包含在输出数组中的表达式。可以是常量、列或函数，以及任何算术或字符串运算符的组合。

别名

• make_list

SELECT make_array(1, 2, 3, 4, 5) AS make_array

make_list

make_array 的别名。

range

返回一个在指定 start 和 stop 值之间生成的，以指定 step 为间隔的数组。

范围 start..stop 包含所有大于或等于 start 且小于 stop 的值（start <= x < stop）。如果 start 大于或等于 stop（start >= stop），则函数返回一个空数组。

range 类似于 generate_series，但不包含上界（stop）在输出数组中。

range(start, stop, step)

参数

• start：序列的开始。支持整数、时间戳、日期或可强制转换为 Date32 的字符串类型。
• stop：序列的上限。支持整数、时间戳、日期或可强制转换为 Date32 的字符串类型。类型必须与 start 相同。
• step：以 step 递增（不能为 0）。小于一天的步长仅支持 TIMESTAMP 类型的范围。

相关函数

generate_series

SELECT range(1, 5, 1) AS range

SELECT
  range(
    DATE '2025-03-01',
    DATE '2025-08-01',
    INTERVAL '1 month'
  ) AS range

SELECT
  range(
    '2025-01-01T00:00:00Z'::timestamp,
    '2025-01-01T06:00:00Z'::timestamp,
    INTERVAL '2 hours'
  ) AS range

string_to_array

根据分隔符将字符串拆分为子字符串数组。任何匹配可选 null_str 参数的子字符串都将被替换为 NULL。

string_to_array(str, delimiter[, null_str])

参数

• str：要拆分的字符串表达式。
• delimiter：用于拆分的delimiter字符串。
• null_str：_（可选）_ 要替换为 NULL 的子字符串值。

别名

• string_to_list

SELECT string_to_array('abc, def, ghi', ', ') AS string_to_array

SELECT string_to_array('abc##def', '##') AS string_to_array

SELECT string_to_array('abc def', ' ', 'def') AS string_to_array

string_to_list

string_to_array 的别名。