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

> Documentation for Tuple functions

# Tuple functions

<Note>
  The documentation below is generated from the `system.functions` system table.
</Note>

{/*AUTOGENERATED_START*/}

<h2 id="dotProduct">
  dotProduct
</h2>

Introduced in: v21.11.0

Calculates the [dot product](https://en.wikipedia.org/wiki/Dot_product) (scalar product) of two vectors (tuples or arrays of equal size).
Returns the sum of the products of the corresponding elements.

**Syntax**

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

**Aliases**: `scalarProduct`

**Arguments**

* `vector1` — First vector. [`Array(T)`](/reference/data-types/array) or [`Tuple(T)`](/reference/data-types/tuple)
* `vector2` — Second vector. Must be the same size as the first vector. [`Array(T)`](/reference/data-types/array) or [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the dot product of the two vectors. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Examples**

**Basic usage**

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

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

<h2 id="flattenTuple">
  flattenTuple
</h2>

Introduced in: v22.6.0

Flattens a named and nested tuple.
The elements of the returned tuple are the paths of the input tuple.

**Syntax**

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

**Arguments**

* `input` — Named and nested tuple to flatten. [`Tuple(n1 T1[, n2 T2, ... ])`](/reference/data-types/tuple)

**Returned value**

Returns an output tuple whose elements are paths from the original input. [`Tuple(T)`](/reference/data-types/tuple)

**Examples**

**Usage example**

```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)    │
└────────────────┘
```

<h2 id="tuple">
  tuple
</h2>

Introduced in: v1.1.0

Returns a tuple by grouping input arguments.

For columns C1, C2, ... with the types T1, T2, ..., it returns a named Tuple(C1 T1, C2 T2, ...) type tuple containing these columns if their names are unique and can be treated as unquoted identifiers, otherwise a Tuple(T1, T2, ...) is returned. There is no cost to execute the function.
Tuples are normally used as intermediate values for an argument of IN operators, or for creating a list of formal parameters of lambda functions. Tuples can't be written to a table.

The function implements the operator `(x, y, ...)`.

**Syntax**

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

**Arguments**

* None.

**Returned value**

**Examples**

**typical**

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

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

<h2 id="tupleConcat">
  tupleConcat
</h2>

Introduced in: v23.8.0

Combines tuples passed as arguments.

**Syntax**

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

**Arguments**

* `tupleN` — Arbitrary number of arguments of Tuple type. [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple containing all elements from the input tuples. [`Tuple(T)`](/reference/data-types/tuple)

**Examples**

**Usage example**

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

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

<h2 id="tupleDivide">
  tupleDivide
</h2>

Introduced in: v21.11.0

Calculates the element-wise division of two or more tuples of the same size, applied left-to-right.

<Note>
  Division by zero will return `inf`.
</Note>

**Syntax**

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

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple containing the element-wise quotients. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Two tuples**

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

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

**Three tuples**

```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)
```

<h2 id="tupleDivideByNumber">
  tupleDivideByNumber
</h2>

Introduced in: v21.11.0

Returns a tuple with all elements divided by a number.

<Note>
  Division by zero will return `inf`.
</Note>

**Syntax**

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

**Arguments**

* `tuple` — Tuple to divide. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `number` — Divider. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Returned value**

Returns a tuple with divided elements. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

<h2 id="tupleElement">
  tupleElement
</h2>

Introduced in: v1.1.0

Extracts an element from a tuple by index or name.

For access by index, an 1-based numeric index is expected.
For access by name, the element name can be provided as a string (works only for named tuples).

Negative indexes are supported. In this case, the corresponding element is selected, numbered from the end. For example, `tuple.-1` is the last element in the tuple.

An optional third argument specifies a default value which is returned instead of throwing an exception when the accessed element does not exist.
All arguments must be constants.

This function has zero runtime cost and implements the operators `x.index` and `x.name`.

**Syntax**

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

**Arguments**

* `tuple` — A tuple or array of tuples. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(Tuple(T))`](/reference/data-types/array)
* `index` — Column index, starting from 1. [`const UInt8/16/32/64`](/reference/data-types/int-uint)
* `name` — Name of the element. [`const String`](/reference/data-types/string)
* `default_value` — Default value returned when index is out of bounds or element doesn't exist. [`Any`](/reference/data-types/index)

**Returned value**

Returns the element at the specified index or name. [`Any`](/reference/data-types/index)

**Examples**

**Index access**

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

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

**Negative indexing**

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

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

**Named tuple with table**

```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
```

**With default value**

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

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

**Operator syntax**

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

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

<h2 id="tupleHammingDistance">
  tupleHammingDistance
</h2>

Introduced in: v21.1.0

Returns the [Hamming Distance](https://en.wikipedia.org/wiki/Hamming_distance) between two tuples of the same size.

<Note>
  The result type is determined the same way it is for [Arithmetic functions](/reference/functions/regular-functions/arithmetic-functions), based on the number of elements in the input tuples.

  ```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>

**Syntax**

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

**Arguments**

* `t1` — First tuple. [`Tuple(*)`](/reference/data-types/tuple)
* `t2` — Second tuple. [`Tuple(*)`](/reference/data-types/tuple)

**Returned value**

Returns the Hamming distance. [`UInt8/16/32/64`](/reference/data-types/int-uint)

**Examples**

**Usage example**

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

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

**With MinHash to detect semi-duplicate strings**

```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
```

<h2 id="tupleIntDiv">
  tupleIntDiv
</h2>

Introduced in: v23.8.0

Performs element-wise integer division of two or more tuples of the same size, applied left-to-right. Returns a tuple of quotients.
If any tuple contains non-integer elements, the result is calculated by rounding to the nearest integer for each non-integer numerator or divisor.
Division by 0 causes an exception to be thrown.

**Syntax**

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

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple of integer quotients. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Two tuples**

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

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

**With decimals**

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

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

**Three tuples**

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

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

<h2 id="tupleIntDivByNumber">
  tupleIntDivByNumber
</h2>

Introduced in: v23.8.0

Performs integer division of a tuple of numerators by a given denominator, and returns a tuple of the quotients.
If either of the input parameters contain non-integer elements then the result is calculated by rounding to the nearest integer for each non-integer numerator or divisor.
An error will be thrown for division by 0.

**Syntax**

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

**Arguments**

* `tuple_num` — Tuple of numerator values. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `div` — The divisor value. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Returned value**

Returns a tuple of the quotients. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

**With decimals**

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

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

<h2 id="tupleIntDivOrZero">
  tupleIntDivOrZero
</h2>

Introduced in: v23.8.0

Like [`tupleIntDiv`](#tupleIntDiv), performs element-wise integer division of two or more tuples of the same size, applied left-to-right.
In case of division by 0, returns 0 for that element instead of throwing an exception.
If any tuple contains non-integer elements, the result is calculated by rounding to the nearest integer for each non-integer numerator or divisor.

**Syntax**

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

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple of integer quotients, with 0 for any element where the divisor is 0. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**With zero divisors**

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

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

**Three tuples**

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

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

<h2 id="tupleIntDivOrZeroByNumber">
  tupleIntDivOrZeroByNumber
</h2>

Introduced in: v23.8.0

Like [`tupleIntDivByNumber`](#tupleIntDivByNumber) it does integer division of a tuple of numerators by a given denominator, and returns a tuple of the quotients.
It does not throw an error for zero divisors, but rather returns the quotient as zero.
If either the tuple or div contain non-integer elements then the result is calculated by rounding to the nearest integer for each non-integer numerator or divisor.

**Syntax**

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

**Arguments**

* `tuple_num` — Tuple of numerator values. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `div` — The divisor value. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Returned value**

Returns a tuple of the quotients with `0` for quotients where the divisor is `0`. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

**With zero divisor**

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

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

<h2 id="tupleMinus">
  tupleMinus
</h2>

Introduced in: v21.11.0

Calculates the element-wise difference of two or more tuples of the same size, applied left-to-right.

**Syntax**

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

**Aliases**: `vectorDifference`

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple containing the element-wise differences. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Two tuples**

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

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

**Three tuples**

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

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

<h2 id="tupleModulo">
  tupleModulo
</h2>

Introduced in: v23.8.0

Returns a tuple of element-wise remainders from dividing two or more tuples of the same size, applied left-to-right.

**Syntax**

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

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple of element-wise remainders. An exception is thrown for division by zero. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Two tuples**

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

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

**Three tuples**

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

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

<h2 id="tupleModuloByNumber">
  tupleModuloByNumber
</h2>

Introduced in: v23.8.0

Returns a tuple of the moduli (remainders) of division operations of a tuple and a given divisor.

**Syntax**

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

**Arguments**

* `tuple_num` — Tuple of numerator elements. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `div` — The divisor value. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Returned value**

Returns tuple of the remainders of division. An error is thrown for division by zero. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

<h2 id="tupleMultiply">
  tupleMultiply
</h2>

Introduced in: v21.11.0

Calculates the element-wise product of two or more tuples of the same size.

**Syntax**

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

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple containing the element-wise products. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Two tuples**

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

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

**Three tuples**

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

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

<h2 id="tupleMultiplyByNumber">
  tupleMultiplyByNumber
</h2>

Introduced in: v21.11.0

Returns a tuple with all elements multiplied by a number.

**Syntax**

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

**Arguments**

* `tuple` — Tuple to multiply. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `number` — Multiplier. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Returned value**

Returns a tuple with multiplied elements. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

<h2 id="tupleNames">
  tupleNames
</h2>

Introduced in: v24.8.0

Converts a tuple into an array of column names. For a tuple in the form `Tuple(a T, b T, ...)`, it returns an array of strings representing the named columns of the tuple. If the tuple elements do not have explicit names, their indices will be used as the column names instead.

**Syntax**

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

**Arguments**

* None.

**Returned value**

**Examples**

**typical**

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

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

<h2 id="tupleNegate">
  tupleNegate
</h2>

Introduced in: v21.11.0

Calculates the negation of the tuple elements.

**Syntax**

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

**Arguments**

* `t` — Tuple to negate. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple with the result of negation. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

<h2 id="tuplePlus">
  tuplePlus
</h2>

Introduced in: v21.11.0

Calculates the element-wise sum of two or more tuples of the same size.

**Syntax**

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

**Aliases**: `vectorSum`

**Arguments**

* `t1` — First input tuple. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `t2, ..., tN` — One or more further input tuples. All tuples must have the same size. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Returned value**

Returns a tuple containing the element-wise sums. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Two tuples**

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

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

**Three tuples**

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

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

<h2 id="tuplePositiveModuloByNumber">
  tuplePositiveModuloByNumber
</h2>

Introduced in: v26.4.0

Returns a tuple of the positive moduli (remainders) of division operations of a tuple and a given divisor.
Unlike tupleModuloByNumber, the result is always non-negative.

**Syntax**

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

**Arguments**

* `tuple_num` — Tuple of numerator values. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)
* `div` — The divisor value. [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Returned value**

Returns a tuple of the non-negative remainders. [`Tuple((U)Int*)`](/reference/data-types/tuple) or [`Tuple(Float*)`](/reference/data-types/tuple) or [`Tuple(Decimal)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

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

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

<h2 id="tupleToNameValuePairs">
  tupleToNameValuePairs
</h2>

Introduced in: v21.9.0

Converts a tuple to an array of `(name, value)` pairs.
For example, tuple `Tuple(n1 T1, n2 T2, ...)` is converted to `Array(Tuple('n1', T1), Tuple('n2', T2), ...)`.
All values in the tuple must be of the same type.

**Syntax**

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

**Arguments**

* `tuple` — Named tuple with any types of values. [`Tuple(n1 T1[, n2 T2, ...])`](/reference/data-types/tuple)

**Returned value**

Returns an array with `(name, value)` pairs. [`Array(Tuple(String, T))`](/reference/data-types/array)

**Examples**

**Named tuple**

```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)]
```

**Unnamed tuple**

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

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

<h2 id="untuple">
  untuple
</h2>

Performs syntactic substitution of [tuple](/reference/data-types/tuple) elements in the call location.

The names of the result columns are implementation-specific and subject to change. Do not assume specific column names after `untuple`.

**Syntax**

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

You can use the `EXCEPT` expression to skip columns as a result of the query.

**Arguments**

* `x` — A `tuple` function, column, or tuple of elements. [Tuple](/reference/data-types/tuple).

**Returned value**

* None.

**Examples**

Input table:

```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') │
└─────┴────┴────┴────┴────┴────┴───────────┘
```

Example of using a `Tuple`-type column as the `untuple` function parameter:

```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    │
└───────┴───────┘
```

Example of using an `EXCEPT` expression:

```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') │
└─────┴────┴────┴────┴───────────┘
```

<h2 id="distance-functions">
  Distance functions
</h2>

All supported functions are described in [distance functions documentation](/reference/functions/regular-functions/distance-functions).