> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Tuple 函数文档

# Tuple 函数

<Note>
  以下文档由 `system.functions` 系统表自动生成。
</Note>

{/*AUTOGENERATED_START*/}

<div id="dotProduct">
  ## dotProduct
</div>

引入版本：v21.11.0

计算两个向量 (大小相等的元组或数组) 的[点积](https://en.wikipedia.org/wiki/Dot_product) (标量积) 。
返回对应元素乘积的总和。

**语法**

```sql theme={null}
dotProduct(vector1, vector2)
```

**别名**: `scalarProduct`

**参数**

* `vector1` — 第一个向量。[`Array(T)`](/zh/reference/data-types/array) 或 [`Tuple(T)`](/zh/reference/data-types/tuple)
* `vector2` — 第二个向量。其长度必须与第一个向量相同。[`Array(T)`](/zh/reference/data-types/array) 或 [`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回两个向量的点积。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT dotProduct((1, 2), (3, 4))
```

```response title=Response theme={null}
11
```

<div id="flattenTuple">
  ## flattenTuple
</div>

引入版本：v22.6.0

将具名的嵌套 Tuple 展平。
返回的 Tuple 的元素为输入 Tuple 的路径。

**语法**

```sql theme={null}
flattenTuple(input)
```

**参数**

* `input` — 要展平的带名称嵌套元组。[`Tuple(n1 T1[, n2 T2, ... ])`](/zh/reference/data-types/tuple)

**返回值**

返回一个输出元组，其元素为原始输入中的路径。[`Tuple(T)`](/zh/reference/data-types/tuple)

**示例**

**使用示例**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─flattenTuple(t)┐
│ (3, 'c', 4)    │
└────────────────┘
```

<div id="tuple">
  ## tuple
</div>

首次引入于：v1.1.0

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

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

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

**语法**

```sql theme={null}
tuple([t1[, t2[ ...]])
```

**参数**

* 无。

**返回值**

**示例**

**典型用法**

```sql title=Query theme={null}
SELECT tuple(1, 2)
```

```response title=Response theme={null}
(1,2)
```

<div id="tupleConcat">
  ## tupleConcat
</div>

引入版本：v23.8.0

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

**语法**

```sql theme={null}
tupleConcat(tuple1[, tuple2, [...]])
```

**参数**

* `tupleN` — 任意数量的 Tuple 类型的参数。[`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回一个包含所有输入 Tuple 元素的 Tuple。[`Tuple(T)`](/zh/reference/data-types/tuple)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT tupleConcat((1, 2), ('a',), (true, false))
```

```response title=Response theme={null}
(1, 2, 'a', true, false)
```

<div id="tupleDivide">
  ## tupleDivide
</div>

引入版本：v21.11.0

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

<Note>
  除以零将返回 `inf`。
</Note>

**语法**

```sql theme={null}
tupleDivide(t1, t2[, tN, ...])
```

**参数**

* `t1` — 第一个输入 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 一个或多个额外的输入 Tuple。所有 Tuple 的大小必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个包含逐元素相除所得商的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**两个 Tuple**

```sql title=Query theme={null}
SELECT tupleDivide((1, 2), (2, 3))
```

```response title=Response theme={null}
(0.5, 0.6666666666666666)
```

**三个Tuple**

```sql title=Query theme={null}
SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))
```

```response title=Response theme={null}
(10, 5)
```

<div id="tupleDivideByNumber">
  ## tupleDivideByNumber
</div>

首次引入版本：v21.11.0

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

<Note>
  除以零将返回 `inf`。
</Note>

**语法**

```sql theme={null}
tupleDivideByNumber(tuple, number)
```

**参数**

* `tuple` — 待相除的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `number` — 除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回一个各元素均已相除的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tupleDivideByNumber((1, 2), 0.5)
```

```response title=Response theme={null}
(2, 4)
```

<div id="tupleElement">
  ## tupleElement
</div>

Introduced in: v1.1.0

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

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

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

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

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

**Syntax**

```sql theme={null}
tupleElement(tuple, index|name[, default_value])
```

**参数**

* `tuple` — Tuple或Tuple数组。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(Tuple(T))`](/zh/reference/data-types/array)
* `index` — 列索引，从 1 开始计数。[`const UInt8/16/32/64`](/zh/reference/data-types/int-uint)
* `name` — 元素名称。[`const String`](/zh/reference/data-types/string)
* `default_value` — 当索引越界或元素不存在时返回的默认值。[`Any`](/zh/reference/data-types/index)

**返回值**

返回指定索引或名称对应的元素。[`Any`](/zh/reference/data-types/index)

**示例**

**索引访问**

```sql title=Query theme={null}
SELECT tupleElement((1, 'hello'), 2)
```

```response title=Response theme={null}
hello
```

**负索引**

```sql title=Query theme={null}
SELECT tupleElement((1, 'hello'), -1)
```

```response title=Response theme={null}
hello
```

**带表的命名Tuple**

```sql title=Query theme={null}
CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;
```

```response title=Response theme={null}
Alice
```

**带默认值**

```sql title=Query theme={null}
SELECT tupleElement((1, 2), 5, 'not_found')
```

```response title=Response theme={null}
not_found
```

**运算符语法**

```sql title=Query theme={null}
SELECT (1, 'hello').2
```

```response title=Response theme={null}
hello
```

<div id="tupleHammingDistance">
  ## tupleHammingDistance
</div>

自 v21.1.0 引入

返回两个大小相同的 Tuple 之间的 [Hamming 距离](https://en.wikipedia.org/wiki/Hamming_distance)。

<Note>
  结果类型的确定方式与 [算术函数](/zh/reference/functions/regular-functions/arithmetic-functions) 相同，具体取决于输入 Tuple 中的元素数量。

  ```sql theme={null}
  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
  ```

  ```text theme={null}
  ┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
  │ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
  └───────┴────────┴────────┴────────┴────────┘
  ```
</Note>

**语法**

```sql theme={null}
tupleHammingDistance(t1, t2)
```

**参数**

* `t1` — 第一个 Tuple。[`Tuple(*)`](/zh/reference/data-types/tuple)
* `t2` — 第二个 Tuple。[`Tuple(*)`](/zh/reference/data-types/tuple)

**返回值**

返回 Hamming 距离。[`UInt8/16/32/64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))
```

```response title=Response theme={null}
2
```

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

```sql title=Query theme={null}
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 title=Response theme={null}
2
```

<div id="tupleIntDiv">
  ## tupleIntDiv
</div>

引入版本：v23.8.0

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

**语法**

```sql theme={null}
tupleIntDiv(t1, t2[, tN, ...])
```

**参数**

* `t1` — 第一个输入 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 一个或多个额外的输入 Tuple。所有 Tuple 的大小必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个由整数商组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**两个 Tuple**

```sql title=Query theme={null}
SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))
```

```response title=Response theme={null}
(3, 2, 1)
```

**使用 Decimal**

```sql title=Query theme={null}
SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))
```

```response title=Response theme={null}
(2, 1, 0)
```

**三个Tuple**

```sql title=Query theme={null}
SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))
```

```response title=Response theme={null}
(15, 5)
```

<div id="tupleIntDivByNumber">
  ## tupleIntDivByNumber
</div>

引入版本：v23.8.0

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

**语法**

```sql theme={null}
tupleIntDivByNumber(tuple_num, div)
```

**参数**

* `tuple_num` — 由分子值组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `div` — 除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回一个由商组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tupleIntDivByNumber((15, 10, 5), 5)
```

