数组函数

array

引入于：v1.1

根据函数参数创建一个数组。

参数必须是常量，且其类型必须具有共同的超类型。必须至少传入一个参数，否则无法确定要创建哪种类型的数组。这意味着不能使用此函数来创建空数组。要创建空数组，请使用 emptyArray* 函数。

可以使用 [ ] 运算符实现相同的功能。

语法

array(x1 [, x2, ..., xN])

参数

x1 — 任意类型 T 的常量值。如果只提供此参数，数组的类型为 T。- [, x2, ..., xN] — 其他 N 个常量值，与 x1 具有共同的超类型

返回值

返回一个数组，其中 'T' 是所有传入参数的最小公共类型。Array(T)

示例

有效用法

SELECT array(toInt32(1), toUInt16(2), toInt8(3)) AS a, toTypeName(a)

┌─a───────┬─toTypeName(a)─┐
│ [1,2,3] │ Array(Int32)  │
└─────────┴───────────────┘

无效用法

SELECT array(toInt32(5), toDateTime('1998-06-16'), toInt8(5)) AS a, toTypeName(a)

Received exception from server (version 25.4.3):
Code: 386. DB::Exception: Received from localhost:9000. DB::Exception:
There is no supertype for types Int32, DateTime, Int8 ...

arrayAUCPR

引入版本：v20.4

计算精确率-召回率（PR）曲线下的面积。精确率-召回率曲线是通过在所有阈值下，以精确率为 y 轴、召回率为 x 轴绘制得到的。取值范围为 0 到 1，值越大表示模型性能越好。在处理类别不平衡的数据集时，PR AUC 尤其有用，在这些场景下，相比 ROC AUC，它能提供更清晰的性能对比。更多详情请参见这里、这里以及这里。

语法

arrayAUCPR(scores, labels[, partial_offsets])

别名: arrayPRAUC

参数

cores — 预测模型给出的得分。Array((U)Int*) 或 Array(Float*)
labels — 样本标签，通常正样本为 1，负样本为 0。Array((U)Int*) 或 Array(Enum)
partial_offsets —
可选。一个由三个非负整数组成的 Array(T)，用于计算 PR 曲线下的部分面积（等价于 PR 空间中的一条垂直带状区域），而不是整个 AUC。此选项对于 PR AUC 的分布式计算非常有用。该数组必须包含以下元素 [higher_partitions_tp, higher_partitions_fp, total_positives]。
- higher_partitions_tp：得分更高的各分区中正标签的数量。
- higher_partitions_fp：得分更高的各分区中负标签的数量。
- total_positives：整个数据集中正样本的总数。

注意

当使用 arr_partial_offsets 时，arr_scores 和 arr_labels 应该只包含整个数据集的一个分区，即某个得分区间内的样本。数据集应被划分为连续的分区，每个分区包含得分落在特定范围内的数据子集。例如：

一个分区可以包含区间 [0, 0.5) 内的所有得分。
另一个分区可以包含区间 [0.5, 1.0] 内的得分。

返回值

返回精确率-召回率（PR）曲线下的面积。Float64

示例

使用示例

SELECT arrayAUCPR([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1]);

┌─arrayAUCPR([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1])─┐
│                              0.8333333333333333 │
└─────────────────────────────────────────────────┘

arrayAll

自 v1.1 起引入

如果 lambda func(x [, y1, y2, ... yN]) 对所有元素都返回 true，则返回 1，否则返回 0。

语法

