跳转到主要内容
以下文档由 system.functions 系统表自动生成。

​
dotProduct

引入版本：v21.11.0 计算两个向量 (大小相等的元组或数组) 的点积 (标量积) 。 返回对应元素乘积的总和。 语法 
dotProduct(vector1, vector2)
别名: scalarProduct 参数 返回值 返回两个向量的点积。(U)Int* 或 Float* 或 Decimal 示例 基本用法
Query
SELECT dotProduct((1, 2), (3, 4))
Response
11

​
flattenTuple

引入版本：v22.6.0 将具名的嵌套 Tuple 展平。 返回的 Tuple 的元素为输入 Tuple 的路径。 语法 
flattenTuple(input)
参数 返回值 返回一个输出元组，其元素为原始输入中的路径。Tuple(T) 示例 使用示例
Query
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;
Response
┌─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[ ...]])
参数
  • 无。
返回值 示例 典型用法
Query
SELECT tuple(1, 2)
Response
(1,2)

​
tupleConcat

引入版本：v23.8.0 将作为参数传入的元组合并在一起。 语法 
tupleConcat(tuple1[, tuple2, [...]])
参数
  • tupleN — 任意数量的 Tuple 类型的参数。Tuple(T)
返回值 返回一个包含所有输入 Tuple 元素的 Tuple。Tuple(T) 示例 使用示例
Query
SELECT tupleConcat((1, 2), ('a',), (true, false))
Response
(1, 2, 'a', true, false)

​
tupleDivide

引入版本：v21.11.0 计算两个大小相同的元组中对应元素相除的结果。
除以零将返回 inf。
语法 
tupleDivide(t1, t2)
参数 返回值 返回包含除法结果的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleDivide((1, 2), (2, 3))
Response
(0.5, 0.6666666666666666)

​
tupleDivideByNumber

首次引入版本：v21.11.0 返回一个 Tuple，其中所有元素都除以同一个数。
除以零将返回 inf。
语法 
tupleDivideByNumber(tuple, number)
参数 返回值 返回一个各元素均已相除的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleDivideByNumber((1, 2), 0.5)
Response
(2, 4)

​
tupleElement

Introduced in: v1.1.0 按索引或名称从元组中提取元素。 按索引访问时，应使用从 1 开始的数字索引。 按名称访问时，可将元素名称作为字符串传入 (仅适用于命名元组) 。 支持负索引。在这种情况下，将选择对应的元素，并从末尾开始计数。例如，tuple.-1 表示元组中的最后一个元素。 可选的第三个参数用于指定默认值；当访问的元素不存在时，将返回该值，而不是抛出异常。 所有参数都必须是常量。 此函数没有运行时开销，并实现了运算符 x.index 和 x.name。 Syntax 
tupleElement(tuple, index|name[, default_value])
参数 返回值 返回指定索引或名称对应的元素。Any 示例 索引访问
Query
SELECT tupleElement((1, 'hello'), 2)
Response
hello
负索引
Query
SELECT tupleElement((1, 'hello'), -1)
Response
hello
带表的命名元组
Query
CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;
Response
Alice
带默认值
Query
SELECT tupleElement((1, 2), 5, 'not_found')
Response
not_found
运算符语法
Query
SELECT (1, 'hello').2
Response
hello

​
tupleHammingDistance

自 v21.1.0 引入 返回两个大小相同的 Tuple 之间的 Hamming 距离。
结果类型的确定方式与 算术函数 相同，具体取决于输入 Tuple 中的元素数量。
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)
参数 返回值 返回 Hamming 距离。UInt8/16/32/64 示例 使用示例
Query
SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))
Response
2
使用 MinHash 检测近似重复字符串
Query
SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string)
Response
2

​
tupleIntDiv

首次引入于：v23.8.0 对一个分子 Tuple 和一个分母 Tuple 执行整数除法，返回由各商组成的 Tuple。 如果任一 Tuple 包含非整数元素，则会先将每个非整数分子或除数舍入为最接近的整数，再计算结果。 除以 0 会抛出错误。 语法 
tupleIntDiv(tuple_num, tuple_div)
参数 返回值 返回由各商组成的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))
Response
(3, 2, 1)
使用 Decimal 类型
Query
SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))
Response
(2, 1, 0)

​
tupleIntDivByNumber

引入版本：v23.8.0 对由分子组成的 Tuple 按给定分母执行整数除法，并返回由商组成的 Tuple。 如果任一输入参数包含非整数元素，则会先将每个非整数分子或除数舍入为最接近的整数，再计算结果。 除以 0 时会抛出错误。 语法 
tupleIntDivByNumber(tuple_num, div)
参数 返回值 返回一个由商组成的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleIntDivByNumber((15, 10, 5), 5)
Response
(3, 2, 1)
使用 Decimal 类型
Query
SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)
Response
(2, 1, 0)

​
tupleIntDivOrZero

