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

元组函数

注意

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

flattenTuple​

引入于：v22.6

将具名的嵌套 tuple 扁平化。 返回的 tuple 中的每个元素表示输入 tuple 中对应元素的路径。

语法

flattenTuple(input)

参数

返回值

返回一个输出 Tuple，其元素为原始输入中的路径。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，包含这些列；否则返回 Tuple(T1, T2, ...)。执行该函数没有额外开销。 tuple 通常用作 IN 运算符参数的中间值，或用于创建 lambda 函数的形式参数列表。tuple 不能写入表中。

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

语法

参数

  • 无。

返回值

示例

典型示例

SELECT tuple(1, 2)

(1,2)

tupleConcat​

自 v23.8 起引入

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

语法

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

参数

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

返回值

返回一个元组，包含所有输入元组中的所有元素。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((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement​

引入版本：v1.1

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

按索引访问时，索引从 1 开始计数。 按名称访问时，可以将元素名称以字符串形式提供（仅适用于具名元组）。

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

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

语法

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

参数

返回值

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

示例

按索引访问

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

你好

包含表的命名元组

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

你好

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 是一个列式数据库管理系统,用于在线分析处理查询。' 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

对一个由分子组成的 tuple 按给定的分母执行整数除法，并返回由商组成的 tuple。 如果任一输入参数中包含非整数元素，则会先将每个非整数分子或分母四舍五入到最接近的整数，再计算结果。 当除数为 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 类似，对一个分子元组和一个分母元组执行整数除法，并返回商的元组。 当除数为 0 时，会将对应的商返回为 0，而不是抛出异常。 如果任一元组包含非整数元素，则会先将每个非整数分子或除数四舍五入到最接近的整数，然后再计算结果。

语法

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 或除数中包含非整数元素，则会先将每个非整数的被除数或除数四舍五入到最接近的整数，再计算结果。

语法

tupleIntDivOrZeroByNumber(tuple_num, div)

参数

返回值

返回一个由各个商组成的元组，对于除数为 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((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal)

示例

基本用法

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

(-1, -1)

tupleModulo​

引入自：v23.8

返回一个元组，其中包含两个元组对应元素相除所得的余数（模）。

语法

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

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

语法

tupleMultiply(t1, t2)

参数

返回值

返回包含乘积结果的元组。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 转换为列名数组。对于形如 Tuple(a T, b T, ...) 的 tuple，它返回一个字符串数组，表示该 tuple 中具名列的名称。如果 tuple 元素没有显式名称，则会使用它们的索引作为列名。

语法

参数

  • 无。

返回值

示例

典型示例

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

['a','b']

tupleNegate​

引入版本：v21.11

计算元组中各元素的相反数。

语法

tupleNegate(t)

参数

返回值

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

示例

基本用法

SELECT tupleNegate((1, 2))

(-1, -2)

tuplePlus​

自 v21.11 引入

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

语法

tuplePlus(t1, t2)

别名: vectorSum

参数

返回值

返回一个元组，包含各输入元组对应元素之和。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') │
└─────┴────┴────┴────┴───────────┘

距离函数​

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