```response title=Response theme={null}
(3, 2, 1)
```

**使用 Decimal 类型**

```sql title=Query theme={null}
SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)
```

```response title=Response theme={null}
(2, 1, 0)
```

<div id="tupleIntDivOrZero">
  ## tupleIntDivOrZero
</div>

引入版本：v23.8.0

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

**语法**

```sql theme={null}
tupleIntDivOrZero(t1, t2[, tN, ...])
```

**参数**

* `t1` — 第一个输入 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 一个或多个后续输入 Tuple。所有 Tuple 的大小必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个由整数商组成的 Tuple。对于除数为 0 的元素，返回 0。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**除数为 0 时**

```sql title=Query theme={null}
SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))
```

```response title=Response theme={null}
(0, 0, 0)
```

**三个元组**

```sql title=Query theme={null}
SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))
```

```response title=Response theme={null}
(15, 5)
```

<div id="tupleIntDivOrZeroByNumber">
  ## tupleIntDivOrZeroByNumber
</div>

引入版本：v23.8.0

与 [`tupleIntDivByNumber`](#tupleIntDivByNumber) 类似，它对一个由多个分子组成的元组和给定分母执行整数除法，并返回由各个商组成的元组。
当除数为零时，它不会抛出错误，而是返回商为零。
如果元组或 `div` 包含非整数元素，则会先将每个非整数分子或除数舍入到最接近的整数，再计算结果。

**语法**

```sql theme={null}
tupleIntDivOrZeroByNumber(tuple_num, div)
```

**参数**

* `tuple_num` — 由分子值组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `div` — 除数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回由各个商组成的 Tuple；当除数为 `0` 时，对应的商为 `0`。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)
```

```response title=Response theme={null}
(3, 2, 1)
```

**除数为零时**

```sql title=Query theme={null}
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)
```

```response title=Response theme={null}
(0, 0, 0)
```

<div id="tupleMinus">
  ## tupleMinus
</div>

引入版本：v21.11.0

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

**语法**

```sql theme={null}
tupleMinus(t1, t2[, tN, ...])
```

**别名**: `vectorDifference`

**参数**

* `t1` — 第一个输入 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 一个或多个后续输入 Tuple。所有 Tuple 的大小都必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个包含逐元素差值的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**两个 Tuple**

```sql title=Query theme={null}
SELECT tupleMinus((1, 2), (2, 3))
```

```response title=Response theme={null}
(-1, -1)
```

**三个元组**

```sql title=Query theme={null}
SELECT tupleMinus((10, 10), (3, 4), (2, 1))
```

```response title=Response theme={null}
(5, 5)
```

<div id="tupleModulo">
  ## tupleModulo
</div>

引入版本：v23.8.0

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

**语法**

```sql theme={null}
tupleModulo(t1, t2[, tN, ...])
```

**参数**

* `t1` — 第一个输入 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 另外一个或多个输入 Tuple。所有 Tuple 的大小必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个按元素求余后得到的 Tuple。除以零时会抛出异常。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**两个 Tuple**

```sql title=Query theme={null}
SELECT tupleModulo((15, 10, 5), (5, 3, 2))
```

```response title=Response theme={null}
(0, 1, 1)
```

**三个元组**

```sql title=Query theme={null}
SELECT tupleModulo((10, 20), (7, 9), (3, 5))
```

```response title=Response theme={null}
(0, 2)
```

<div id="tupleModuloByNumber">
  ## tupleModuloByNumber
</div>

在 v23.8.0 中引入

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

**语法**

```sql theme={null}
tupleModuloByNumber(tuple_num, div)
```

**参数**

* `tuple_num` — 由分子元素组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `div` — 除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回除法余数组成的 Tuple。除以零时会抛出错误。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tupleModuloByNumber((15, 10, 5), 2)
```