arrayAll(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 作用于源数组元素（x）和条件数组（y）的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
cond1_arr, ... — 可选。N 个条件数组，为 lambda 函数提供附加参数。Array(T)

返回值

如果 lambda 函数对所有元素都返回 true，则返回 1，否则返回 0。UInt8

示例

所有元素均匹配

SELECT arrayAll(x, y -> x=y, [1, 2, 3], [1, 2, 3])

并非所有元素都匹配

SELECT arrayAll(x, y -> x=y, [1, 2, 3], [1, 1, 1])

arrayAvg

自 v21.1 版本引入

返回源数组中元素的平均值。

如果指定了 lambda 函数 func，则返回该 lambda 结果的元素的平均值。

语法

arrayAvg([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 可选。一个对源数组 (x) 和条件数组 (y) 的元素进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。作为附加参数传递给 lambda 函数的 N 个条件数组。Array(T)

返回值

返回源数组中元素的平均值；如果提供了 lambda 函数，则返回 lambda 结果元素的平均值。Float64

示例

基础示例

SELECT arrayAvg([1, 2, 3, 4]);

2.5

与 lambda 函数配合使用

SELECT arrayAvg(x, y -> x*y, [2, 3], [2, 3]) AS res;

6.5

arrayCompact

自 v20.1 起引入

从数组中删除连续的重复元素，包括 null 值。结果数组中各元素的顺序与源数组中的顺序一致。

语法

arrayCompact(arr)

参数

arr — 要进行去重的数组。Array(T)

返回值

返回一个不包含重复值的数组 Array(T)

示例

使用示例

SELECT arrayCompact([1, 1, nan, nan, 2, 3, 3, 3]);

[1,nan,2,3]

arrayConcat

自 v1.1 版本引入

将传入的数组参数合并为一个数组。

语法

arrayConcat(arr1 [, arr2, ... , arrN])

参数

arr1 [, arr2, ... , arrN] — 要拼接的 N 个数组。Array(T)

返回值

返回一个由所有输入数组拼接得到的单个数组。Array(T)

示例

用法示例

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

[1, 2, 3, 4, 5, 6]

arrayCount

引入版本：v1.1

返回使 func(arr1[i], ..., arrN[i]) 返回 true 的元素个数。如果未指定 func，则返回数组中非零元素的个数。

arrayCount 是一个高阶函数。

语法

arrayCount([func, ] arr1, ...)

参数

func — 可选。应用于数组中每个元素的函数。Lambda function
arr1, ..., arrN — N 个数组。Array(T)

返回值

返回 func 返回 true 的元素数量。否则，返回数组中非零元素的数量。UInt32

示例

用法示例

SELECT arrayCount(x -> (x % 2), groupArray(number)) FROM numbers(10)

arrayCumSum

引入版本：v1.1

返回一个数组，数组中的元素是源数组元素的前缀（累积）和。若指定了一个 lambda 函数，则会在每个位置对数组元素应用该 lambda 后再进行求和。

语法

arrayCumSum([func,] arr1[, arr2, ... , arrN])

参数

func — 可选。在每个位置对数组元素进行处理的 lambda 函数。Lambda function
arr1 — 源数值数组。Array(T)
[arr2, ..., arrN] — 可选。与 arr1 大小相同的其他数组，如果指定了 lambda 函数，则作为该函数的参数传入。Array(T)

返回值

返回一个数组，包含源数组中元素的部分和（前缀和）。结果类型与输入数组的数值类型相同。Array(T)

示例

基本用法

SELECT arrayCumSum([1, 1, 1, 1]) AS res

[1, 2, 3, 4]

使用 lambda 表达式

SELECT arrayCumSum(x -> x * 2, [1, 2, 3]) AS res

[2, 6, 12]

arrayCumSumNonNegative

引入版本：v18.12

返回源数组元素的部分（前缀、累积）和组成的数组，并将任何为负的累积和值替换为零。若指定了 lambda 函数，则在每个位置先对数组元素应用该 lambda，再根据结果计算累积和。

语法

arrayCumSumNonNegative([func,] arr1[, arr2, ... , arrN])

参数

func — 可选。应用到数组各位置元素的 lambda 函数。Lambda function
arr1 — 数值类型的源数组。Array(T)
[arr2, ..., arrN] — 可选。与 arr1 大小相同的其他数组，如果指定了 lambda 函数，则作为参数传递给该函数。Array(T)

返回值

返回一个数组，其元素为源数组元素的部分和（累计和），其中所有为负的累计和都会被替换为 0。结果类型与输入数组的数值类型相同。Array(T)

示例

基本用法

SELECT arrayCumSumNonNegative([1, 1, -4, 1]) AS res

[1, 2, 0, 1]

使用 lambda

SELECT arrayCumSumNonNegative(x -> x * 2, [1, -2, 3]) AS res

[2, 0, 6]

arrayDifference

自 v1.1 起引入

计算由相邻数组元素的差值构成的数组。结果数组的第一个元素为 0，第二个元素为 arr[1] - arr[0]，第三个为 arr[2] - arr[1]，以此类推。结果数组中元素的类型由减法的类型推导规则决定（例如 UInt8 - UInt8 = Int16）。

语法

arrayDifference(arr)

参数

arr — 要计算相邻元素之间差值的数组。Array(T)

返回值

返回一个包含相邻数组元素差值的数组 UInt*

示例

用法示例

SELECT arrayDifference([1, 2, 3, 4]);

[0,1,1,1]

结果类型为 Int64 时发生溢出的示例

SELECT arrayDifference([0, 10000000000000000000]);

┌─arrayDifference([0, 10000000000000000000])─┐
│ [0,-8446744073709551616]                   │
└────────────────────────────────────────────┘

arrayDistinct

引入版本：v1.1

返回一个仅包含原数组中各不相同元素的数组。

语法

arrayDistinct(arr)

参数

arr — 要从中提取唯一元素的数组。Array(T)

返回值

返回一个包含唯一元素的数组 Array(T)

示例

用法示例

SELECT arrayDistinct([1, 2, 2, 3, 1]);

[1,2,3]

arrayDotProduct

引入版本：v23.5

返回两个数组的点积。

注意

两个向量的长度必须相等。Array 和 Tuple 也可以包含不同类型的元素。

语法

arrayDotProduct(v1, v2)

参数

v1 — 第一个向量。Array((U)Int* | Float* | Decimal) 或 Tuple((U)Int* | Float* | Decimal)
v2 — 第二个向量。Array((U)Int* | Float* | Decimal) 或 Tuple((U)Int* | Float* | Decimal)

返回值

两个向量的点积。

注意

返回类型由参数类型决定。如果 Array 或 Tuple 中包含不同类型的元素，则结果类型为它们的超类型。

(U)Int* 或 Float* 或 Decimal

示例

Array 示例

SELECT arrayDotProduct([1, 2, 3], [4, 5, 6]) AS res, toTypeName(res);

32    UInt16

元组示例

SELECT dotProduct((1::UInt16, 2::UInt8, 3::Float32),(4::Int16, 5::Float32, 6::UInt8)) AS res, toTypeName(res);

32    Float64

arrayElement

引入于：v1.1

获取给定数组中索引为 n 的元素，其中 n 可以是任意整数类型。如果索引超出数组范围，则返回默认值（数字为 0，字符串为空字符串等），但对于“非常量数组 + 常量索引 0”的参数组合除外。在这种情况下会报错：Array indices are 1-based。

注意

ClickHouse 中的数组是从 1 开始计数的。

支持负索引。在这种情况下，将根据从数组末尾开始的编号选择对应的元素。例如，arr[-1] 表示数组中的最后一个元素。

运算符 [n] 提供相同的功能。

语法

arrayElement(arr, n)

参数

arr — 要查找的数组。Array(T). - n — 要获取的元素的位置。(U)Int*.

返回值

返回由提供的数组参数合并得到的单个数组 Array(T)

示例

使用示例

SELECT arrayElement(arr, 2) FROM (SELECT [1, 2, 3] AS arr)

负索引

SELECT arrayElement(arr, -1) FROM (SELECT [1, 2, 3] AS arr)

使用 [n] 记法

SELECT arr[2] FROM (SELECT [1, 2, 3] AS arr)

数组下标越界

SELECT arrayElement(arr, 4) FROM (SELECT [1, 2, 3] AS arr)

arrayElementOrNull

引入于：v1.1

获取给定数组中索引为 n 的元素，其中 n 可以是任意整数类型。如果索引超出了数组的范围，则返回 NULL，而不是默认值。

注意

ClickHouse 中的数组是从 1 开始索引的。

支持负索引。在这种情况下，将从数组末尾开始计数来选择对应元素。例如，arr[-1] 是数组中的最后一个元素。

语法

arrayElementOrNull(arrays)

参数

arrays — 任意数量的数组参数。Array

返回值

从给定的数组参数中返回一个合并后的数组。Array(T)

示例

用法示例

SELECT arrayElementOrNull(arr, 2) FROM (SELECT [1, 2, 3] AS arr)

负索引

SELECT arrayElementOrNull(arr, -1) FROM (SELECT [1, 2, 3] AS arr)

数组下标越界

SELECT arrayElementOrNull(arr, 4) FROM (SELECT [1, 2, 3] AS arr)

NULL

arrayEnumerate

引入自：v1.1

返回数组 [1, 2, 3, ..., length (arr)]

此函数通常与 ARRAY JOIN 子句一起使用。它允许在应用 ARRAY JOIN 之后，对每个数组只计数一次。该函数也可以用于高阶函数中。例如，你可以使用它来获取满足某个条件的元素的数组下标。

语法

arrayEnumerate(arr)

参数

arr — 要枚举的数组。Array

返回值

返回一个数组 [1, 2, 3, ..., length(arr)]。Array(UInt32)

示例

带 ARRAY JOIN 的基本示例

CREATE TABLE test
(
    `id` UInt8,
    `tag` Array(String),
    `version` Array(String)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test VALUES (1, ['release-stable', 'dev', 'security'], ['2.4.0', '2.6.0-alpha', '2.4.0-sec1']);

SELECT
    id,
    tag,
    version,
    seq
FROM test
ARRAY JOIN
    tag,
    version,
    arrayEnumerate(tag) AS seq

┌─id─┬─tag────────────┬─version─────┬─seq─┐
│  1 │ release-stable │ 2.4.0       │   1 │
│  1 │ dev            │ 2.6.0-alpha │   2 │
│  1 │ security       │ 2.4.0-sec1  │   3 │
└────┴────────────────┴─────────────┴─────┘

arrayEnumerateDense

引入版本：v18.12

返回一个与源数组大小相同的数组，表示每个元素在源数组中首次出现的位置。

语法

arrayEnumerateDense(arr)

参数

arr — 要枚举的数组。Array(T)

返回值

返回一个与 arr 长度相同的数组，用于指示每个元素在源数组 Array(T) 中第一次出现的位置。

示例

使用示例

SELECT arrayEnumerateDense([10, 20, 10, 30])

[1,2,1,3]

arrayEnumerateDenseRanked

引入版本：v20.1

返回一个与源数组大小相同的数组，用于标记每个元素在源数组中首次出现的位置。它支持对多维数组进行枚举，并且可以指定在数组中向内展开的层级深度。

语法

arrayEnumerateDenseRanked(clear_depth, arr, max_array_depth)

参数

clear_depth — 在指定层级对元素分别编号。必须小于或等于 max_arr_depth。UInt*
arr — 要进行编号的 N 维数组。Array(T)
max_array_depth — 最大有效深度。必须小于或等于 arr 的深度。UInt*

返回值

返回一个数组，表示每个元素在源数组中首次出现的位置。Array

示例

基本用法

-- With clear_depth=1 and max_array_depth=1, the result is identical to what arrayEnumerateDense would give.

SELECT arrayEnumerateDenseRanked(1,[10, 20, 10, 30],1);

[1,2,1,3]

多维数组的用法

-- In this example, arrayEnumerateDenseRanked is used to obtain an array indicating, for each element of the
-- multidimensional array, what its position is among elements of the same value.
-- For the first row of the passed array, [10, 10, 30, 20], the corresponding first row of the result is [1, 1, 2, 3],
-- indicating that 10 is the first number encountered in position 1 and 2, 30 the second number encountered in position 3
-- and 20 is the third number encountered in position 4.
-- For the second row, [40, 50, 10, 30], the corresponding second row of the result is [4,5,1,2], indicating that 40
-- and 50 are the fourth and fifth numbers encountered in position 1 and 2 of that row, that another 10
-- (the first encountered number) is in position 3 and 30 (the second number encountered) is in the last position.

SELECT arrayEnumerateDenseRanked(1,[[10,10,30,20],[40,50,10,30]],2);

[[1,1,2,3],[4,5,1,2]]

提高 clear_depth 的示例

-- Changing clear_depth=2 results in the enumeration occurring separately for each row anew.

SELECT arrayEnumerateDenseRanked(2,[[10,10,30,20],[40,50,10,30]],2);

[[1, 1, 2, 3], [1, 2, 3, 4]]

arrayEnumerateUniq

自 v1.1 引入

返回一个与源数组大小相同的数组，对每个元素给出其在所有具有相同值的元素中的位置。

在使用 ARRAY JOIN 并对数组元素进行聚合时，此函数非常有用。

该函数可以接受多个大小相同的数组作为参数。在这种情况下，会根据所有数组中相同位置元素组成的元组来确定唯一性。

语法

arrayEnumerateUniq(arr1[, arr2, ... , arrN])

参数

arr1 — 要处理的第一个数组。Array(T)
arr2, ... — 可选。用于确定元组唯一性的、长度相同的附加数组。Array(UInt32)

返回值

返回一个数组，其中每个元素表示其在具有相同值或相同元组的元素中的位置。Array(T)

示例

基本用法

SELECT arrayEnumerateUniq([10, 20, 10, 30]);

[1, 1, 2, 1]

多个数组

SELECT arrayEnumerateUniq([1, 1, 1, 2, 2, 2], [1, 1, 2, 1, 1, 2]);

[1,2,1,1,2,1]

ARRAY JOIN 聚合

-- Each goal ID has a calculation of the number of conversions (each element in the Goals nested data structure is a goal that was reached, which we refer to as a conversion)
-- and the number of sessions. Without ARRAY JOIN, we would have counted the number of sessions as sum(Sign). But in this particular case,
-- the rows were multiplied by the nested Goals structure, so in order to count each session one time after this, we apply a condition to the
-- value of the arrayEnumerateUniq(Goals.ID) function.

SELECT
    Goals.ID AS GoalID,
    sum(Sign) AS Reaches,
    sumIf(Sign, num = 1) AS Visits
FROM test.visits
ARRAY JOIN
    Goals,
    arrayEnumerateUniq(Goals.ID) AS num
WHERE CounterID = 160656
GROUP BY GoalID
ORDER BY Reaches DESC
LIMIT 10

┌──GoalID─┬─Reaches─┬─Visits─┐
│   53225 │    3214 │   1097 │
│ 2825062 │    3188 │   1097 │
│   56600 │    2803 │    488 │
│ 1989037 │    2401 │    365 │
│ 2830064 │    2396 │    910 │
│ 1113562 │    2372 │    373 │
│ 3270895 │    2262 │    812 │
│ 1084657 │    2262 │    345 │
│   56599 │    2260 │    799 │
│ 3271094 │    2256 │    812 │
└─────────┴─────────┴────────┘

arrayEnumerateUniqRanked

自 v20.1 版本引入

返回一个与源数组维度相同的一维或多维数组，对每个元素给出其在所有相同值元素中的序号。它支持对多维数组进行枚举，并允许指定在数组中向内展开的深度。

语法

arrayEnumerateUniqRanked(clear_depth, arr, max_array_depth)

参数

clear_depth — 在指定层级对元素分别进行枚举。正整数，且小于或等于 max_arr_depth。UInt*
arr — 要枚举的 N 维数组。Array(T)
max_array_depth — 最大有效深度。正整数，且小于或等于 arr 的深度。UInt*

返回值

返回一个与 arr 大小相同的 N 维数组，其中每个元素表示该元素在与其具有相同值的其他元素中的位置。Array(T)

示例

示例 1

-- With clear_depth=1 and max_array_depth=1, the result of arrayEnumerateUniqRanked
-- is identical to that which arrayEnumerateUniq would give for the same array.

SELECT arrayEnumerateUniqRanked(1, [1, 2, 1], 1);

[1, 1, 2]

示例 2

-- with clear_depth=1 and max_array_depth=1, the result of arrayEnumerateUniqRanked
-- is identical to that which arrayEnumerateUniqwould give for the same array.

SELECT arrayEnumerateUniqRanked(1, [[1, 2, 3], [2, 2, 1], [3]], 2);", "[[1, 1, 1], [2, 3, 2], [2]]

[1, 1, 2]

示例 3

-- In this example, arrayEnumerateUniqRanked is used to obtain an array indicating,
-- for each element of the multidimensional array, what its position is among elements
-- of the same value. For the first row of the passed array, [1, 2, 3], the corresponding
-- result is [1, 1, 1], indicating that this is the first time 1, 2 and 3 are encountered.
-- For the second row of the provided array, [2, 2, 1], the corresponding result is [2, 3, 3],
-- indicating that 2 is encountered for a second and third time, and 1 is encountered
-- for the second time. Likewise, for the third row of the provided array [3] the
-- corresponding result is [2] indicating that 3 is encountered for the second time.

SELECT arrayEnumerateUniqRanked(1, [[1, 2, 3], [2, 2, 1], [3]], 2);

[[1, 1, 1], [2, 3, 2], [2]]

示例 4

-- Changing clear_depth=2, results in elements being enumerated separately for each row.
SELECT arrayEnumerateUniqRanked(2,[[1, 2, 3],[2, 2, 1],[3]], 2);

[[1, 1, 1], [1, 2, 1], [1]]

arrayExcept

引入于：v25.9

返回一个数组，其中包含 source 中在 except 中不存在的元素，并保留原始顺序。

此函数对两个数组执行差集运算。对于 source 中的每个元素，它会检查该元素是否存在于 except 中（使用精确比较）。如果不存在，该元素会被包含在结果中。

该操作具有以下特性：

保留 source 中元素的顺序
如果 source 中的重复元素在 except 中不存在，则会被保留
将 NULL 作为单独的值进行处理

语法

arrayExcept(source, except)

参数

source — 包含要过滤元素的源数组。Array(T)
except — 包含需要从结果中排除元素的数组。Array(T)

返回值

返回一个与输入数组类型相同的数组，包含 source 中那些未出现在 except 中的元素。Array(T)

示例

基本示例

SELECT arrayExcept([1, 2, 3, 2, 4], [3, 5])

[1, 2, 2, 4]

with_nulls1

SELECT arrayExcept([1, NULL, 2, NULL], [2])

[1, NULL, NULL]

with_nulls2

SELECT arrayExcept([1, NULL, 2, NULL], [NULL, 2, NULL])

[1]

字符串

SELECT arrayExcept(['apple', 'banana', 'cherry'], ['banana', 'date'])

['apple', 'cherry']

arrayExists

自 v1.1 起引入

如果源数组中至少有一个元素使 func(x[, y1, y2, ... yN]) 返回 true，则返回 1，否则返回 0。

语法

arrayExists(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 在源数组 (x) 和条件数组 (y) 的元素上进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。提供给 lambda 函数的 N 个条件数组，作为附加参数。Array(T)

返回值

如果对至少一个元素应用 lambda 函数时返回 true，则返回 1，否则返回 0。UInt8

示例

用法示例

SELECT arrayExists(x, y -> x=y, [1, 2, 3], [0, 0, 0])

arrayFill

引入版本：v20.1

arrayFill 函数按顺序处理源数组，从第一个元素到最后一个元素，在每个位置使用源数组和条件数组中的元素对一个 lambda 条件进行求值。当 lambda 函数在位置 i 上的求值结果为 false 时，函数会将该元素替换为当前数组状态中位置 i-1 的元素。无论条件如何，第一个元素始终会被保留。

语法

arrayFill(func(x [, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x [, y1, ..., yN]) — 一个 lambda 函数 func(x [, y1, y2, ... yN]) → F(x [, y1, y2, ... yN])，作用于源数组（x）和条件数组（y）中的元素。Lambda function
source_arr — 要处理的源数组。Lambda function
[, cond1_arr, ... , condN_arr] — 可选。提供给 lambda 函数的 N 个条件数组，作为附加参数。Array(T)

返回值

返回一个数组 Array(T)

示例

单个数组示例

SELECT arrayFill(x -> not isNull(x), [1, null, 2, null]) AS res

[1, 1, 2, 2]

包含两个数组的示例

SELECT arrayFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res

[5, 5, 6, 6]

arrayFilter

引入自：v1.1

返回一个数组，其中只包含源数组中使 lambda 函数返回 true 的元素。

语法

arrayFilter(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])]

参数

func(x[, y1, ..., yN]) — 对源数组（x）和条件数组（y）的元素进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 lambda 函数提供附加参数。Array(T)

返回值

返回源数组的一个子集 Array(T)

示例

示例 1

SELECT arrayFilter(x -> x LIKE '%World%', ['Hello', 'abc World']) AS res

['abc World']

示例 2

SELECT
    arrayFilter(
        (i, x) -> x LIKE '%World%',
        arrayEnumerate(arr),
        ['Hello', 'abc World'] AS arr)
    AS res

[2]

arrayFirst

自 v1.1 引入

返回源数组中第一个使 func(x[, y1, y2, ... yN]) 返回 true 的元素，否则返回默认值。

语法

arrayFirst(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 一个对源数组 (x) 和条件数组 (y) 的元素进行操作的 Lambda 函数。Lambda function。- source_arr — 要处理的源数组。Array(T)。- [, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 Lambda 函数提供额外参数。Array(T)。

返回值

返回第一个使 λ 为真的源数组元素，否则返回 T 类型的默认值。

示例

用法示例

SELECT arrayFirst(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])

未找到匹配项

SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)

0 UInt8

arrayFirstIndex

引入于：v1.1

返回源数组中第一个使 func(x[, y1, y2, ... yN]) 返回 true 的元素的索引，否则返回 '0'。

语法

arrayFirstIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 一个对源数组（x）元素及条件数组（y）元素进行操作的 lambda 函数。Lambda function. - source_arr — 要处理的源数组。Array(T). - [, cond1_arr, ... , condN_arr] — 可选。提供给 lambda 函数的附加参数的 N 个条件数组。Array(T).

返回值

返回在源数组中使 func 为 true 的第一个元素的索引，否则返回 0，类型为 UInt32

示例

用法示例

SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])

无匹配结果

SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f'])

arrayFirstOrNull

自 v1.1 引入

返回源数组中第一个使得 func(x[, y1, y2, ... yN]) 返回 true 的元素，否则返回 NULL。

语法

arrayFirstOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 一个 lambda 函数，用于对源数组 (x) 和条件数组 (y) 的元素进行操作。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 lambda 函数提供额外的参数。Array(T)

返回值

返回 func 结果为 true 的源数组中的第一个元素，否则返回 NULL。

示例

用法示例

SELECT arrayFirstOrNull(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])

无匹配

SELECT arrayFirstOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)

NULL Nullable(UInt8)

arrayFlatten

引入版本：v20.1

将嵌套数组转换为扁平数组。

函数：

适用于任意深度的嵌套数组。
不会改变已经是扁平结构的数组。

扁平化后的数组包含所有源数组中的全部元素。

语法

arrayFlatten(arr)

别名: flatten

参数

arr — 多维数组。Array(Array(T))

返回值

返回由多维数组展平得到的数组 Array(T)

示例

用法示例

SELECT arrayFlatten([[[1]], [[2], [3]]]);

[1, 2, 3]

arrayFold

自 v23.10 版本引入

对一个或多个等长数组应用一个 lambda 函数，并将结果累积到累加器中。

语法

arrayFold(λ(acc, x1 [, x2, x3, ... xN]), arr1 [, arr2, arr3, ... arrN], acc)

参数

λ(x, x1 [, x2, x3, ... xN]) — 一个 Lambda 函数 λ(acc, x1 [, x2, x3, ... xN]) → F(acc, x1 [, x2, x3, ... xN])，其中 F 是应用于 acc 和来自 x 的数组值的操作，其结果会被作为新的 acc 继续使用。Lambda function
arr1 [, arr2, arr3, ... arrN] — 要进行操作的 N 个数组。Array(T)
acc — 累加器值，其类型与 Lambda 函数的返回类型相同。

返回值

返回最终的 acc 值。

示例

用法示例

SELECT arrayFold(acc,x -> acc + x*2, [1, 2, 3, 4], 3::Int64) AS res;

斐波那契数列

SELECT arrayFold(acc, x -> (acc.2, acc.2 + acc.1),range(number),(1::Int64, 0::Int64)).1 AS fibonacci FROM numbers(1,10);

┌─fibonacci─┐
│         0 │
│         1 │
│         1 │
│         2 │
│         3 │
│         5 │
│         8 │
│        13 │
│        21 │
│        34 │
└───────────┘

多个数组示例

SELECT arrayFold(
(acc, x, y) -> acc + (x * y),
[1, 2, 3, 4],
[10, 20, 30, 40],
0::Int64
) AS res;

arrayIntersect

自 v1.1 起引入

接受多个数组，并返回一个数组，其中只包含在所有源数组中都出现的元素。结果中仅包含唯一值。

语法

arrayIntersect(arr, arr1, ..., arrN)

参数

arrN — 用于构造新数组的 N 个数组。Array(T)。

返回值

返回一个数组，包含所有 N 个数组共有的、不重复的元素。Array(T)

示例

用法示例

SELECT
arrayIntersect([1, 2], [1, 3], [2, 3]) AS empty_intersection,
arrayIntersect([1, 2], [1, 3], [1, 4]) AS non_empty_intersection

┌─non_empty_intersection─┬─empty_intersection─┐
│ []                     │ [1]                │
└────────────────────────┴────────────────────┘

arrayJaccardIndex

自 v23.7 版本引入

返回两个数组的 Jaccard 指数。

语法

arrayJaccardIndex(arr_x, arr_y)

参数

arr_x — 第一个数组。Array(T)
arr_y — 第二个数组。Array(T)

返回值

返回 arr_x 和 arr_y 的 Jaccard 指数。Float64

示例

用法示例

SELECT arrayJaccardIndex([1, 2], [2, 3]) AS res

0.3333333333333333

arrayJoin

引入版本：v1.1

arrayJoin 函数接收一行包含数组的记录并将其展开，为数组中的每个元素生成一行。这与 ClickHouse 中的常规函数（Regular Functions）不同，后者是在同一行内将输入值映射为输出值，而聚合函数（Aggregate Functions）则接收一组行并将它们“压缩”或“归约”为单个汇总行（或者在与 GROUP BY 一起使用时，将其归约为汇总行中的单个值）。

除应用此函数的列中的值外，其他列中的所有值都会被直接复制；应用此函数的列中的值会被对应的数组元素所替代。

语法

arrayJoin(arr)

参数

arr — 要展开的数组。Array(T)

返回值

返回由 arr 展开得到的一组行。

示例

基本用法

SELECT arrayJoin([1, 2, 3] AS src) AS dst, 'Hello', src

┌─dst─┬─\'Hello\'─┬─src─────┐
│   1 │ Hello     │ [1,2,3] │
│   2 │ Hello     │ [1,2,3] │
│   3 │ Hello     │ [1,2,3] │
└─────┴───────────┴─────────┘

arrayJoin 会影响查询的所有部分

-- The arrayJoin function affects all sections of the query, including the WHERE section. Notice the result 2, even though the subquery returned 1 row.

SELECT sum(1) AS impressions
FROM
(
    SELECT ['Istanbul', 'Berlin', 'Bobruisk'] AS cities
)
WHERE arrayJoin(cities) IN ['Istanbul', 'Berlin'];

┌─impressions─┐
│           2 │
└─────────────┘

使用多个 arrayJoin 函数

- A query can use multiple arrayJoin functions. In this case, the transformation is performed multiple times and the rows are multiplied.

SELECT
    sum(1) AS impressions,
    arrayJoin(cities) AS city,
    arrayJoin(browsers) AS browser
FROM
(
    SELECT
        ['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
        ['Firefox', 'Chrome', 'Chrome'] AS browsers
)
GROUP BY
    2,
    3

┌─impressions─┬─city─────┬─browser─┐
│           2 │ Istanbul │ Chrome  │
│           1 │ Istanbul │ Firefox │
│           2 │ Berlin   │ Chrome  │
│           1 │ Berlin   │ Firefox │
│           2 │ Bobruisk │ Chrome  │
│           1 │ Bobruisk │ Firefox │
└─────────────┴──────────┴─────────┘

优化导致的非预期结果

-- Using multiple arrayJoin with the same expression may not produce the expected result due to optimizations.
-- For these cases, consider modifying the repeated array expression with extra operations that do not affect join result.
- e.g. arrayJoin(arraySort(arr)), arrayJoin(arrayConcat(arr, []))

SELECT
    arrayJoin(dice) as first_throw,
    /* arrayJoin(dice) as second_throw */ -- is technically correct, but will annihilate result set
    arrayJoin(arrayConcat(dice, [])) as second_throw -- intentionally changed expression to force re-evaluation
FROM (
    SELECT [1, 2, 3, 4, 5, 6] as dice
);

┌─first_throw─┬─second_throw─┐
│           1 │            1 │
│           1 │            2 │
│           1 │            3 │
│           1 │            4 │
│           1 │            5 │
│           1 │            6 │
│           2 │            1 │
│           2 │            2 │
│           2 │            3 │
│           2 │            4 │
│           2 │            5 │
│           2 │            6 │
│           3 │            1 │
│           3 │            2 │
│           3 │            3 │
│           3 │            4 │
│           3 │            5 │
│           3 │            6 │
│           4 │            1 │
│           4 │            2 │
│           4 │            3 │
│           4 │            4 │
│           4 │            5 │
│           4 │            6 │
│           5 │            1 │
│           5 │            2 │
│           5 │            3 │
│           5 │            4 │
│           5 │            5 │
│           5 │            6 │
│           6 │            1 │
│           6 │            2 │
│           6 │            3 │
│           6 │            4 │
│           6 │            5 │
│           6 │            6 │
└─────────────┴──────────────┘

使用 ARRAY JOIN 语法

-- Note the ARRAY JOIN syntax in the `SELECT` query below, which provides broader possibilities.
-- ARRAY JOIN allows you to convert multiple arrays with the same number of elements at a time.

SELECT
    sum(1) AS impressions,
    city,
    browser
FROM
(
    SELECT
        ['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
        ['Firefox', 'Chrome', 'Chrome'] AS browsers
)
ARRAY JOIN
    cities AS city,
    browsers AS browser
GROUP BY
    2,
    3

┌─impressions─┬─city─────┬─browser─┐
│           1 │ Istanbul │ Firefox │
│           1 │ Berlin   │ Chrome  │
│           1 │ Bobruisk │ Chrome  │
└─────────────┴──────────┴─────────┘

使用元组

-- You can also use Tuple

SELECT
    sum(1) AS impressions,
    (arrayJoin(arrayZip(cities, browsers)) AS t).1 AS city,
    t.2 AS browser
FROM
(
    SELECT
        ['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
        ['Firefox', 'Chrome', 'Chrome'] AS browsers
)
GROUP BY
    2,
    3

┌─impressions─┬─city─────┬─browser─┐
│           1 │ Istanbul │ Firefox │
│           1 │ Berlin   │ Chrome  │
│           1 │ Bobruisk │ Chrome  │
└─────────────┴──────────┴─────────┘

arrayLast

引入版本：v1.1

返回源数组中最后一个使 lambda func(x [, y1, y2, ... yN]) 返回 true 的元素；如果不存在这样的元素，则返回默认值。

语法

arrayLast(func(x[, y1, ..., yN]), source[, cond1, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 在源数组（x）和条件数组（y）的元素上进行操作的 lambda 函数。Lambda function。

source — 要处理的源数组。Array(T)。
[, cond1, ... , condN] — 可选。为 lambda 函数提供附加参数的 N 个条件数组。Array(T)。

返回值

返回使 func 为 true 的源数组中的最后一个元素，否则返回 T 类型的默认值。

示例

用法示例

SELECT arrayLast(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c'])

无匹配项

SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)

0 UInt8

arrayLastIndex

自 v1.1 起引入。

返回源数组中最后一个使 func(x[, y1, y2, ... yN]) 返回 true 的元素的索引；如果不存在这样的元素，则返回 0。

语法

arrayLastIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 一个对源数组 (x) 和条件数组 (y) 的元素进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 lambda 函数提供附加参数。Array(T)

返回值

返回源数组中使 func 为 true 的最后一个元素的索引；否则返回 0 UInt32

示例

用法示例

SELECT arrayLastIndex(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c']);

未找到匹配项

SELECT arrayLastIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f']);

arrayLastOrNull

自 v1.1 起引入

返回源数组中最后一个使得 lambda func(x [, y1, y2, ... yN]) 返回 true 的元素，否则返回 NULL。

语法

arrayLastOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x [, y1, ..., yN]) — 一个 lambda 函数，用于处理源数组 (x) 和条件数组 (y) 的元素。Lambda function。

source_arr — 要处理的源数组。Array(T)。
[, cond1_arr, ... , condN_arr] — 可选。提供给 lambda 函数的额外参数的 N 个条件数组。Array(T)。

返回值

返回源数组中最后一个使 λ 的返回值不为 true 的元素，否则返回 NULL。

示例

使用示例

SELECT arrayLastOrNull(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c'])

无匹配项

SELECT arrayLastOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)

NULL Nullable(UInt8)

arrayLevenshteinDistance

引入自：v25.4

计算两个数组之间的 Levenshtein 距离。

语法

arrayLevenshteinDistance(from, to)

参数

from — 第一个数组。Array(T)。- to — 第二个数组。Array(T)。

返回值

第一个数组与第二个数组之间的 Levenshtein 距离。Float64

示例

用法示例

SELECT arrayLevenshteinDistance([1, 2, 4], [1, 2, 3])

arrayLevenshteinDistanceWeighted

自 v25.4 版本引入

计算两个数组的 Levenshtein 距离，并为每个元素使用自定义权重。数组的元素数量应当与其对应的权重数量一致。

语法

arrayLevenshteinDistanceWeighted(from, to, from_weights, to_weights)

参数

from — 第一个数组。Array(T)。- to — 第二个数组。Array(T)。- from_weights — 第一个数组的权重。Array((U)Int*|Float*)
to_weights — 第二个数组的权重。Array((U)Int*|Float*)

返回值

第一个数组和第二个数组之间的 Levenshtein 距离，对每个元素使用自定义权重。Float64

示例

用法示例

SELECT arrayLevenshteinDistanceWeighted(['A', 'B', 'C'], ['A', 'K', 'L'], [1.0, 2, 3], [3.0, 4, 5])

arrayMap

引入版本：v1.1

返回通过对原始数组的每个元素应用 lambda 函数得到的数组。

语法

arrayMap(func, arr)

参数

func — 在源数组（x）和条件数组（y）的元素上进行操作的 lambda 函数。Lambda function
arr — 要处理的 N 个数组。Array(T)

返回值

返回一个由 lambda 函数结果组成的数组。Array(T)

示例

用法示例

SELECT arrayMap(x -> (x + 2), [1, 2, 3]) as res;

[3, 4, 5]

从不同数组中创建元素元组

SELECT arrayMap((x, y) -> (x, y), [1, 2, 3], [4, 5, 6]) AS res

[(1, 4),(2, 5),(3, 6)]

arrayMax

自 v21.1 版本引入

返回源数组中的最大元素。

如果指定了 lambda 函数 func，则返回该 lambda 函数结果中的最大元素。

语法

arrayMax([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 可选。对源数组 (x) 及条件数组 (y) 的元素进行操作的 Lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 Lambda 函数提供额外参数。Array(T)

返回值

返回源数组中的最大元素；如果提供了 Lambda 函数，则返回其结果中的最大元素。

示例

基础示例

SELECT arrayMax([5, 3, 2, 7]);

与 lambda 函数配合使用

SELECT arrayMax(x, y -> x/y, [4, 8, 12, 16], [1, 2, 1, 2]);

arrayMin

引入版本：v21.1

返回原始数组中的最小元素。

如果指定了 lambda 函数 func，则返回该 lambda 函数结果中的最小值。

语法

arrayMin([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 可选。一个对源数组 (x) 和条件数组 (y) 的元素进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
cond1_arr, ... — 可选。提供给 lambda 函数作为附加参数的 N 个条件数组。Array(T)

返回值

返回源数组中的最小元素；如果提供了 lambda 函数，则返回其结果中的最小元素。

示例

基本示例

SELECT arrayMin([5, 3, 2, 7]);

与 lambda 函数配合使用

SELECT arrayMin(x, y -> x/y, [4, 8, 12, 16], [1, 2, 1, 2]);

arrayNormalizedGini

在 v25.1 中引入

计算标准化的 Gini 系数。

语法

arrayNormalizedGini(predicted, label)

参数

predicted — 预测值。Array(T)
label — 实际值。Array(T)

返回值

一个元组，包含预测值的 Gini 系数、归一化后数值的 Gini 系数，以及归一化 Gini 系数（= 前两个 Gini 系数的比值）。Tuple(Float64, Float64, Float64)

示例

用法示例

SELECT arrayNormalizedGini([0.9, 0.3, 0.8, 0.7],[6, 1, 0, 2]);

(0.18055555555555558, 0.2638888888888889, 0.6842105263157896)

arrayPartialReverseSort

自 v23.2 版本引入

此函数与 arrayReverseSort 相同，但额外增加了一个 limit 参数，用于只对部分元素进行排序。

提示

若只保留已排序的元素，请使用 arrayResize。

语法

arrayPartialReverseSort([f,] arr [, arr1, ... ,arrN], limit)

参数

f(arr[, arr1, ... ,arrN]) — 应用于数组 x 元素的 lambda 函数。Lambda function
arr — 要排序的数组。Array(T)
arr1, ... ,arrN — 当 f 接受多个参数时使用的 N 个附加数组。Array(T)
limit — 排序执行到的索引值上限。(U)Int*

返回值

返回一个与原数组大小相同的数组，其中区间 [1..limit] 内的元素按降序排序。其余区间 (limit..N] 内元素的顺序未定义。

示例

simple_int

SELECT arrayPartialReverseSort(2, [5, 9, 1, 3])

[9, 5, 1, 3]

simple_string

SELECT arrayPartialReverseSort(2, ['expenses','lasso','embolism','gladly'])

['lasso','gladly','expenses','embolism']

retain_sorted

SELECT arrayResize(arrayPartialReverseSort(2, [5, 9, 1, 3]), 2)

[9, 5]

lambda_simple

SELECT arrayPartialReverseSort((x) -> -x, 2, [5, 9, 1, 3])

[1, 3, 5, 9]

lambda_complex

SELECT arrayPartialReverseSort((x, y) -> -y, 1, [0, 1, 2], [1, 2, 3]) as res

[0, 1, 2]

arrayPartialShuffle

引入于：v23.2

返回一个与原始数组大小相同的数组，其中区间 [1..limit] 内的元素是原始数组的一个随机子集。剩余区间 (limit..n] 包含不在 [1..limit] 区间内的元素，顺序未定义。 limit 的取值范围应为 [1..n]。超出该范围的取值等价于执行完整的 arrayShuffle：

注意

该函数不会物化常量。

limit 的值应在 [1..N] 范围内。超出该范围的取值等价于执行完整的 arrayShuffle。

语法

arrayPartialShuffle(arr [, limit[, seed]])

参数

arr — 要打乱顺序的数组。Array(T)
seed — 可选。用于随机数生成的种子。如果未提供，则使用随机种子。(U)Int*
limit — 可选。用于限制元素交换次数的数值，取值范围为 [1..N]。(U)Int*

返回值

元素顺序被部分打乱的数组。Array(T)

示例

no_limit1

SELECT arrayPartialShuffle([1, 2, 3, 4], 0)

[2, 4, 3, 1]

no_limit2

SELECT arrayPartialShuffle([1, 2, 3, 4])

[4, 1, 3, 2]

random_seed

SELECT arrayPartialShuffle([1, 2, 3, 4], 2)

[3, 4, 1, 2]

explicit_seed

SELECT arrayPartialShuffle([1, 2, 3, 4], 2, 41)

[3, 2, 1, 4]

materialize

SELECT arrayPartialShuffle(materialize([1, 2, 3, 4]), 2, 42), arrayPartialShuffle([1, 2, 3], 2, 42) FROM numbers(10)

┌─arrayPartial⋯4]), 2, 42)─┬─arrayPartial⋯ 3], 2, 42)─┐
│ [3,2,1,4]                │ [3,2,1]                  │
│ [3,2,1,4]                │ [3,2,1]                  │
│ [4,3,2,1]                │ [3,2,1]                  │
│ [1,4,3,2]                │ [3,2,1]                  │
│ [3,4,1,2]                │ [3,2,1]                  │
│ [1,2,3,4]                │ [3,2,1]                  │
│ [1,4,3,2]                │ [3,2,1]                  │
│ [1,4,3,2]                │ [3,2,1]                  │
│ [3,1,2,4]                │ [3,2,1]                  │
│ [1,3,2,4]                │ [3,2,1]                  │
└──────────────────────────┴──────────────────────────┘

arrayPartialSort

自 v23.2 版本引入

此函数与 arraySort 相同，但多了一个 limit 参数，用于实现部分排序。

提示

若只想保留排序后的元素，请使用 arrayResize。

语法

arrayPartialSort([f,] arr [, arr1, ... ,arrN], limit)

参数

f(arr[, arr1, ... ,arrN]) — 应用于数组 x 元素的 lambda 函数。Lambda function
arr — 要排序的数组。Array(T)
arr1, ... ,arrN — 当 f 接受多个参数时的 N 个额外数组。Array(T)
limit — 执行排序的索引上限值。(U)Int*

返回值

返回一个与原始数组大小相同的数组，其中区间 [1..limit] 内的元素按升序排序。其余元素 (limit..N] 的顺序未定义。

示例

simple_int

SELECT arrayPartialSort(2, [5, 9, 1, 3])

[1, 3, 5, 9]

simple_string

SELECT arrayPartialSort(2, ['expenses', 'lasso', 'embolism', 'gladly'])

['embolism', 'expenses', 'gladly', 'lasso']

retain_sorted

SELECT arrayResize(arrayPartialSort(2, [5, 9, 1, 3]), 2)

[1, 3]

lambda_simple

SELECT arrayPartialSort((x) -> -x, 2, [5, 9, 1, 3])

[9, 5, 1, 3]

lambda_complex

SELECT arrayPartialSort((x, y) -> -y, 1, [0, 1, 2], [1, 2, 3]) as res

[2, 1, 0]

arrayPopBack

自 v1.1 起引入。

从数组中移除最后一个元素。

语法

arrayPopBack(arr)

参数

arr — 要移除其最后一个元素的数组。Array(T)

返回值

返回一个与 arr 相同但去掉了最后一个元素的数组。Array(T)

示例

用法示例

SELECT arrayPopBack([1, 2, 3]) AS res;

[1, 2]

arrayPopFront

引入版本：v1.1

从数组中删除第一个元素。

语法

arrayPopFront(arr)

参数

arr — 要从中删除第一个元素的数组。Array(T)

返回值

返回一个与 arr 相同但不包含其第一个元素的数组。Array(T)

示例

使用示例

SELECT arrayPopFront([1, 2, 3]) AS res;

[2, 3]

arrayProduct

引入版本：v21.1

返回源数组中元素的乘积。

如果指定了 lambda 函数 func，则返回对数组元素应用该 lambda 后所得结果的乘积。

语法

arrayProduct([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 可选。一个对源数组 (x) 和条件数组 (y) 的元素进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。向 lambda 函数提供额外参数的 N 个条件数组。Array(T)

返回值

返回源数组中元素的乘积；如果提供了 lambda 函数，则返回其结果数组中元素的乘积。Float64

示例

基础示例

SELECT arrayProduct([1, 2, 3, 4]);

结合 lambda 函数使用

SELECT arrayProduct(x, y -> x+y, [2, 2], [2, 2]) AS res;

arrayPushBack

自 v1.1 起引入

在数组末尾添加一个元素。

语法

arrayPushBack(arr, x)

参数

arr — 要在其末尾添加值 x 的数组。Array(T)
x —
要添加到数组末尾的单个值。Array(T)。

注意

只有数字可以添加到数字数组中，只有字符串可以添加到字符串数组中。
添加数字时，ClickHouse 会自动将 x 的类型推断为数组元素的数据类型。
可以为 NULL。该函数会向数组添加一个 NULL 元素，并将数组元素的类型转换为 Nullable。

有关 ClickHouse 中数据类型的更多信息，请参阅数据类型。

返回值

返回一个与 arr 相同但在数组末尾多了一个值 x 的数组 Array(T)。

示例

用法示例

SELECT arrayPushBack(['a'], 'b') AS res;

['a','b']

arrayPushFront

自 v1.1 起引入。

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

语法

arrayPushFront(arr, x)

参数

arr — 要在其末尾添加值 x 的数组。Array(T)。- x —
要添加到数组开头的单个值。Array(T)。

注意

数组中包含数字时只能添加数字，数组中包含字符串时只能添加字符串。
添加数字时，ClickHouse 会自动将 x 的类型设置为与数组的数据类型一致。
可以为 NULL。该函数会向数组中添加一个 NULL 元素，并将数组元素的类型转换为 Nullable。

有关 ClickHouse 中数据类型的更多信息，请参阅数据类型。

返回值

返回一个与 arr 相同的数组，但在数组开头额外包含一个值 x Array(T)。

示例

用法示例

SELECT arrayPushFront(['b'], 'a') AS res;

['a','b']

arrayROCAUC

引入版本：v20.4

计算受试者工作特征（ROC）曲线下的面积。 ROC 曲线是通过在所有阈值上，以真正例率（TPR）为纵轴、假正例率（FPR）为横轴绘制得到的。结果值范围为 0 到 1，值越高表示模型性能越好。

ROC AUC（也常简称为 AUC）是机器学习中的一个概念。更多详情请参见这里、这里以及这里。

语法

arrayROCAUC(scores, labels[, scale[, partial_offsets]])

别名: arrayAUC

参数

scores — 预测模型给出的分数。Array((U)Int*) 或 Array(Float*)
labels — 样本标签，通常正样本为 1，负样本为 0。Array((U)Int*) 或 Enum
scale — 可选。决定是否返回归一化后的面积。如果为 false，则返回 TP（真阳性）与 FP（假阳性）曲线下的面积。默认值：true。Bool
partial_offsets —
一个由四个非负整数组成的数组，用于计算 ROC 曲线下的部分面积（相当于 ROC 空间中的一个垂直带），而不是整个 AUC。此选项对 ROC AUC 的分布式计算非常有用。数组必须包含以下元素 [higher_partitions_tp, higher_partitions_fp, total_positives, total_negatives]。Array 类型的非负 Integers。可选。
- higher_partitions_tp: 高得分分区中的正标签数量。
- higher_partitions_fp: 高得分分区中的负标签数量。
- total_positives: 整个数据集中正样本的总数。
- total_negatives: 整个数据集中负样本的总数。

注意

当使用 arr_partial_offsets 时，arr_scores 和 arr_labels 只应包含整个数据集中的一个分区，即某一分数区间内的样本。数据集应被划分为连续的分区，每个分区包含分数落在特定范围内的数据子集。例如：

一个分区可以包含范围为 [0, 0.5) 的所有分数。
另一个分区可以包含范围为 [0.5, 1.0] 的分数。

返回值

返回接收者操作特性（ROC）曲线下的面积。Float64

示例

用法示例

SELECT arrayROCAUC([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1]);

0.75

arrayRandomSample

引入版本：v23.10

返回由输入数组中 samples 个随机元素组成的子集。如果 samples 大于输入数组的大小，则样本数量会被限制为数组的大小，即返回数组中的所有元素，但不保证其顺序。该函数既能处理一维数组，也能处理嵌套数组。

语法

arrayRandomSample(arr, samples)

参数

arr — 要从中抽取元素的输入数组或多维数组。Array(T)
samples — 随机样本中包含的元素数量。(U)Int*

返回值

一个数组，包含从输入数组中随机抽取的元素的样本。Array(T)

示例

用法示例

SELECT arrayRandomSample(['apple', 'banana', 'cherry', 'date'], 2) as res;

['cherry','apple']

使用多维数组

SELECT arrayRandomSample([[1, 2], [3, 4], [5, 6]], 2) as res;

[[3,4],[5,6]]

arrayReduce

引入版本：v1.1

对数组元素应用聚合函数并返回其结果。聚合函数的名称以单引号括起的字符串形式传入，例如 'max'、'sum'。使用参数化聚合函数时，在函数名后用括号指定参数，例如 'uniqUpTo(6)'。

语法

arrayReduce(agg_f, arr1 [, arr2, ... , arrN)])

参数

agg_f — 聚合函数的名称，应为常量。String
arr1 [, arr2, ... , arrN)] — 与 agg_f 的参数相对应的 N 个数组。Array(T)

返回值

返回聚合函数的结果。

示例

使用示例

SELECT arrayReduce('max', [1, 2, 3]);

┌─arrayReduce('max', [1, 2, 3])─┐
│                             3 │
└───────────────────────────────┘

带多个参数的聚合函数示例

--If an aggregate function takes multiple arguments, then this function must be applied to multiple arrays of the same size.

SELECT arrayReduce('maxIf', [3, 5], [1, 0]);

┌─arrayReduce('maxIf', [3, 5], [1, 0])─┐
│                                    3 │
└──────────────────────────────────────┘

参数化聚合函数示例

SELECT arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

┌─arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])─┐
│                                                           4 │
└─────────────────────────────────────────────────────────────┘

arrayReduceInRanges

引入版本：v20.4

对给定区间内的数组元素应用聚合函数，并返回一个数组，其中包含每个区间对应的结果。该函数返回的结果与分别对每个区间多次调用 arrayReduce(agg_func, arraySlice(arr1, index, length), ...) 所得到的结果相同。

语法

arrayReduceInRanges(agg_f, ranges, arr1 [, arr2, ... ,arrN)])

参数

agg_f — 要使用的聚合函数名称。String
ranges — 要进行聚合的范围。是一个由元组 (i, r) 组成的数组，每个元组包含起始位置的索引 i，以及执行聚合的范围 r。Array(T) 或 Tuple(T)
arr1 [, arr2, ... ,arrN)] — 作为聚合函数参数的 N 个数组。Array(T)

返回值

返回一个数组，其中包含聚合函数在指定范围上的结果。Array(T)

示例

用法示例

SELECT arrayReduceInRanges(
    'sum',
    [(1, 5), (2, 3), (3, 4), (4, 4)],
    [1000000, 200000, 30000, 4000, 500, 60, 7]
) AS res

┌─res─────────────────────────┐
│ [1234500,234000,34560,4567] │
└─────────────────────────────┘

arrayRemove

自 v25.11 引入

从数组中移除所有等于给定值的元素。将 NULL 视为相等。

语法

arrayRemove(arr, elem)

别名: array_remove

参数

arr — Array(T) - elem — T

返回值

返回源数组 Array(T) 的子集。

示例

示例 1

SELECT arrayRemove([1, 2, 2, 3], 2)

[1, 3]

示例 2

SELECT arrayRemove(['a', NULL, 'b', NULL], NULL)

['a', 'b']

arrayResize

自 v1.1 版本引入

修改数组长度。

语法

arrayResize(arr, size[, extender])

参数

arr — 要调整大小的数组。Array(T)
size —
- 数组的新长度。如果 size 小于数组的原始大小，则从右侧截断数组。如果 size 大于数组的初始大小，则从右侧使用 extender 值或数组元素类型的默认值扩展数组。
extender — 用于扩展数组的值。可以为 NULL。

返回值

一个长度为 size 的数组。Array(T)

示例

示例 1

SELECT arrayResize([1], 3);

[1,0,0]

示例 2

SELECT arrayResize([1], 3, NULL);

[1,NULL,NULL]

arrayReverse

自 v1.1 版本引入

将给定数组中的元素顺序反转。

注意

函数 reverse(arr) 实现相同的功能，但除了数组（Array）类型外，还适用于其他数据类型。

语法

arrayReverse(arr)

参数

arr — 要反转的数组。Array(T)

返回值

返回一个与原数组大小相同的数组，其中的元素顺序被反转。Array(T)

示例

用法示例

SELECT arrayReverse([1, 2, 3])

[3,2,1]

arrayReverseFill

引入于：v20.1

arrayReverseFill 函数按顺序处理源数组，从最后一个元素到第一个元素，在每个位置使用源数组和条件数组中的元素计算一个 lambda 条件。当条件在位置 i 的求值结果为 false 时，函数会将该元素替换为当前数组状态中位置 i+1 的元素。无论条件为何，最后一个元素始终会被保留。

语法

arrayReverseFill(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 作用于源数组 (x) 和条件数组 (y) 元素的 Lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 Lambda 函数提供额外参数。Array(T)

返回值

返回一个数组，其中源数组的元素被 Lambda 函数的结果替换。Array(T)

示例

单个数组示例

SELECT arrayReverseFill(x -> not isNull(x), [1, null, 2, null]) AS res

[1, 2, 2, NULL]

两个数组的示例

SELECT arrayReverseFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res;

[5, 6, 6, 2]

arrayReverseSort

引入于：v1.1

对数组元素进行降序排序。如果指定了函数 f，则根据该函数应用于数组元素后的结果对给定数组进行排序，然后再反转排序后的数组。如果 f 接受多个参数，则 arrayReverseSort 函数会接收多个数组，这些数组分别对应于 func 的各个参数。

如果待排序数组包含 -Inf、NULL、NaN 或 Inf，它们在排序时的顺序如下：

-Inf
Inf
NaN
NULL

arrayReverseSort 是一个高阶函数。

语法

arrayReverseSort([f,] arr [, arr1, ... ,arrN)

参数

f(y1[, y2 ... yN]) — 要应用到数组 x 元素上的 lambda 函数。
arr — 要排序的数组。Array(T)
arr1, ..., yN — 可选。当 f 接受多个参数时，额外提供的 N 个数组。

返回值

如果未提供 lambda 函数，则返回按降序排序的数组 x；否则，返回一个先根据所提供 lambda 函数逻辑排序，然后再反转后的数组。Array(T)。

示例

示例 1

SELECT arrayReverseSort((x, y) -> y, [4, 3, 5], ['a', 'b', 'c']) AS res;

[5,3,4]

示例 2

SELECT arrayReverseSort((x, y) -> -y, [4, 3, 5], [1, 2, 3]) AS res;

[4,3,5]

arrayReverseSplit

引入版本：v20.1

将源数组拆分为多个数组。当 func(x[, y1, ..., yN]) 返回非零值时，数组会在该元素右侧进行拆分。数组不会在最后一个元素之后被拆分。

语法

arrayReverseSplit(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 一个在源数组 (x) 和条件数组 (y) 的元素上执行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Lambda function
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 lambda 函数提供额外参数。Array(T)

返回值

返回一个数组的数组。Array(Array(T))

示例

用法示例

SELECT arrayReverseSplit((x, y) -> y, [1, 2, 3, 4, 5], [1, 0, 0, 1, 0]) AS res

[[1], [2, 3, 4], [5]]

arrayRotateLeft

自 v23.8 起引入

将数组循环左移指定的元素个数。n 为负值时，等价于按其绝对值将数组向右旋转。

语法

arrayRotateLeft(arr, n)

参数

arr — 要进行元素旋转的数组。Array(T)。 - n — 要旋转的元素个数。(U)Int8/16/32/64。

返回值

根据指定元素个数向左旋转后的数组 Array(T)。

示例

用法示例

SELECT arrayRotateLeft([1,2,3,4,5,6], 2) as res;

[3,4,5,6,1,2]

n 为负值时

SELECT arrayRotateLeft([1,2,3,4,5,6], -2) as res;

[5,6,1,2,3,4]

arrayRotateRight

引入于：v23.8

按指定的元素个数将数组向右旋转。n 为负数时，视为按该负数的绝对值向左旋转。

语法

arrayRotateRight(arr, n)

参数

arr — 要进行元素旋转的数组。Array(T). - n — 要旋转的元素个数。(U)Int8/16/32/64.

返回值

按指定元素个数向右旋转后的数组 Array(T)

示例

用法示例

SELECT arrayRotateRight([1,2,3,4,5,6], 2) as res;

[5,6,1,2,3,4]

n 为负数

SELECT arrayRotateRight([1,2,3,4,5,6], -2) as res;

[3,4,5,6,1,2]

arrayShiftLeft

引入自：v23.8

将数组向左移位指定数量的元素。新元素将使用提供的参数，或数组元素类型的默认值进行填充。如果该数量为负数，则将数组向右移位。

语法

arrayShiftLeft(arr, n[, default])

参数

arr — 要进行元素移位操作的数组。Array(T). - n — 要移位的元素个数。(U)Int8/16/32/64. - default — 可选。新元素的默认值。

返回值

按指定元素个数向左移位后的数组 Array(T)

示例

用法示例

SELECT arrayShiftLeft([1,2,3,4,5,6], 2) as res;

[3,4,5,6,0,0]

n 为负值时

SELECT arrayShiftLeft([1,2,3,4,5,6], -2) as res;

[0,0,1,2,3,4]

使用默认值

SELECT arrayShiftLeft([1,2,3,4,5,6], 2, 42) as res;

[3,4,5,6,42,42]

arrayShiftRight

引入于：v23.8

将数组按指定的元素个数向右移动。新位置上的元素使用提供的参数或数组元素类型的默认值填充。如果元素个数为负值，则数组向左移动。

语法

arrayShiftRight(arr, n[, default])

参数

arr — 要进行元素移位的数组。Array(T)
n — 要移位的元素个数。(U)Int8/16/32/64
default — 可选。新元素的默认值。

返回值

元素向右移位指定个数后得到的数组。Array(T)

示例

用法示例

SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], 2) as res;

[0, 0, 1, 2, 3, 4]

n 为负值

SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], -2) as res;

