数组函数

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)

从服务器收到异常(版本 25.4.3):
代码: 386. DB::Exception: 从 localhost:9000 收到。DB::Exception:
类型 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 函数，则返回其结果元素的平均值。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)

返回值

返回源数组元素的部分和数组，其中任何为负的累积和都会被替换为零。结果类型与输入数组的数值类型一致。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

示例

基本用法

-- 当 clear_depth=1 且 max_array_depth=1 时,结果与 arrayEnumerateDense 给出的结果相同。

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

[1,2,1,3]

与多维数组一起使用

-- 在此示例中,arrayEnumerateDenseRanked 用于获取一个数组,该数组指示多维数组中每个元素在具有相同值的元素中的排名位置。
-- 对于传入数组的第一行 [10, 10, 30, 20],结果的对应第一行是 [1, 1, 2, 3],
-- 表示 10 是第一个遇到的数字,出现在位置 1 和 2,30 是第二个遇到的数字,出现在位置 3,
-- 20 是第三个遇到的数字,出现在位置 4。
-- 对于第二行 [40, 50, 10, 30],结果的对应第二行是 [4,5,1,2],表示 40
-- 和 50 是第四个和第五个遇到的数字,分别出现在该行的位置 1 和 2,另一个 10
-- (第一个遇到的数字)出现在位置 3,30(第二个遇到的数字)出现在最后位置。

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

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

使用更大 clear_depth 的示例

-- 将 clear_depth 设置为 2 会导致每行的枚举单独重新开始。

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, ... — 可选。用于确定元组唯一性的、与 arr1 具有相同大小的其他数组。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 聚合

-- 每个目标 ID 计算了转化次数(Goals 嵌套数据结构中的每个元素代表一个已达成的目标,我们称之为转化)
-- 以及会话数。如果不使用 ARRAY JOIN,会话数将按 sum(Sign) 计算。但在此特定场景下,
-- 由于嵌套的 Goals 结构导致行数倍增,为了确保每个会话仅计数一次,我们对
-- arrayEnumerateUniq(Goals.ID) 函数的值应用条件进行过滤。

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

-- 当 clear_depth=1 且 max_array_depth=1 时,arrayEnumerateUniqRanked 的结果
-- 与 arrayEnumerateUniq 对同一数组给出的结果相同。

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

[1, 1, 2]

示例 2

-- 当 clear_depth=1 且 max_array_depth=1 时,arrayEnumerateUniqRanked 的结果
-- 与 arrayEnumerateUniq 对相同数组给出的结果一致。

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

[1, 1, 2]

示例 3

-- 在此示例中,arrayEnumerateUniqRanked 用于获取一个数组,该数组指示
-- 多维数组中每个元素在具有相同值的元素中的位置。对于传入数组的第一行 [1, 2, 3],对应的
-- 结果是 [1, 1, 1],表示这是首次遇到 1、2 和 3。
-- 对于传入数组的第二行 [2, 2, 1],对应的结果是 [2, 3, 3],
-- 表示 2 是第二次和第三次遇到,1 是第二次遇到。
-- 同样,对于传入数组的第三行 [3],
-- 对应的结果是 [2],表示 3 是第二次遇到。

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

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

示例 4

-- 将 clear_depth 设置为 2，会使每行的元素被分别枚举。
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] — 可选。N 个条件数组，为 lambda 函数提供附加参数。Array(T)

返回值

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

示例

使用示例

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

arrayFill

引入版本：v20.1

arrayFill 函数会从源数组的第一个元素开始，按顺序处理到最后一个元素，并在每个位置上使用源数组和条件数组中的元素，对一个 lambda 条件进行求值。当在位置 i 上该 lambda 函数的结果为 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] — 可选。为 Lambda 函数提供额外参数的 N 个条件数组。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 函数。- source_arr — 要处理的源数组。Array(T)。- [, cond1_arr, ... , condN_arr] — 可选。作为附加参数传递给 Lambda 函数的 N 个条件数组。Array(T)。

返回值

返回源数组中使 λ 结果为 true 的第一个元素，否则返回类型 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]) — 一个用于对源数组 (x) 和条件数组 (y) 的元素进行操作的 lambda 函数。Lambda function
source_arr — 要处理的源数组。Array(T)
[, cond1_arr, ... , condN_arr] — 可选。提供给 lambda 函数的 N 个条件数组，作为附加参数。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]) — 形式为 λ(acc, x1 [, x2, x3, ... xN]) → F(acc, x1 [, x2, x3, ... xN]) 的 lambda 函数，其中 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 中的常规函数不同，常规函数是在同一行内将输入值映射为输出值，而聚合函数则对一组行进行“压缩”或“归约”，将其变为单个汇总行（或在与 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 会影响查询的所有部分