```response title=Response theme={null}
(1, 0, 1)
```

<div id="tupleMultiply">
  ## tupleMultiply
</div>

首次引入版本：v21.11.0

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

**语法**

```sql theme={null}
tupleMultiply(t1, t2[, tN, ...])
```

**参数**

* `t1` — 第一个输入 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 一个或多个其他输入 Tuple。所有 Tuple 的大小必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个包含对应元素乘积的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**两个 Tuple**

```sql title=Query theme={null}
SELECT tupleMultiply((1, 2), (2, 3))
```

```response title=Response theme={null}
(2, 6)
```

**三个 Tuple**

```sql title=Query theme={null}
SELECT tupleMultiply((1, 2), (2, 3), (1, 2))
```

```response title=Response theme={null}
(2, 12)
```

<div id="tupleMultiplyByNumber">
  ## tupleMultiplyByNumber
</div>

自 v21.11.0 引入

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

**语法**

```sql theme={null}
tupleMultiplyByNumber(tuple, number)
```

**参数**

* `tuple` — 要相乘的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `number` — 乘数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回一个各元素均已相乘的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tupleMultiplyByNumber((1, 2), -2.1)
```

```response title=Response theme={null}
(-2.1, -4.2)
```

<div id="tupleNames">
  ## tupleNames
</div>

引入版本：v24.8.0

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

**语法**

```sql theme={null}
tupleNames(tuple)
```

**参数**

* 无。

**返回值**

**示例**

**典型示例**

```sql title=Query theme={null}
SELECT tupleNames(tuple(1 as a, 2 as b))
```

```response title=Response theme={null}
['a','b']
```

<div id="tupleNegate">
  ## tupleNegate
</div>

Introduced in：v21.11.0

计算 Tuple 元素的相反数。

**Syntax**

```sql theme={null}
tupleNegate(t)
```

**参数**

* `t` — 要取负的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个包含取负结果的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tupleNegate((1, 2))
```