[3, 4, 5, 6, 0, 0]

使用默认值

SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], 2, 42) as res;

[42, 42, 1, 2, 3, 4]

arrayShingles

引入于：v24.1

生成一个由 shingles 组成的数组（类似于字符串的 ngrams），即由输入数组中具有指定长度的连续子数组构成的数组。

语法

arrayShingles(arr, l)

参数

arr — 要从中生成 shingle 数组的数组。Array(T)
l — 每个 shingle 的长度。(U)Int*

返回值

生成的 shingle 组成的数组。Array(T)

示例

用法示例

SELECT arrayShingles([1, 2, 3, 4], 3) as res;

[[1, 2, 3], [2, 3, 4]]

arrayShuffle

自 v23.2 版本引入

返回一个与原始数组大小相同的数组，数组中的元素以随机顺序排列。元素会被重新排序，使得这些元素的每一种排列出现的概率都相同。

注意

此函数不会对常量进行物化。

语法

arrayShuffle(arr [, seed])

参数

arr — 要打乱顺序的数组。Array(T)
seed (optional) — 可选。用于随机数生成的种子值。如果未提供，则会使用一个随机种子。(U)Int*

返回值

元素顺序被打乱的数组 Array(T)

示例

未指定种子的示例（结果不稳定）

SELECT arrayShuffle([1, 2, 3, 4]);

