跳到主要内容
跳到主要内容

元组函数

注意

下述文档内容是根据 system.functions 系统表生成的。

flattenTuple​

引入于：v22.6

将具名且嵌套的 tuple 扁平化。 返回的 tuple 的各个元素是输入 tuple 中元素的路径。

语法

flattenTuple(input)

参数

返回值

返回一个输出元组，其元素为原始输入中的路径。Tuple(T)

示例

用法示例

CREATE TABLE tab(t Tuple(a UInt32, b Tuple(c String, d UInt32))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO tab VALUES ((3, ('c', 4)));

SELECT flattenTuple(t) FROM tab;

┌─flattenTuple(t)┐
│ (3, 'c', 4)    │
└────────────────┘

tuple​

引入于：v

通过将输入参数分组来返回一个元组（tuple）。

对于类型为 T1、T2、… 的列 C1、C2、…，如果这些列名是唯一的并且可以作为未加引号的标识符使用，则返回一个命名类型 Tuple(C1 T1, C2 T2, …) 的元组，包含这些列；否则返回 Tuple(T1, T2, …)。执行该函数不会产生额外开销。 元组通常用作 IN 运算符参数的中间值，或用于创建 lambda 函数的形式参数列表。元组不能直接写入表中。

该函数实现运算符 (x, y, …)。

语法

参数

  • 无

返回值

示例

典型示例

SELECT tuple(1, 2)

(1,2)

tupleConcat​

首次引入于：v23.8

合并作为参数传入的元组。

语法

tupleConcat(tuple1[, tuple2, [...]])

参数

  • tupleN — 任意数量的 Tuple 类型的参数。Tuple(T)

返回值

返回一个包含所有输入 Tuple 中元素的 Tuple。Tuple(T)

示例

使用示例

SELECT tupleConcat((1, 2), ('a',), (true, false))

(1, 2, 'a', true, false)

tupleDivide​

首次引入于：v21.11

计算两个大小相同的元组（tuple）中对应元素相除的结果。

注意

除以零时将返回 inf。

语法

tupleDivide(t1, t2)

参数

返回值

返回一个包含除法结果的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleDivide((1, 2), (2, 3))

(0.5, 0.6666666666666666)

tupleDivideByNumber​

自 v21.11 引入

返回一个元组，其中所有元素都被某个数字相除。

注意

除以零将返回 inf。

语法

tupleDivideByNumber(tuple, number)

参数

返回值

返回一个各元素已被除后的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement​

引入于：v1.1

按索引或名称从 tuple 中提取元素。

按索引访问时，需要使用从 1 开始的数字索引。 按名称访问时，可以将元素名称作为字符串提供（仅适用于具名 tuple）。

支持负索引。在这种情况下，将从末尾开始编号选择相应的元素。例如，tuple.-1 是 tuple 中的最后一个元素。

可以指定一个可选的第三个参数作为默认值：当访问的元素不存在时，将返回该默认值，而不是抛出异常。 所有参数必须是常量。

此函数在运行时开销为零，并实现了运算符 x.index 和 x.name。

语法

tupleElement(tuple, index|name[, default_value])

参数

返回值

返回指定索引或名称处的元素。Any

示例

索引访问

SELECT tupleElement((1, 'hello'), 2)

hello

负索引

SELECT tupleElement((1, 'hello'), -1)

hello

与表配合使用的命名元组

CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;

Alice

使用默认值

SELECT tupleElement((1, 2), 5, 'not_found')

not_found

运算符语法

SELECT (1, 'hello').2

hello

tupleHammingDistance​

引入于：v21.1

返回两个大小相同的元组之间的汉明距离。

注意

结果类型的确定方式与算术函数相同，根据输入元组中元素的数量来确定。

SELECT
    toTypeName(tupleHammingDistance(tuple(0), tuple(0))) AS t1,
    toTypeName(tupleHammingDistance((0, 0), (0, 0))) AS t2,
    toTypeName(tupleHammingDistance((0, 0, 0), (0, 0, 0))) AS t3,
    toTypeName(tupleHammingDistance((0, 0, 0, 0), (0, 0, 0, 0))) AS t4,
    toTypeName(tupleHammingDistance((0, 0, 0, 0, 0), (0, 0, 0, 0, 0))) AS t5

┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
│ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
└───────┴────────┴────────┴────────┴────────┘

语法

tupleHammingDistance(t1, t2)

参数

返回值

返回汉明距离。UInt8/16/32/64

示例

用法示例

SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))

