Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Tuple 函数

View as MarkdownEdit this pageReport an issueSet up docs MCP

dotProduct

引入版本：v21.11.0

计算两个向量 (大小相等的元组或数组) 的点积 (标量积) 。 返回对应元素乘积的总和。

语法

dotProduct(vector1, vector2)

别名: scalarProduct

参数

返回值

返回两个向量的点积。两个 BFloat16 数组会以 Float32 类型累加并返回 Float32。(U)Int* 或 Float* 或 Decimal

示例

基本用法

SELECT dotProduct((1, 2), (3, 4))
11

flattenTuple

引入版本：v22.6.0

将具名的嵌套 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

首次引入于：v1.1.0

将输入参数分组后返回一个元组。

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

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

语法

tuple([t1[, t2[ ...]])

参数

  • 无。

返回值

示例

典型用法

SELECT tuple(1, 2)
(1,2)

tupleConcat

引入版本：v23.8.0

将作为参数传入的元组合并在一起。

语法

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.0

计算两个或多个大小相同的Tuple按元素逐一相除的结果，按从左到右的顺序进行。

语法

tupleDivide(t1, t2[, tN, ...])

参数

返回值

返回一个包含逐元素相除所得商的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

两个 Tuple

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

三个Tuple

SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))
(10,5)

tupleDivideByNumber

首次引入版本：v21.11.0

返回一个 Tuple，其中所有元素都除以同一个数。

语法

tupleDivideByNumber(tuple, number)

参数

返回值

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

示例

基本用法

SELECT tupleDivideByNumber((1, 2), 0.5)
(2,4)

tupleElement

Introduced in: v1.1.0

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

按索引访问时，应使用从 1 开始的数字索引。 按名称访问时，可将元素名称作为字符串传入 (仅适用于命名Tuple) 。

支持负索引。在这种情况下，将选择对应的元素，并从末尾开始计数。例如，tuple.-1 表示Tuple中的最后一个元素。

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

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

Syntax

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

参数

返回值

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

示例

索引访问

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

负索引

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

带表的命名Tuple

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.0 引入

返回两个大小相同的 Tuple 之间的 Hamming 距离。

语法

tupleHammingDistance(t1, t2)

参数

返回值

返回 Hamming 距离。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

对两个或多个大小相同的Tuple按从左到右的顺序逐元素执行整数除法。返回由各商值组成的Tuple。 如果任一Tuple包含非整数元素，则会先将每个非整数被除数或除数舍入为最接近的整数，再计算结果。 除以 0 会抛出异常。

语法

tupleIntDiv(t1, t2[, tN, ...])

参数

返回值

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

示例

两个 Tuple

SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))
(3,2,1)

使用 Decimal

SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))
(2,1,0)

三个Tuple

SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))
(15,5)

tupleIntDivByNumber

引入版本：v23.8.0

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

语法

tupleIntDivByNumber(tuple_num, div)

参数

返回值

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

示例

基本用法

SELECT tupleIntDivByNumber((15, 10, 5), 5)
(3,2,1)

使用 Decimal 类型

SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)
(2,1,0)

tupleIntDivOrZero

引入版本：v23.8.0

与 tupleIntDiv 类似，对两个或多个大小相同的 Tuple 按从左到右的顺序逐元素执行整数除法。 如果发生除以 0，则该元素返回 0，而不是抛出异常。 如果任一 Tuple 包含非整数元素，则会先将每个非整数被除数或除数舍入为最接近的整数，再计算结果。

语法

tupleIntDivOrZero(t1, t2[, tN, ...])

参数

返回值

返回一个由整数商组成的 Tuple。对于除数为 0 的元素，返回 0。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

除数为 0 时

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

三个元组

SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))
(15,5)

tupleIntDivOrZeroByNumber

引入版本：v23.8.0

与 tupleIntDivByNumber 类似，它对一个由多个分子组成的元组和给定分母执行整数除法，并返回由各个商组成的元组。 当除数为零时，它不会抛出错误，而是返回商为零。 如果元组或 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.0

计算两个或多个大小相同的 Tuple 的逐元素差值，按从左到右的顺序进行。

语法

tupleMinus(t1, t2[, tN, ...])

别名: vectorDifference

参数

返回值

返回一个包含逐元素差值的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

两个 Tuple

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

三个元组

SELECT tupleMinus((10, 10), (3, 4), (2, 1))
(5,5)

tupleModulo

引入版本：v23.8.0

返回一个由两个或多个大小相同的元组按从左到右顺序逐元素相除所得余数组成的元组。

语法

tupleModulo(t1, t2[, tN, ...])

参数

返回值

返回一个按元素求余后得到的 Tuple。除以零时会抛出异常。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

两个 Tuple

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

三个元组

SELECT tupleModulo((10, 20), (7, 9), (3, 5))
(0,2)

tupleModuloByNumber

在 v23.8.0 中引入

返回一个 tuple，其中包含将给定除数分别对 tuple 中各元素进行求模 (取余) 运算后的结果。

语法

tupleModuloByNumber(tuple_num, div)

参数

返回值

返回除法余数组成的 Tuple。除以零时会抛出错误。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

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

tupleMultiply

首次引入版本：v21.11.0

计算两个或多个大小相同的 Tuple 的逐元素乘积。

语法

tupleMultiply(t1, t2[, tN, ...])

参数

返回值

返回一个包含对应元素乘积的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

两个 Tuple

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

三个 Tuple

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

tupleMultiplyByNumber

自 v21.11.0 引入

返回一个 Tuple，其中所有元素都乘以一个数值。

语法

tupleMultiplyByNumber(tuple, number)

参数

返回值

返回一个各元素均已相乘的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

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

tupleNames

引入版本：v24.8.0

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

语法

tupleNames(tuple)

参数

  • 无。

返回值

示例

典型示例

SELECT tupleNames(tuple(1 as a, 2 as b))
['1','2']

tupleNegate

Introduced in：v21.11.0

计算 Tuple 元素的相反数。

Syntax

tupleNegate(t)

参数

返回值

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

示例

基本用法

SELECT tupleNegate((1, 2))
(-1,-2)

tuplePlus

引入版本：v21.11.0

计算两个或多个大小相同的Tuple中对应元素之和。

语法

tuplePlus(t1, t2[, tN, ...])

别名：vectorSum

参数

返回值

返回一个包含各元素求和结果的Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

两个Tuple

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

三个Tuple

SELECT tuplePlus((1, 2), (2, 3), (3, 4))
(6,9)

tuplePositiveModuloByNumber

引入版本：v26.4.0

返回一个 Tuple 与给定除数做除法运算后所得正模 (余数) 组成的 Tuple。 与 tupleModuloByNumber 不同，结果始终为非负。

语法

tuplePositiveModuloByNumber(tuple_num, div)

参数

返回值

返回一个由非负余数组成的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)
(1,0,1)

tupleToNameValuePairs

引入版本：v21.9.0

将 Tuple 转换为由 (name, value) 对组成的 Array。 例如，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 函数参数的示例：

Querysql
SELECT untuple(v6) FROM kv;
Responsetext
┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘

使用 EXCEPT 表达式的示例：

Querysql
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;
Responsetext
┌─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') │
└─────┴────┴────┴────┴───────────┘

距离函数

所有支持的函数均在距离函数文档中有详细说明。

Navigation