[1,4,2,3]

未指定种子的示例（结果稳定）

SELECT arrayShuffle([1, 2, 3, 4], 41);

[3,2,1,4]

arraySimilarity

自 v25.4 引入

基于加权 Levenshtein 距离计算两个数组的相似度，取值范围为 0 到 1。

语法

arraySimilarity(from, to, from_weights, to_weights)

参数

from — 第一个数组 Array(T)
to — 第二个数组 Array(T)
from_weights — 第一个数组对应的权重 Array((U)Int*|Float*)
to_weights — 第二个数组对应的权重 Array((U)Int*|Float*)

返回值

返回一个 Float64 值，表示基于加权 Levenshtein 距离计算得到的两个数组之间的相似度，取值范围在 0 到 1 之间。

示例

使用示例

SELECT arraySimilarity(['A', 'B', 'C'], ['A', 'K', 'L'], [1.0, 2, 3], [3.0, 4, 5]);

0.2222222222222222

arraySlice

自 v1.1 引入

返回数组的一个切片，并保留其中的 NULL 元素。

语法

arraySlice(arr, offset [, length])

参数

arr — 要切片的数组。Array(T)
offset — 相对于数组边缘的偏移量。正值表示从左侧偏移，负值表示从右侧偏移。数组元素的编号从 1 开始。(U)Int*
length — 所需切片的长度。如果指定负值，则函数返回开区间切片 [offset, array_length - length]。如果省略该值，则函数返回切片 [offset, the_end_of_array]。(U)Int*