2

使用 MinHash 检测近似重复字符串

SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string)

2

tupleIntDiv​

引入版本：v23.8

对一个分子元组和一个分母元组执行整数除法运算。返回一个由商组成的元组。 如果任一元组包含非整数元素，则对每个非整数分子或除数先四舍五入到最接近的整数，再计算结果。 被 0 除会抛出错误。

语法

tupleIntDiv(tuple_num, tuple_div)

参数

返回值

返回商的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))

(3, 2, 1)

带小数

SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))

(2, 1, 0)

tupleIntDivByNumber​

引入版本：v23.8

对一个由分子组成的元组按给定分母执行整数除法，并返回由商组成的元组。 如果任一输入参数包含非整数元素，则会对每个非整数分子或除数先四舍五入到最接近的整数再进行计算。 如果发生除以 0 的情况，会抛出错误。

语法

tupleIntDivByNumber(tuple_num, div)

参数

返回值

返回一个由商值组成的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleIntDivByNumber((15, 10, 5), 5)

(3, 2, 1)

含小数

SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)

(2, 1, 0)

tupleIntDivOrZero​

引入于：v23.8

与 tupleIntDiv 类似，对一个分子 tuple 和一个分母 tuple 执行整数除法，并返回一个由商组成的 tuple。 在除以 0 的情况下，返回的商为 0，而不是抛出异常。 如果任一 tuple 中包含非整数元素，则会先将每个非整数分子或除数四舍五入到最接近的整数，然后再计算结果。

语法

tupleIntDivOrZero(tuple_num, tuple_div)

参数

返回值

返回商的元组。对于除数为 0 的情况返回 0。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

除数包含零的情况

SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))

(0, 0, 0)

tupleIntDivOrZeroByNumber​

引入于：v23.8

与 tupleIntDivByNumber 类似，它对由若干分子构成的 tuple 与给定分母执行整数除法，并返回一个由商组成的 tuple。 对于除数为零的情况，它不会抛出错误，而是将对应商返回为零。 如果 tuple 或 div 参数中包含非整数元素，则会先将每个非整数分子或除数四舍五入到最接近的整数，再据此计算结果。

语法

tupleIntDivOrZeroByNumber(tuple_num, div)

参数

返回值

返回一个包含各个商的 Tuple，当除数为 0 时，对应位置的商为 0。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)

(3, 2, 1)

当除数为零时

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)

(0, 0, 0)

tupleMinus​

引入版本：v21.11

计算两个相同长度的元组中对应元素的差值。

语法

tupleMinus(t1, t2)

别名: vectorDifference

参数

返回值

返回一个包含逐元素相减结果的元组（tuple）。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleMinus((1, 2), (2, 3))

(-1, -1)

tupleModulo​

引入版本：v23.8

返回一个 tuple，其中包含两个 tuple 做除法运算时各元素的余数（模）。

语法

tupleModulo(tuple_num, tuple_mod)

参数

返回值

返回由各次除法运算所得余数组成的元组。当除数为零时会抛出错误。返回类型为 Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleModulo((15, 10, 5), (5, 3, 2))

(0, 1, 1)

tupleModuloByNumber​

引入版本：v23.8

返回一个元组，其中包含将元组中各元素分别除以指定除数后得到的模（余数）。

语法

tupleModuloByNumber(tuple_num, div)

参数

返回值

返回一个由各元素与除数相除所得余数组成的元组。当除数为零时会抛出错误。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleModuloByNumber((15, 10, 5), 2)

