tuple-functions
tuple
一个允许对多个列进行分组的函数。对于列 C1、C2、... 以及类型 T1、T2、...，如果列名唯一且可以视为未加引号的标识符，则返回包含这些列的命名 Tuple(C1 T1, C2 T2, ...) 类型元组，否则返回 Tuple(T1, T2, ...)。执行该函数没有成本。元组通常用作 IN 运算符参数的中间值，或用于创建 lambda 函数的形式参数列表。元组不能写入表中。
该函数实现了运算符 (x, y, ...)。
语法
tuple(x, y, ...)
tupleElement
一个允许从元组中获取列的函数。
如果第二个参数是数字 index，则它是列索引，从 1 开始。如果第二个参数是字符串 name，则它表示元素的名称。此外，我们可以提供第三个可选参数，以便当索引超出范围或名称不存在元素时，返回默认值而不是抛出异常。如果提供，第二个和第三个参数必须是常量。执行该函数没有成本。
该函数实现了运算符 x.index 和 x.name。
语法
tupleElement(tuple, index, [, default_value])
tupleElement(tuple, name, [, default_value])
untuple
在调用位置执行 tuple 元素的语法替换。
结果列的名称是特定于实现的，并且可能会更改。不要假设 untuple 之后特定的列名。
语法
untuple(x)
您可以使用 EXCEPT 表达式跳过查询结果中的列。
参数
x—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') │
└─────┴────┴────┴────┴───────────┘
另请参阅
tupleHammingDistance
返回两个相同大小的元组之间的 汉明距离。
语法
tupleHammingDistance(tuple1, tuple2)
参数
元组应具有相同类型的元素。
返回值
- 汉明距离。
结果类型根据输入元组中元素的数量，以与 算术函数相同的方式计算。
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 │
└───────┴────────┴────────┴────────┴────────┘
示例
查询
SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1)) AS HammingDistance;
结果
┌─HammingDistance─┐
│ 2 │
└─────────────────┘
可与 MinHash 函数一起用于检测半重复字符串
SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) AS HammingDistance
FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string);
结果
┌─HammingDistance─┐
│ 2 │
└─────────────────┘
tupleToNameValuePairs
将命名元组转换为 (名称，值) 对的数组。对于 Tuple(a T, b T, ..., c T) 返回 Array(Tuple(String, T), ...)，其中 Strings 表示元组的命名字段，T 是与这些名称关联的值。元组中的所有值都应具有相同的类型。
语法
tupleToNameValuePairs(tuple)
参数
tuple— 命名元组。 元组，任何类型的值。
返回值
示例
查询
CREATE TABLE tupletest (col Tuple(user_ID UInt64, session_ID UInt64)) ENGINE = Memory;
INSERT INTO tupletest VALUES (tuple( 100, 2502)), (tuple(1,100));
SELECT tupleToNameValuePairs(col) FROM tupletest;
结果
┌─tupleToNameValuePairs(col)────────────┐
│ [('user_ID',100),('session_ID',2502)] │
│ [('user_ID',1),('session_ID',100)] │
└───────────────────────────────────────┘
可以使用此函数将列转换为行
CREATE TABLE tupletest (col Tuple(CPU Float64, Memory Float64, Disk Float64)) ENGINE = Memory;
INSERT INTO tupletest VALUES(tuple(3.3, 5.5, 6.6));
SELECT arrayJoin(tupleToNameValuePairs(col)) FROM tupletest;
结果
┌─arrayJoin(tupleToNameValuePairs(col))─┐
│ ('CPU',3.3) │
│ ('Memory',5.5) │
│ ('Disk',6.6) │
└───────────────────────────────────────┘
如果将简单元组传递给函数，ClickHouse 会使用值的索引作为其名称
SELECT tupleToNameValuePairs(tuple(3, 2, 1));
结果
┌─tupleToNameValuePairs(tuple(3, 2, 1))─┐
│ [('1',3),('2',2),('3',1)] │
└───────────────────────────────────────┘
tupleNames
将元组转换为列名数组。对于 Tuple(a T, b T, ...) 形式的元组，它返回一个字符串数组，表示元组的命名列。如果元组元素没有显式名称，则将使用它们的索引作为列名。
语法
tupleNames(tuple)
参数
tuple— 命名元组。 元组，任何类型的值。
返回值
- 一个包含字符串的数组。
类型： Array(Tuple(String, ...))。
示例
查询
CREATE TABLE tupletest (col Tuple(user_ID UInt64, session_ID UInt64)) ENGINE = Memory;
INSERT INTO tupletest VALUES (tuple(1, 2));
SELECT tupleNames(col) FROM tupletest;
结果
┌─tupleNames(col)──────────┐
│ ['user_ID','session_ID'] │
└──────────────────────────┘
如果将简单元组传递给函数，ClickHouse 会使用列的索引作为其名称
SELECT tupleNames(tuple(3, 2, 1));
结果
┌─tupleNames((3, 2, 1))─┐
│ ['1','2','3'] │
└───────────────────────┘
tuplePlus
计算两个相同大小的元组中对应值的总和。
语法
tuplePlus(tuple1, tuple2)
别名：vectorSum。
参数
返回值
- 包含总和的元组。 元组。
示例
查询
SELECT tuplePlus((1, 2), (2, 3));
结果
┌─tuplePlus((1, 2), (2, 3))─┐
│ (3,5) │
└───────────────────────────┘
tupleMinus
计算两个相同大小的元组中对应值的差。
语法
tupleMinus(tuple1, tuple2)
别名：vectorDifference。
参数
返回值
- 包含减法结果的元组。 元组。
示例
查询
SELECT tupleMinus((1, 2), (2, 3));
结果
┌─tupleMinus((1, 2), (2, 3))─┐
│ (-1,-1) │
└────────────────────────────┘
tupleMultiply
计算两个相同大小的元组中对应值的乘积。
语法
tupleMultiply(tuple1, tuple2)
参数
返回值
- 包含乘积的元组。 元组。
示例
查询
SELECT tupleMultiply((1, 2), (2, 3));
结果
┌─tupleMultiply((1, 2), (2, 3))─┐
│ (2,6) │
└───────────────────────────────┘
tupleDivide
计算两个相同大小的元组中对应值的商。请注意，除以零将返回 inf。
语法
tupleDivide(tuple1, tuple2)
参数
返回值
- 包含除法结果的元组。 元组。
示例
查询
SELECT tupleDivide((1, 2), (2, 3));
结果
┌─tupleDivide((1, 2), (2, 3))─┐
│ (0.5,0.6666666666666666) │
└─────────────────────────────┘
tupleNegate
计算元组值的负数。
语法
tupleNegate(tuple)
参数
tuple— 元组。
返回值
- 包含取负结果的元组。 元组。
示例
查询
SELECT tupleNegate((1, 2));
结果
┌─tupleNegate((1, 2))─┐
│ (-1,-2) │
└─────────────────────┘
tupleMultiplyByNumber
返回一个元组，其中所有值都乘以一个数字。
语法
tupleMultiplyByNumber(tuple, number)
参数
返回值
- 包含乘积值的元组。 元组。
示例
查询
SELECT tupleMultiplyByNumber((1, 2), -2.1);
结果
┌─tupleMultiplyByNumber((1, 2), -2.1)─┐
│ (-2.1,-4.2) │
└─────────────────────────────────────┘
tupleDivideByNumber
返回一个元组，其中所有值都除以一个数字。请注意，除以零将返回 inf。
语法
tupleDivideByNumber(tuple, number)
参数
返回值
- 包含商值的元组。 元组。
示例
查询
SELECT tupleDivideByNumber((1, 2), 0.5);
结果
┌─tupleDivideByNumber((1, 2), 0.5)─┐
│ (2,4) │
└──────────────────────────────────┘
tupleConcat
组合作为参数传递的元组。
tupleConcat(tuples)
参数
tuples– Tuple 类型的任意数量的参数。
示例
SELECT tupleConcat((1, 2), (3, 4), (true, false)) AS res
┌─res──────────────────┐
│ (1,2,3,4,true,false) │
└──────────────────────┘
tupleIntDiv
对分子元组和分母元组进行整数除法，并返回商的元组。
语法
tupleIntDiv(tuple_num, tuple_div)
参数
返回值
tuple_num和tuple_div的商的元组。 Tuple，整数值。
实现细节
- 如果
tuple_num或tuple_div包含非整数值，则结果将通过对每个非整数分子或分母进行四舍五入到最近的整数来计算。 - 除以 0 将抛出错误。
示例
查询
SELECT tupleIntDiv((15, 10, 5), (5, 5, 5));
结果
┌─tupleIntDiv((15, 10, 5), (5, 5, 5))─┐
│ (3,2,1) │
└─────────────────────────────────────┘
查询
SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5));
结果
┌─tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))─┐
│ (2,1,0) │
└───────────────────────────────────────────┘
tupleIntDivOrZero
与 tupleIntDiv 一样，它对分子元组和分母元组进行整数除法，并返回商的元组。它不会对 0 除数抛出错误，而是将商返回为 0。
语法
tupleIntDivOrZero(tuple_num, tuple_div)
返回值
tuple_num和tuple_div的商的元组。 Tuple，整数值。- 对于除数为 0 的商返回 0。
实现细节
- 如果
tuple_num或tuple_div包含非整数值，则结果将通过对每个非整数分子或分母进行四舍五入到最近的整数来计算，如 tupleIntDiv 中所示。
示例
查询
SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0));
结果
┌─tupleIntDivOrZero((5, 10, 15), (0, 0, 0))─┐
│ (0,0,0) │
└───────────────────────────────────────────┘
tupleIntDivByNumber
对一个元组类型的分子进行整数除法，除数为给定的分母，并返回一个包含商的元组。
语法
tupleIntDivByNumber(tuple_num, div)
参数
返回值
tuple_num和div的商组成的元组。 元组，包含整数值。
实现细节
- 如果
tuple_num或div包含非整数值，则结果将通过对每个非整数分子或除数四舍五入到最近的整数来计算。 - 除以 0 将抛出错误。
示例
查询
SELECT tupleIntDivByNumber((15, 10, 5), 5);
结果
┌─tupleIntDivByNumber((15, 10, 5), 5)─┐
│ (3,2,1) │
└─────────────────────────────────────┘
查询
SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8);
结果
┌─tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)─┐
│ (2,1,0) │
└─────────────────────────────────────────────┘
tupleIntDivOrZeroByNumber
类似于 tupleIntDivByNumber，它对一个元组类型的分子进行整数除法，除数为给定的分母，并返回一个包含商的元组。对于除数为 0 的情况，它不会抛出错误，而是返回商为 0。
语法
tupleIntDivOrZeroByNumber(tuple_num, div)
参数
返回值
tuple_num和div的商组成的元组。 元组，包含整数值。- 对于除数为 0 的商返回 0。
实现细节
- 如果
tuple_num或div包含非整数值，则结果将通过对每个非整数分子或除数四舍五入到最近的整数来计算，与 tupleIntDivByNumber 一样。
示例
查询
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5);
结果
┌─tupleIntDivOrZeroByNumber((15, 10, 5), 5)─┐
│ (3,2,1) │
└───────────────────────────────────────────┘
查询
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)
结果
┌─tupleIntDivOrZeroByNumber((15, 10, 5), 0)─┐
│ (0,0,0) │
└───────────────────────────────────────────┘
tupleModulo
返回两个元组进行除法运算后的余数（模）组成的元组。
语法
tupleModulo(tuple_num, tuple_mod)
参数
返回值
tuple_num和tuple_div进行除法运算后的余数组成的元组。 元组，包含非零整数值。- 除以零将抛出错误。
示例
查询
SELECT tupleModulo((15, 10, 5), (5, 3, 2));
结果
┌─tupleModulo((15, 10, 5), (5, 3, 2))─┐
│ (0,1,1) │
└─────────────────────────────────────┘
tupleModuloByNumber
返回一个元组和给定除数进行除法运算后的余数（模）组成的元组。
语法
tupleModuloByNumber(tuple_num, div)
参数
返回值
tuple_num和div进行除法运算后的余数组成的元组。 元组，包含非零整数值。- 除以零将抛出错误。
示例
查询
SELECT tupleModuloByNumber((15, 10, 5), 2);
结果
┌─tupleModuloByNumber((15, 10, 5), 2)─┐
│ (1,0,1) │
└─────────────────────────────────────┘
flattenTuple
从嵌套命名元组 input 中返回一个扁平化的 output 元组。output 元组的元素是原始 input 元组的路径。例如：Tuple(a Int, Tuple(b Int, c Int)) -> Tuple(a Int, b Int, c Int)。flattenTuple 可用于将类型为 Object 的所有路径作为单独的列进行选择。
语法
flattenTuple(input)
参数
input: 要扁平化的嵌套命名元组。 元组。
返回值
output元组，其元素是原始input的路径。 元组。
示例
查询
CREATE TABLE t_flatten_tuple(t Tuple(t1 Nested(a UInt32, s String), b UInt32, t2 Tuple(k String, v UInt32))) ENGINE = Memory;
INSERT INTO t_flatten_tuple VALUES (([(1, 'a'), (2, 'b')], 3, ('c', 4)));
SELECT flattenTuple(t) FROM t_flatten_tuple;
结果
┌─flattenTuple(t)───────────┐
│ ([1,2],['a','b'],3,'c',4) │
└───────────────────────────┘
距离函数
所有支持的函数在 距离函数文档 中进行了描述。