返回值

从指定的 offset 位置开始，返回包含 length 个元素的数组切片 Array(T)

示例

用法示例

SELECT arraySlice([1, 2, NULL, 4, 5], 2, 3) AS res;

[2, NULL, 4]

arraySort

引入版本：v1.1

对给定数组中的元素进行升序排序。如果指定了 lambda 函数 f，则排序顺序由将该 lambda 应用于数组中每个元素所得到的结果决定。如果 lambda 接受多个参数，arraySort 函数会被传入多个数组，f 的各个参数将与这些数组一一对应。

如果要排序的数组包含 -Inf、NULL、NaN 或 Inf，它们将按以下顺序进行排序：

-Inf
Inf
NaN
NULL

arraySort 是一个高阶函数。

语法

arraySort([f,] arr [, arr1, ... ,arrN])

参数

f(y1[, y2 ... yN]) — 应用于数组 x 元素的 lambda 函数。
arr — 要排序的数组。Array(T)
arr1, ..., yN — 可选。当 f 接受多个参数时，额外提供的 N 个数组。

返回值

如果未提供 lambda 函数，则返回按升序排序的数组 arr；否则，返回根据所提供 lambda 函数逻辑排序后的数组。Array(T)。

示例

示例 1

SELECT arraySort([1, 3, 3, 0]);