-- arrayJoin 函数会影响查询的所有部分,包括 WHERE 子句。请注意结果为 2,即使子查询仅返回了 1 行。

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

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

同时使用多个 arrayJoin 函数

- 查询可以使用多个 arrayJoin 函数。在这种情况下,转换将执行多次,行数会成倍增加。

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 │
└─────────────┴──────────┴─────────┘

优化导致的意外结果

-- 对同一表达式使用多个 arrayJoin 可能因优化而无法产生预期结果。
-- 对于这些情况,请考虑通过不影响连接结果的额外操作来修改重复的数组表达式。
- 例如:arrayJoin(arraySort(arr)), arrayJoin(arrayConcat(arr, []))

SELECT
    arrayJoin(dice) as first_throw,
    /* arrayJoin(dice) as second_throw */ -- 技术上正确,但会导致结果集为空
    arrayJoin(arrayConcat(dice, [])) as second_throw -- 有意更改表达式以强制重新计算
FROM (
    SELECT [1, 2, 3, 4, 5, 6] as dice
);

┌─第一次投掷─┬─第二次投掷─┐
│           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 语法

-- 注意下面 `SELECT` 查询中的 ARRAY JOIN 语法,它提供了更强大的功能。
-- ARRAY JOIN 允许您同时展开具有相同元素数量的多个数组。

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  │
└─────────────┴──────────┴─────────┘

使用元组

-- 也可以使用元组（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 函数。- 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]) — 作用于源数组 (x) 和条件数组 (y) 元素的 lambda 函数。Lambda 函数。
source_arr — 要处理的源数组。Array(T)。
[, cond1_arr, ... , condN_arr] — 可选。提供给 lambda 函数的 N 个条件数组，作为额外参数。Array(T)。

返回值

返回源数组中最后一个不满足 λ 条件的元素，否则返回 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] — 可选。作为附加参数传递给 Lambda 函数的 N 个条件数组。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, ... — 可选。N 个条件数组，为 Lambda 函数提供额外参数。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]

物化

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 函数
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。可选。
- 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 │
└───────────────────────────────┘

使用多参数聚合函数的示例

--如果聚合函数接受多个参数,则必须将该函数应用于大小相同的多个数组。

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) 具有相同的功能，但除了数组之外，还适用于其他数据类型。

语法

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] — 可选。提供给 lambda 函数作为额外参数的 N 个条件数组。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

生成一个由 shingle 组成的数组（类似于字符串的 n-grams），即从输入数组中按指定长度提取的连续子数组。

语法

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)

示例

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

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*)

返回值

返回两个数组之间的相似度（基于加权 Levenshtein 距离），取值范围为 0 到 1，类型为 Float64

示例

使用示例

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, 数组末尾]。(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] — 可选。N 个条件数组，为 Lambda 函数提供额外参数。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 起引入

返回一个空字符串数组

语法

emptyArrayString()

参数

无。

返回值

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

示例

使用示例

SELECT emptyArrayString

[]

emptyArrayToSingle

自 v1.1 引入

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

语法

emptyArrayToSingle(arr)

参数

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

返回值

一个仅包含单个元素的数组，其元素为该数组元素类型的默认值。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(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'])

抛出 NO_COMMON_TYPE 异常

数组的数组（嵌套数组）

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'])

抛出 `NO_COMMON_TYPE` 异常

数组的数组

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

hasSubstr

引入于：v20.6

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

换句话说，该函数会像 hasAll 函数一样检查 array1 中是否包含 array2 的所有元素。此外，它还会检查 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'])

抛出 `NO_COMMON_TYPE` 异常

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，则返回第一个 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)

返回值

返回一个 UInt64 值，表示 String/FixedString x 中的字节数或数组 x 中的元素个数。

示例

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_UTF-8 示例

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。

该函数同样适用于字符串（String）或 UUID 类型。

语法

notEmpty(arr)

参数

arr — 输入数组。Array(T)

返回值

当数组非空时返回 1，当数组为空时返回 0。UInt8

示例

使用示例

SELECT notEmpty([1,2]);

range

引入于：v1.1

按 step 返回一个从 start 到 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