(1, 0, 1)

tupleMultiply​

引入于：v21.11

计算两个长度相同的元组（tuple）中对应元素相乘的结果。

语法

tupleMultiply(t1, t2)

参数

返回值

返回一个包含乘积结果的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleMultiply((1, 2), (2, 3))

(2, 6)

tupleMultiplyByNumber​

引入于：v21.11

返回一个各元素都乘以指定数值后的 tuple。

语法

tupleMultiplyByNumber(tuple, number)

参数

返回值

返回一个其各元素已完成乘法运算的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleMultiplyByNumber((1, 2), -2.1)

(-2.1, -4.2)

tupleNames​

引入版本：v

将一个元组转换为列名数组。对于形如 Tuple(a T, b T, ...) 的元组，它会返回一个字符串数组，其中包含该元组中具名列的名称。如果元组元素没有显式名称，则会使用它们的索引作为列名。

语法

参数

  • 无

返回值

示例

典型示例

SELECT tupleNames(tuple(1 as a, 2 as b))

['a','b']

tupleNegate​

自 v21.11 版本引入

计算元组元素的相反数。

语法

tupleNegate(t)

参数

返回值

返回一个包含取负结果的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleNegate((1, 2))

(-1, -2)

tuplePlus​

引入版本：v21.11

计算两个长度相同的元组中对应元素之和。

语法

tuplePlus(t1, t2)

别名：vectorSum

参数

返回值

返回一个 Tuple，其中的每个元素是对应位置输入 Tuple 元素的和。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tuplePlus((1, 2), (2, 3))

(3, 5)

tupleToNameValuePairs​

引入于：v21.9

将一个 tuple 转换为元素为 (name, value) 对的数组。 例如，tuple Tuple(n1 T1, n2 T2, ...) 会被转换为 Array(Tuple('n1', T1), Tuple('n2', T2), ...)。 tuple 中的所有元素必须是相同类型。

语法

tupleToNameValuePairs(tuple)

参数

返回值

返回包含 (name, value) 对的数组。Array(Tuple(String, T))

示例

命名元组

SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))

[('1', 1593), ('2', 2502)]

未命名元组

SELECT tupleToNameValuePairs(tuple(3, 2, 1))

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

untuple​

在调用处对 tuple 元素执行句法替换。

结果列的名称由具体实现决定，并且可能发生变化。请不要在使用 untuple 后依赖任何特定的列名。

语法

untuple(x)

您可以使用 EXCEPT 表达式在查询结果中排除某些列。

参数

  • x — 一个 tuple 函数、列或元素构成的元组。参见 Tuple。

返回值

  • 无。

示例

输入表：

┌─key─┬─v1─┬─v2─┬─v3─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 20 │ 40 │ 30 │ 15 │ (33,'ab') │
│   2 │ 25 │ 65 │ 70 │ 40 │  6 │ (44,'cd') │
│   3 │ 57 │ 30 │ 20 │ 10 │  5 │ (55,'ef') │
│   4 │ 55 │ 12 │  7 │ 80 │ 90 │ (66,'gh') │
│   5 │ 30 │ 50 │ 70 │ 25 │ 55 │ (77,'kl') │
└─────┴────┴────┴────┴────┴────┴───────────┘

将 Tuple 类型列用作 untuple 函数参数的示例：

查询：

SELECT untuple(v6) FROM kv;

结果：

┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘

使用 EXCEPT 表达式的示例：

查询：

SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;

结果：

┌─key─┬─v1─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 30 │ 15 │ (33,'ab') │
│   2 │ 25 │ 40 │  6 │ (44,'cd') │
│   3 │ 57 │ 10 │  5 │ (55,'ef') │
│   4 │ 55 │ 80 │ 90 │ (66,'gh') │
│   5 │ 30 │ 25 │ 55 │ (77,'kl') │
└─────┴────┴────┴────┴───────────┘

距离函数​

所有受支持的函数在距离函数文档中都有说明。