[0,1,3,3]

示例 2

SELECT arraySort(['hello', 'world', '!']);

['!','hello','world']

示例 3

SELECT arraySort([1, nan, 2, NULL, 3, nan, -4, NULL, inf, -inf]);

[-inf,-4,1,2,3,inf,nan,nan,NULL,NULL]

arraySplit

引入于：v20.1

将源数组拆分为多个子数组。当 func(x [, y1, ..., yN]) 返回非零值时，数组会在该元素的左侧进行拆分。数组不会在第一个元素之前进行拆分。

语法

arraySplit(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 一个对源数组（x）和条件数组（y）的元素执行操作的 lambda 函数。Lambda 函数。- source_arr — 要拆分的源数组 Array(T)。- [, cond1_arr, ... , condN_arr] — 可选。为 lambda 函数提供附加参数的 N 个条件数组。Array(T)。

返回值

返回一个由数组组成的数组 Array(Array(T))。

示例

用法示例

SELECT arraySplit((x, y) -> y, [1, 2, 3, 4, 5], [1, 0, 0, 1, 0]) AS res

[[1, 2, 3], [4, 5]]

arraySum

在 v21.1 中引入。

返回源数组中元素的总和。

如果指定了 lambda 函数 func，则返回该 lambda 计算结果中元素的总和。

语法

arrayMax([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])

参数

func(x[, y1, ..., yN]) — 可选。作用于源数组（x）元素和条件数组（y）元素的 Lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
, cond1_arr, ... , condN_arr] — 可选。作为附加参数传递给 Lambda 函数的 N 个条件数组。Array(T)

返回值

返回源数组中元素的和；如果提供了 Lambda 函数，则返回其结果数组中元素的和。

示例

基本示例

SELECT arraySum([1, 2, 3, 4]);

与 lambda 函数配合使用

SELECT arraySum(x, y -> x+y, [1, 1, 1, 1], [1, 1, 1, 1]);

arraySymmetricDifference

引入于：v25.4

接受多个数组并返回一个数组，其中包含未在所有源数组中同时出现的元素。结果仅包含唯一值。

注意

多于两个集合的对称差在数学上被定义为在奇数个输入集合中出现的所有输入元素构成的集合。相比之下，函数 arraySymmetricDifference 仅返回那些未在所有输入集合中都出现的输入元素构成的集合。

语法

arraySymmetricDifference(arr1, arr2, ... , arrN)

参数

arrN — 用于构造新数组的 N 个数组。Array(T)。

返回值

返回一个由所有源数组中未在全部数组中同时出现的去重元素组成的数组 Array(T)。

示例

用法示例

SELECT
arraySymmetricDifference([1, 2], [1, 2], [1, 2]) AS empty_symmetric_difference,
arraySymmetricDifference([1, 2], [1, 2], [1, 3]) AS non_empty_symmetric_difference;

┌─empty_symmetric_difference─┬─non_empty_symmetric_difference─┐
│ []                         │ [3]                            │
└────────────────────────────┴────────────────────────────────┘

arrayUnion

引入版本：v24.10

接受多个数组并返回一个数组，该数组包含任一源数组中出现的所有元素。结果只包含不重复的值。

语法

arrayUnion(arr1, arr2, ..., arrN)

参数

arrN — 用于构建新数组的 N 个数组。Array(T)

返回值

返回一个包含源数组中所有不同元素的数组 Array(T)

示例

用法示例

SELECT
arrayUnion([-2, 1], [10, 1], [-2], []) as num_example,
arrayUnion(['hi'], [], ['hello', 'hi']) as str_example,
arrayUnion([1, 3, NULL], [2, 3, NULL]) as null_example

┌─num_example─┬─str_example────┬─null_example─┐
│ [10,-2,1]   │ ['hello','hi'] │ [3,2,1,NULL] │
└─────────────┴────────────────┴──────────────┘

