数组函数

array

引入于：v1.1

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

参数应为常量，并且具有共享的共同超类型。必须传递至少一个参数，因为否则不清楚要创建哪种类型的数组。这意味着您不能使用此函数创建空数组。要创建空数组，请使用emptyArray*函数。

使用[ ]运算符获得相同的功能。

语法

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

参数

x1 — 任何类型 T 的常量值。如果仅提供此参数，则数组将为类型 T。 - [, x2, ..., xN] — 共享与x1相同超类型的额外 N 个常量值

返回值

返回一个数组，其中 '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])

参数

cores — 评分预测模型给出的分数。 Array((U)Int*) 或 Array(Float*)
labels — 样本标签，通常正样本为 1，负样本为 0。 Array((U)Int*) 或 Array(Enum)
partial_offsets —
可选。用于计算 PR 曲线部分面积的一个 Array(T)，包括三个非负整数（相当于 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] — 可选。N 个条件数组，为 lambda 函数提供额外参数。 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] — 可选。作为参数传递给 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] — 可选。作为参数传递给 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

返回两个数组的点积。

备注

两个向量的大小必须相等。数组和元组也可以包含混合元素类型。

语法

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)

返回值

两个向量的点积。

备注

返回类型由参数的类型决定。如果数组或元组包含混合元素类型，则结果类型为超类型。

(U)Int* 或 Float* 或 Decimal

示例

数组示例

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)

返回值

返回与输入数组相同类型的数组，包含未在 except 中找到的 source 中的元素。 Array(T)

示例

基本

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

[1, 2, 2, 4]

有 NULL 的情况 1

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

[1, NULL, NULL]

有 NULL 的情况 2

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 条件，使用源数组和条件数组的元素。当 lambda 函数在位置 i 处评估为 false 时，该函数将该元素替换为数组当前状态中位置 i-1 的元素。第一个元素始终被保留，不受任何条件影响。

语法

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

参数

func(x [, y1, ..., yN]) — 操作源数组 (x) 和条件数组 (y) 元素的 lambda 函数 func(x [, y1, y2, ... yN]) → F(x [, y1, y2, ... yN] )。 [Lambda function`](/sql-reference/functions/overview#arrow-operator-and-lambda)
source_arr — 要处理的源数组。 Lambda function
[, cond1_arr, ... , condN_arr] — 可选。N 个条件数组，为 lambda 函数提供额外参数。 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

返回一个数组，仅包含源数组中返回 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).

返回值

返回源数组中第一个使得 λ 为 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] — 可选。N个条件数组，为 lambda 函数提供额外参数。 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] — 可选。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)

参数

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 的常规函数形成对比，常规函数将输入值映射到同一行的输出值，而聚合函数则将一组行“压缩”或“减少”成一行汇总（或者在与 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  │
└─────────────┴──────────┴─────────┘

使用 Tuple

-- 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 函数
source — 要处理的源数组。 Array(T)
[, cond1, ... , condN] — 可选。 N 个条件数组，向 lambda 函数提供附加参数。 Array(T)

返回值

返回源数组中满足 func 的最后一个元素，否则返回 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 函数
source_arr — 要处理的源数组。 Array(T)
[, cond1_arr, ... , condN_arr] — 可选。 N 个条件数组，向 lambda 函数提供附加参数。 Array(T)

返回值

返回源数组中最后一个满足 func 的元素的索引，否则返回 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] — 可选。 N 个条件数组，向 lambda 函数提供附加参数。 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 函数
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 函数
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 函数
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 函数
arr — 要排序的数组。 Array(T)
arr1, ... ,arrN — N 个附加数组，适用于 f 接受多个参数的情况。 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 函数
arr — 要排序的数组。 Array(T)
arr1, ... ,arrN — N 个附加数组，适用于 f 接受多个参数的情况。 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] — 可选。 N 个条件数组，向 lambda 函数提供附加参数。 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 曲线通过在 y 轴上绘制真正率（TPR）和在 x 轴上绘制假正率（FPR）来创建，涵盖所有阈值。结果值范围从零到一，值越高表示模型性能越好。

ROC AUC（也称为 AUC）是机器学习中的一个概念。更多详细信息，请参见这里，这里和这里。

语法

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

参数

scores — 预测模型的分数。 Array((U)Int*) 或 Array(Float*)
labels — 样本的标签，通常对于正样本为 1，对于负样本为 0。 Array((U)Int*) 或 Enum
scale — 可选。决定是否返回标准化面积。如果为 false，则返回 TP（真正例）x 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] — N 个数组，作为 agg_f 的参数。 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] │
└─────────────────────────────┘

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 函数
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 函数
source_arr — 要处理的源数组。 Lambda 函数
[, 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 — 要生成 shingles 数组的数组。Array(T)
l — 每个 shingle 的长度。(U)Int*

返回值

生成的 shingles 数组 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 (可选) — 可选。用于随机数生成的种子。如果未提供，则使用随机值。(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*)

返回值

返回基于加权 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, 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 — 可选。N个附加数组，当 f 接受多个参数时使用。

返回值

如果未提供 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] — 可选。N个条件数组，为 lambda 函数提供附加参数。 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 函数
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 个元素的值，任何类型。

返回值

返回一个值为 x 的 N 元素的数组。 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;。

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

语法

empty(arr)

参数

arr — 输入数组。 Array(T)

返回值

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

示例

用法示例

SELECT empty([]);

emptyArrayDate

引入版本：v1.1

返回一个空的日期数组。

语法

emptyArrayDate()

参数

无。 返回值

一个空的日期数组。 Array(T)

示例

用法示例

SELECT emptyArrayDate

[]

emptyArrayDateTime

引入版本：v1.1

返回一个空的日期时间数组。

语法

emptyArrayDateTime()

参数

无。 返回值

一个空的日期时间数组。 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()

参数

无。 返回值

一个空的字符串数组。 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。

如果集合和子集元素没有共享通用超类型，将引发 NO_COMMON_TYPE 异常。

示例

空数组

SELECT hasAll([], [])

包含 NULL 值的数组

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

包含不同类型值的数组

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

包含字符串值的数组

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。

换句话说，函数将检查 array2 的所有元素是否如函数 hasAll 所示包含在 array1 中。此外，它还会检查在两个数组中元素的顺序是否一致。

如果 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' 的第一个元素的索引（从 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

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

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

请注意，字符串中的字节数与 Unicode "代码点" 的数量不同，它与 Unicode "图形簇"（通常称为 "字符"）的数量不同，它与可见字符串宽度的多少也不同。

字符串中可以有 ASCII NULL 字节，并且这些字节也会被计算在内。

语法

length(x)

参数

x — 要计算字节数（对于字符串/固定字符串）或元素数量（对于数组）的值。 String 或 FixedString 或 Array(T)

返回值

返回字符串/固定字符串 x 中的字节数/数组 x 中元素的数量 UInt64

示例

字符串示例

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 到 end - 1 的数字数组，按 step 递增。

支持的类型有：

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'

Distance functions

所有支持的函数在 distance functions documentation 中有描述。

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​

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​

emptyArrayFloat64​

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

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

emptyArrayFloat64