引入版本：v23.8.0 与 tupleIntDiv 类似，对一个由被除数组成的 Tuple 和一个由除数组成的 Tuple 执行整数除法，并返回由商组成的 Tuple。 如果发生除以 0，则返回的商为 0，而不是抛出异常。 如果任一 Tuple 包含非整数元素，则会先将每个非整数被除数或除数舍入为最接近的整数，再计算结果。 语法 
tupleIntDivOrZero(tuple_num, tuple_div)
参数 返回值 返回由商组成的 Tuple。对于除数为 0 的项，返回 0。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 除数为 0 时
Query
SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))
Response
(0, 0, 0)

​
tupleIntDivOrZeroByNumber

引入版本：v23.8.0 与 tupleIntDivByNumber 类似，它对一个由多个分子组成的元组和给定分母执行整数除法，并返回由各个商组成的元组。 当除数为零时，它不会抛出错误，而是返回商为零。 如果元组或 div 包含非整数元素，则会先将每个非整数分子或除数舍入到最接近的整数，再计算结果。 语法 
tupleIntDivOrZeroByNumber(tuple_num, div)
参数 返回值 返回由各个商组成的 Tuple；当除数为 0 时，对应的商为 0。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)
Response
(3, 2, 1)
除数为零时
Query
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)
Response
(0, 0, 0)

​
tupleMinus

引入版本：v21.11.0 计算两个大小相同的 Tuple 中对应元素之差。 语法 
tupleMinus(t1, t2)
别名: vectorDifference 参数 返回值 返回一个包含各项减法结果的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleMinus((1, 2), (2, 3))
Response
(-1, -1)

​
tupleModulo

引入版本：v23.8.0 返回一个元组，其中包含两个元组对应元素相除所得余数 (模) 组成的结果。 语法 
tupleModulo(tuple_num, tuple_mod)
参数 返回值 返回由各项除法余数组成的 Tuple。除数为零时会抛出错误。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleModulo((15, 10, 5), (5, 3, 2))
Response
(0, 1, 1)

​
tupleModuloByNumber

在 v23.8.0 中引入 返回一个 tuple，其中包含将给定除数分别对 tuple 中各元素进行求模 (取余) 运算后的结果。 语法 
tupleModuloByNumber(tuple_num, div)
参数 返回值 返回除法余数组成的 Tuple。除以零时会抛出错误。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleModuloByNumber((15, 10, 5), 2)
Response
(1, 0, 1)

​
tupleMultiply

引入版本：v21.11.0 计算两个大小相同的 Tuple 中对应元素相乘后的结果。 语法 
tupleMultiply(t1, t2)
参数 返回值 返回一个包含乘法运算结果的元组。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleMultiply((1, 2), (2, 3))
Response
(2, 6)

​
tupleMultiplyByNumber

自 v21.11.0 引入 返回一个 Tuple，其中所有元素都乘以一个数值。 语法 
tupleMultiplyByNumber(tuple, number)
参数 返回值 返回一个各元素均已相乘的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleMultiplyByNumber((1, 2), -2.1)
Response
(-2.1, -4.2)

​
tupleNames

引入版本：v24.8.0 将元组转换为列名数组。对于形如 Tuple(a T, b T, ...) 的元组，它会返回一个字符串数组，表示该元组中已命名列的名称。如果元组元素没有显式名称，则会使用它们的索引作为列名。 语法 
tupleNames(tuple)
参数
  • 无。
返回值 示例 典型示例
Query
SELECT tupleNames(tuple(1 as a, 2 as b))
Response
['a','b']

​
tupleNegate

Introduced in：v21.11.0 计算 Tuple 元素的相反数。 Syntax 
tupleNegate(t)
参数 返回值 返回一个包含取负结果的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tupleNegate((1, 2))
Response
(-1, -2)

​
tuplePlus

引入版本：v21.11.0 计算两个大小相同的元组中对应元素之和。 语法 
tuplePlus(t1, t2)
别名: vectorSum 参数 返回值 返回一个元组，其中包含输入元组中对应位置元素的和。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tuplePlus((1, 2), (2, 3))
Response
(3, 5)

​
tuplePositiveModuloByNumber

引入版本：v26.4.0 返回一个 Tuple 与给定除数做除法运算后所得正模 (余数) 组成的 Tuple。 与 tupleModuloByNumber 不同，结果始终为非负。 语法 
tuplePositiveModuloByNumber(tuple_num, div)
参数 返回值 返回一个由非负余数组成的 Tuple。Tuple((U)Int*) 或 Tuple(Float*) 或 Tuple(Decimal) 示例 基本用法
Query
SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)
Response
(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)) 示例 命名元组
Query
SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))
Response
[('1', 1593), ('2', 2502)]
未命名元组
Query
SELECT tupleToNameValuePairs(tuple(3, 2, 1))
Response
[('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 函数参数的示例：
Query
SELECT untuple(v6) FROM kv;
Response
┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘
使用 EXCEPT 表达式的示例：
Query
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;
Response
┌─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') │
└─────┴────┴────┴────┴───────────┘

​
距离函数

所有支持的函数均在距离函数文档中有详细说明。
最后修改于 2026年6月10日