arrayUniq

自 v1.1 起提供

对于传入的单个参数，计算数组中不同元素的数量。对于传入的多个参数，计算由多个数组中相同位置的元素组成的不同元组的数量。

例如 SELECT arrayUniq([1,2], [3,4], [5,6]) 将形成如下元组：

位置 1: (1,3,5)
位置 2: (2,4,6)

然后会统计唯一元组的数量。在本例中为 2。

所有传入的数组必须具有相同的长度。

提示

如果要获取数组中唯一元素的列表，可以使用 arrayReduce('groupUniqArray', arr)。

语法

arrayUniq(arr1[, arr2, ..., arrN])

参数

arr1 — 要统计其唯一元素数量的数组。Array(T)
[, arr2, ..., arrN] — 可选。其他数组，用于基于多个数组中相同位置元素组成的元组来统计唯一元组的数量。Array(T)

返回值

对于单个参数，返回唯一元素的数量。对于多个参数，返回由各数组中相同位置的元素组成的唯一元组的数量。 UInt32

示例

单个参数

SELECT arrayUniq([1, 1, 2, 2])

多个参数

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

arrayWithConstant

自 v20.1 版本引入

创建一个长度为 length、由常量 x 填充的数组。

语法

arrayWithConstant(N, x)

参数

length — 数组的元素数量。(U)Int*
x — 数组中 N 个元素的取值，可以是任意类型。

返回值

返回一个包含 N 个元素且每个元素值都为 x 的数组。Array(T)

示例

用法示例

SELECT arrayWithConstant(3, 1)

[1, 1, 1]

arrayZip

自 v20.1 起引入

将多个数组组合为一个数组。生成的数组按照参数的先后顺序，将源数组中对应位置的元素分组为元组。

语法

arrayZip(arr1, arr2, ... , arrN)

参数

arr1, arr2, ... , arrN — 要合并成一个数组的 N 个数组。Array(T)

返回值

返回一个数组，其元素是由源数组的元素分组形成的元组。元组中的数据类型与各输入数组的类型相同，且顺序与数组传入的顺序一致。Array(T)

示例

使用示例

SELECT arrayZip(['a', 'b', 'c'], [5, 2, 1]);

[('a', 5), ('b', 2), ('c', 1)]

arrayZipUnaligned

引入版本：v20.1

将多个数组合并为单个数组，允许数组之间长度不一致（不同长度的数组）。结果数组按参数列出的顺序，将源数组中对应位置的元素分组为元组。

语法

arrayZipUnaligned(arr1, arr2, ..., arrN)

参数

arr1, arr2, ..., arrN — 要合并成一个数组的 N 个数组。Array(T)

返回值

返回一个数组，其中的元素是从源数组按元组分组得到的。元组中的数据类型与对应输入数组的类型相同，且顺序与数组传入的顺序一致。Array(T) 或 Tuple(T1, T2, ...)

示例

用法示例

SELECT arrayZipUnaligned(['a'], [1, 2, 3]);

[('a', 1),(NULL, 2),(NULL, 3)]

countEqual

自 v1.1 引入

返回数组中等于 x 的元素个数。等价于 arrayCount(elem -> elem = x, arr)。

NULL 元素会被作为独立的取值处理。

语法

countEqual(arr, x)

参数

arr — 待搜索的数组。Array(T)
x — 在数组中要统计的值。任意类型。

返回值

返回数组中等于 x 的元素个数。UInt64

示例

用法示例

SELECT countEqual([1, 2, NULL, NULL], NULL)

empty

引入于：v1.1

检查输入数组是否为空。

如果数组不包含任何元素，则认为是空数组。

注意

可以通过启用 optimize_functions_to_subcolumns 设置项进行优化。当 optimize_functions_to_subcolumns = 1 时，该函数只读取 size0 子列，而不是读取并处理整个数组列。查询 SELECT empty(arr) FROM TABLE; 会被转换为 SELECT arr.size0 = 0 FROM TABLE;。

该函数同样适用于 String 或 UUID 类型。

语法

empty(arr)

参数

arr — 输入数组。Array(T)

返回值

如果数组为空，则返回 1；如果数组非空，则返回 0，类型为 UInt8

示例

使用示例

SELECT empty([]);

emptyArrayDate

自 v1.1 起引入

返回一个空的 Date 类型数组

语法

emptyArrayDate()

参数

无。

返回值

一个空的 Date 数组。Array(T)

示例

用法示例

SELECT emptyArrayDate

[]

emptyArrayDateTime

自 v1.1 引入

返回一个空的 DateTime 类型数组

语法

emptyArrayDateTime()

参数

无。

返回值

空的 DateTime 数组。Array(T)

示例

使用示例

SELECT emptyArrayDateTime

[]

emptyArrayFloat32

自 v1.1 起引入

返回一个空的 Float32 数组

语法

emptyArrayFloat32()

参数

无。

返回值

一个空的 Float32 类型数组。Array(T)

示例

用法示例

SELECT emptyArrayFloat32

[]

emptyArrayFloat64

自 v1.1 起引入

返回一个空的 Float64 数组

语法

emptyArrayFloat64()

参数

无。

返回值

一个空的 Float64 数组。Array(T)

示例

使用示例

SELECT emptyArrayFloat64

[]

emptyArrayInt16

自 v1.1 版本引入

返回一个空的 Int16 类型数组

语法

emptyArrayInt16()

参数

无。

返回值

空的 Int16 数组。Array(T)

示例

用法示例

SELECT emptyArrayInt16

[]

emptyArrayInt32

自 v1.1 引入

返回一个空的 Int32 类型数组

语法

emptyArrayInt32()

参数

无。

返回值

一个空的 Int32 数组。Array(T)

示例

用法示例

SELECT emptyArrayInt32

[]

emptyArrayInt64

自 v1.1 起引入

返回一个空的 Int64 数组

语法

emptyArrayInt64()

参数

无。

返回值

一个空的 Int64 数组。Array(T)

示例

用法示例

SELECT emptyArrayInt64

[]

emptyArrayInt8

自 v1.1 起引入

返回一个空的 Int8 数组

语法

emptyArrayInt8()

参数

无。

返回值

空 Int8 数组。Array(T)

示例

用法示例

SELECT emptyArrayInt8

[]

emptyArrayString

引入版本：v1.1

返回一个空的 String 类型数组

语法

emptyArrayString()

参数

无。

返回值

一个空的 String 类型数组。Array(T)

示例

使用示例

SELECT emptyArrayString

[]

emptyArrayToSingle

自 v1.1 版本引入

接受一个空数组，并返回一个仅包含单个元素的数组，该元素为默认值。

语法

emptyArrayToSingle(arr)

参数

arr — 一个空数组。Array(T)

返回值

一个仅包含单个元素的数组，该元素的数据类型为该 Array 的默认类型。Array(T)

示例

基础示例

CREATE TABLE test (
  a Array(Int32),
  b Array(String),
  c Array(DateTime)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO test VALUES ([], [], []);

SELECT emptyArrayToSingle(a), emptyArrayToSingle(b), emptyArrayToSingle(c) FROM test;

┌─emptyArrayToSingle(a)─┬─emptyArrayToSingle(b)─┬─emptyArrayToSingle(c)───┐
│ [0]                   │ ['']                  │ ['1970-01-01 01:00:00'] │
└───────────────────────┴───────────────────────┴─────────────────────────┘

emptyArrayUInt16

自 v1.1 引入

返回一个空的 UInt16 数组

语法

emptyArrayUInt16()

参数

无。

返回值

一个空的 UInt16 数组。Array(T)

示例

用法示例

SELECT emptyArrayUInt16

[]

emptyArrayUInt32

自 v1.1 引入

返回一个空的 UInt32 数组

语法

emptyArrayUInt32()

参数

无。

返回值

返回一个空的 UInt32 数组。Array(T)

示例

使用示例

SELECT emptyArrayUInt32

[]

emptyArrayUInt64

自 v1.1 起引入

返回一个空的 UInt64 数组

语法

emptyArrayUInt64()

参数

无。

返回值

空的 UInt64 数组。Array(T)

示例

使用示例

SELECT emptyArrayUInt64

[]

emptyArrayUInt8

引入版本：v1.1

返回一个空的 UInt8 数组

语法

emptyArrayUInt8()

参数

无。

返回值

返回一个空的 UInt8 数组。Array(T)

示例

使用示例

SELECT emptyArrayUInt8

[]

has

引入版本：v1.1

返回数组是否包含指定的元素。

当第一个参数是常量数组，第二个参数是列或表达式时，has(constant_array, column) 的行为类似于 column IN (constant_array)，并且可以使用主键和数据跳过索引进行优化。例如，如果 id 是 PRIMARY KEY 的一部分，则 has([1, 10, 100], id) 可以利用主键索引。

当对该列应用单调函数时（例如 has([...], toDate(ts))），同样适用此优化。

语法

has(arr, x)

参数

arr — 源数组。Array(T)
x — 要在数组中查找的值。

返回值

如果数组包含指定元素则返回 1，否则返回 0。UInt8

示例

基本用法

SELECT has([1, 2, 3], 2)

未找到

SELECT has([1, 2, 3], 4)

hasAll

引入于：v1.1

检查一个数组是否为另一个数组的子集。

空数组是任意数组的子集。
Null 会被当作一个普通值处理。
两个数组中值的顺序不会影响结果。

语法

hasAll(set, subset)

参数

set — 任意类型元素组成的数组。Array(T)
subset — 与 set 具有共同超类型的任意类型数组，包含要检测是否为 set 子集的元素。Array(T)

返回值

若 set 包含 subset 中的所有元素，则为 1。
否则为 0。

如果 set 和 subset 中的元素不具有共同的超类型，则抛出 NO_COMMON_TYPE 异常。

示例

空数组

SELECT hasAll([], [])

含有 NULL 值的数组

SELECT hasAll([1, Null], [Null])

包含不同类型元素的数组

SELECT hasAll([1.0, 2, 3, 4], [1, 3])

包含 String 类型值的数组

SELECT hasAll(['a', 'b'], ['a'])

没有公共元素类型的数组

SELECT hasAll([1], ['a'])

Raises a NO_COMMON_TYPE exception

嵌套数组

SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [3, 5]])

hasAny

自 v1.1 起引入

检查两个数组是否存在公共元素。

将 Null 作为普通值进行处理。
两个数组中元素的顺序无关紧要。

语法

hasAny(arr_x, arr_y)

参数

arr_x — 包含一组元素的任意类型数组。Array(T)
arr_y — 与数组 arr_x 具有公共超类型的任意类型数组。Array(T)

返回值

如果 arr_x 和 arr_y 至少有一个相同元素，则返回 1。
否则返回 0。

如果两个数组中的任意元素不具有公共超类型，则会抛出 NO_COMMON_TYPE 异常。

示例

一个数组为空

SELECT hasAny([1], [])

包含 NULL 值的数组

SELECT hasAny([Null], [Null, 1])

包含不同数据类型值的数组

SELECT hasAny([-128, 1., 512], [1])

不具有公共类型的数组

SELECT hasAny([[1, 2], [3, 4]], ['a', 'c'])

Raises a `NO_COMMON_TYPE` exception

数组的数组

SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [1, 2]])

hasSubstr

引入于：v20.6

检查 array2 的所有元素是否以完全相同的顺序出现在 array1 中。因此，当且仅当 array1 = prefix + array2 + suffix 时，该函数返回 1。

换句话说，该函数会像 hasAll 函数那样检查 array2 的所有元素是否都包含在 array1 中。此外，它还会检查在 array1 和 array2 中，这些元素是否以相同的顺序出现。