```response title=Response theme={null}
(-1, -2)
```

<div id="tuplePlus">
  ## tuplePlus
</div>

引入版本：v21.11.0

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

**语法**

```sql theme={null}
tuplePlus(t1, t2[, tN, ...])
```

**别名**：`vectorSum`

**参数**

* `t1` — 第一个输入Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `t2, ..., tN` — 一个或多个额外的输入Tuple。所有Tuple的大小必须相同。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**返回值**

返回一个包含各元素求和结果的Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**两个Tuple**

```sql title=Query theme={null}
SELECT tuplePlus((1, 2), (2, 3))
```

```response title=Response theme={null}
(3, 5)
```

**三个Tuple**

```sql title=Query theme={null}
SELECT tuplePlus((1, 2), (2, 3), (3, 4))
```

```response title=Response theme={null}
(6, 9)
```

<div id="tuplePositiveModuloByNumber">
  ## tuplePositiveModuloByNumber
</div>

引入版本：v26.4.0

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

**语法**

```sql theme={null}
tuplePositiveModuloByNumber(tuple_num, div)
```

**参数**

* `tuple_num` — 由分子值组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)
* `div` — 除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回一个由非负余数组成的 Tuple。[`Tuple((U)Int*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Float*)`](/zh/reference/data-types/tuple) 或 [`Tuple(Decimal)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)
```

```response title=Response theme={null}
(1, 0, 1)
```

<div id="tupleToNameValuePairs">
  ## tupleToNameValuePairs
</div>

引入版本：v21.9.0

将 Tuple 转换为由 `(name, value)` 对组成的 Array。
例如，Tuple `Tuple(n1 T1, n2 T2, ...)` 会转换为 `Array(Tuple('n1', T1), Tuple('n2', T2), ...)`。
Tuple 中的所有值都必须是相同的类型。

**语法**

```sql theme={null}
tupleToNameValuePairs(tuple)
```

**参数**

* `tuple` — 包含任意类型值的命名元组。[`Tuple(n1 T1[, n2 T2, ...])`](/zh/reference/data-types/tuple)

**返回值**

返回一个由 `(name, value)` 对组成的数组。[`Array(Tuple(String, T))`](/zh/reference/data-types/array)

**示例**

**命名元组**

```sql title=Query theme={null}
SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))
```

```response title=Response theme={null}
[('1', 1593), ('2', 2502)]
```

**未命名元组**

```sql title=Query theme={null}
SELECT tupleToNameValuePairs(tuple(3, 2, 1))
```

```response title=Response theme={null}
[('1', 3), ('2', 2), ('3', 1)]
```

<div id="untuple">
  ## untuple
</div>

在调用位置对 [tuple](/zh/reference/data-types/tuple) 的元素执行语法替换。

结果列名取决于具体实现，并且可能发生变化。不要在 `untuple` 之后假定特定的列名。

**语法**

```sql theme={null}
untuple(x)
```

你可以使用 `EXCEPT` 表达式，从查询结果中排除某些列。

**参数**

* `x` — `tuple` 函数、列，或元素组成的元组。[Tuple](/zh/reference/data-types/tuple)。

**返回值**

* 无。

**示例**

输入表：

```text theme={null}
┌─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` 函数参数的示例：

```sql title="Query" theme={null}
SELECT untuple(v6) FROM kv;
```

```text title="Response" theme={null}
┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘
```

使用 `EXCEPT` 表达式的示例：

```sql title="Query" theme={null}
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;
```

```text title="Response" theme={null}
┌─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') │
└─────┴────┴────┴────┴───────────┘
```

<div id="distance-functions">
  ## 距离函数
</div>

所有支持的函数均在[距离函数文档](/zh/reference/functions/regular-functions/distance-functions)中有详细说明。