如果 array2 为空，函数将返回 1。
NULL 会作为一个值进行处理。换句话说，hasSubstr([1, 2, NULL, 3, 4], [2,3]) 将返回 0。然而，hasSubstr([1, 2, NULL, 3, 4], [2,NULL,3]) 将返回 1。
两个数组中值的顺序会影响结果。

如果两个数组中的任一元素不存在共同的超类型，则会抛出 NO_COMMON_TYPE 异常。

语法

hasSubstr(arr1, arr2)

参数

arr1 — 任意类型的数组，包含一组元素。Array(T)
arr2 — 任意类型的数组，包含一组元素。Array(T)

返回值

如果数组 arr1 包含数组 arr2，则返回 1，否则返回 0。返回类型：UInt8

示例

两个数组都为空

SELECT hasSubstr([], [])

含有 NULL 值的数组

SELECT hasSubstr([1, Null], [Null])

包含不同类型元素的数组

SELECT hasSubstr([1.0, 2, 3, 4], [1, 3])

字符串数组

SELECT hasSubstr(['a', 'b'], ['a'])

顺序有意义的数组

SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'b'])

顺序不合法的数组

SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'c'])

数组嵌套数组

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

元素不具有共同类型的数组

SELECT hasSubstr([1, 2, NULL, 3, 4], ['a'])

Raises a `NO_COMMON_TYPE` exception

indexOf

自 v1.1 引入

如果数组中存在值为 'x' 的元素，则返回第一个值为 'x' 的元素的索引（从 1 开始）。如果数组不包含要查找的值，则函数返回 0。

被设置为 NULL 的元素会按普通值处理。

语法

indexOf(arr, x)

参数

arr — 要在其中搜索 x 的数组。Array(T)
x — 要返回其索引的、在 arr 中首次匹配的元素的值。UInt64

返回值

如果存在，返回 arr 中第一个 x 的索引（从 1 开始编号）。否则返回 0。UInt64

示例

基本示例

SELECT indexOf([5, 4, 1, 3], 3)

包含 NULL 值的数组

SELECT indexOf([1, 3, NULL, NULL], NULL)

indexOfAssumeSorted

引入于：v24.12

如果数组中包含值为 'x' 的元素，则返回第一个此类元素的索引（从 1 开始计数）。如果数组不包含要查找的值，则函数返回 0。

注意

与 indexOf 函数不同，此函数假定数组按升序排序。如果数组未排序，则结果未定义。

语法

indexOfAssumeSorted(arr, x)

参数

arr — 要搜索的已排序数组。Array(T)
x — 在已排序的 arr 中，用于查找并返回其第一个匹配元素索引的值。UInt64

返回值

如果存在，则返回 arr 中第一个 x 的索引（从 1 开始编号）。否则返回 0。UInt64

示例

基本示例

SELECT indexOfAssumeSorted([1, 3, 3, 3, 4, 4, 5], 4)

length

自 v1.1 起引入

计算字符串或数组的长度。

对于 String 或 FixedString 参数：计算字符串中的字节数。
对于 Array 参数：计算数组中的元素个数。
如果应用于 FixedString 参数，该函数是一个常量表达式。

请注意，字符串中的字节数不等同于 Unicode “code points” 的数量，也不等同于 Unicode “grapheme clusters”（通常称为“字符”）的数量，也不等同于可见字符串宽度。

字符串中允许包含 ASCII 的 NULL 字节，这些字节同样会被计数。

语法

length(x)

别名: OCTET_LENGTH

参数

x — 要计算其字节数（对于 String/FixedString）或元素数量（对于 Array）的值。类型为 String、FixedString 或 Array(T)。

返回值

返回 String/FixedString x 中的字节数，或数组 x 中的元素数量，类型为 UInt64。

示例

String 示例

SELECT length('Hello, world!')

数组示例

SELECT length(['Hello', 'world'])

constexpr 示例

WITH 'hello' || toString(number) AS str
SELECT str,
isConstant(length(str)) AS str_length_is_constant,
isConstant(length(str::FixedString(6))) AS fixed_str_length_is_constant
FROM numbers(3)

┌─str────┬─str_length_is_constant─┬─fixed_str_length_is_constant─┐
│ hello0 │                      0 │                            1 │
│ hello1 │                      0 │                            1 │
│ hello2 │                      0 │                            1 │
└────────┴────────────────────────┴──────────────────────────────┘

Unicode 示例

SELECT 'ёлка' AS str1, length(str1), lengthUTF8(str1), normalizeUTF8NFKD(str1) AS str2, length(str2), lengthUTF8(str2)

┌─str1─┬─length(str1)─┬─lengthUTF8(str1)─┬─str2─┬─length(str2)─┬─lengthUTF8(str2)─┐
│ ёлка │            8 │                4 │ ёлка │           10 │                5 │
└──────┴──────────────┴──────────────────┴──────┴──────────────┴──────────────────┘

ascii_vs_utf8 示例

SELECT 'ábc' AS str, length(str), lengthUTF8(str)

┌─str─┬─length(str)──┬─lengthUTF8(str)─┐
│ ábc │            4 │               3 │
└─────┴──────────────┴─────────────────┘

notEmpty

引入于：v1.1

检查输入数组是否为非空。

如果数组至少包含一个元素，则视为非空。

注意

可以通过启用 optimize_functions_to_subcolumns 设置进行优化。启用 optimize_functions_to_subcolumns = 1 时，该函数只读取 size0 子列，而不是读取并处理整个数组列。查询 SELECT notEmpty(arr) FROM table 会被转换为 SELECT arr.size0 != 0 FROM TABLE。

该函数也适用于字符串或 UUID 类型。

语法

notEmpty(arr)

参数

arr — 输入数组。Array(T)

返回值

对于非空数组返回 1，对于空数组返回 0，类型为 UInt8

示例

用法示例

SELECT notEmpty([1,2]);

range

自 v1.1 版本引入。

返回一个由数字组成的数组，从 start 开始，以 step 为步长，直到 end - 1 结束。

支持的类型为：

UInt8/16/32/64
Int8/16/32/64]
所有参数 start、end、step 必须是以上支持类型之一。返回数组的元素类型将是这些参数类型的超类型。
如果函数返回的数组总长度超过了由设置 function_range_max_elements_in_block 指定的元素个数，则会抛出异常。
如果任一参数的类型为 Nullable(nothing)，则返回 NULL。如果任一参数的值为 NULL（Nullable(T) 类型），则会抛出异常。

语法

range([start, ] end [, step])

参数

start — 可选。数组的第一个元素。如果使用了 step，则必须指定。默认值：0。
end — 必填。构造数组时的上界（不包含该值）。
step — 可选。决定数组中每个元素之间的递增步长。默认值：1。

返回值

从 start 开始到 end - 1，步长为 step 的数值数组。Array(T)

示例

用法示例

SELECT range(5), range(1, 5), range(1, 5, 2), range(-1, 5, 2);

┌─range(5)────┬─range(1, 5)─┬─range(1, 5, 2)─┬─range(-1, 5, 2)─┐
│ [0,1,2,3,4] │ [1,2,3,4]   │ [1,3]          │ [-1,1,3]        │
└─────────────┴─────────────┴────────────────┴─────────────────┘

replicate

引入版本：v1.1

创建一个仅包含单个值的数组。

语法

replicate(x, arr)

参数

x — 用于填充结果数组的值。Any
arr — 一个数组。Array(T)

返回值

返回一个与 arr 长度相同、填充为值 x 的数组。Array(T)

示例

用法示例

SELECT replicate(1, ['a', 'b', 'c']);

┌─replicate(1, ['a', 'b', 'c'])───┐
│ [1, 1, 1]                       │
└─────────────────────────────────┘

reverse

首次引入版本：v1.1

反转输入数组中元素的顺序，或反转输入字符串中的字符顺序。

语法

reverse(arr | str)

参数

arr | str — 源数组或字符串。Array(T) 或 String

返回值

返回一个数组或字符串，其元素或字符的顺序被反转。

示例

反转数组

SELECT reverse([1, 2, 3, 4]);

[4, 3, 2, 1]

字符串反转

SELECT reverse('abcd');

'dcba'

距离函数

所有受支持的函数详见距离函数文档。

array​

arrayAUCPR​

arrayAll​

arrayAvg​

arrayCompact​

arrayConcat​

arrayCount​

arrayCumSum​

arrayCumSumNonNegative​

arrayDifference​

arrayDistinct​

arrayDotProduct​

arrayElement​

arrayElementOrNull​

arrayEnumerate​

arrayEnumerateDense​

arrayEnumerateDenseRanked​

arrayEnumerateUniq​

arrayEnumerateUniqRanked​

arrayExcept​

arrayExists​

arrayFill​

arrayFilter​

arrayFirst​

arrayFirstIndex​

arrayFirstOrNull​

arrayFlatten​

arrayFold​

arrayIntersect​

arrayJaccardIndex​

arrayJoin​

arrayLast​

arrayLastIndex​

arrayLastOrNull​

arrayLevenshteinDistance​

arrayLevenshteinDistanceWeighted​

arrayMap​

arrayMax​

arrayMin​

arrayNormalizedGini​

arrayPartialReverseSort​

arrayPartialShuffle​

arrayPartialSort​

arrayPopBack​

arrayPopFront​

arrayProduct​

arrayPushBack​

arrayPushFront​

arrayROCAUC​

arrayRandomSample​

arrayReduce​

arrayReduceInRanges​

arrayRemove​

arrayResize​

arrayReverse​

arrayReverseFill​

arrayReverseSort​

arrayReverseSplit​

arrayRotateLeft​

arrayRotateRight​

arrayShiftLeft​

arrayShiftRight​

arrayShingles​

arrayShuffle​

arraySimilarity​

arraySlice​

arraySort​

arraySplit​

arraySum​

arraySymmetricDifference​

arrayUnion​

arrayUniq​

arrayWithConstant​

arrayZip​

arrayZipUnaligned​

countEqual​

empty​

emptyArrayDate​

emptyArrayDateTime​

emptyArrayFloat32​

array

arrayAUCPR

arrayAll

arrayAvg

arrayCompact

arrayConcat

arrayCount

arrayCumSum

arrayCumSumNonNegative

arrayDifference

arrayDistinct

arrayDotProduct

arrayElement

arrayElementOrNull

arrayEnumerate

arrayEnumerateDense

arrayEnumerateDenseRanked

arrayEnumerateUniq

arrayEnumerateUniqRanked

arrayExcept

arrayExists

arrayFill

arrayFilter

arrayFirst

arrayFirstIndex

arrayFirstOrNull

arrayFlatten

arrayFold

arrayIntersect

arrayJaccardIndex

arrayJoin

arrayLast

arrayLastIndex

arrayLastOrNull

arrayLevenshteinDistance

arrayLevenshteinDistanceWeighted

arrayMap

arrayMax

arrayMin

arrayNormalizedGini

arrayPartialReverseSort

arrayPartialShuffle

arrayPartialSort

arrayPopBack

arrayPopFront

arrayProduct

arrayPushBack

arrayPushFront

arrayROCAUC

arrayRandomSample

arrayReduce

arrayReduceInRanges

arrayRemove

arrayResize

arrayReverse

arrayReverseFill

arrayReverseSort

arrayReverseSplit

arrayRotateLeft

arrayRotateRight

arrayShiftLeft

arrayShiftRight

arrayShingles

arrayShuffle

arraySimilarity

arraySlice

arraySort

arraySplit

arraySum

arraySymmetricDifference

arrayUnion

arrayUniq

arrayWithConstant

arrayZip

arrayZipUnaligned

countEqual

empty

emptyArrayDate

emptyArrayDateTime

emptyArrayFloat32