Tuple functions

**Syntax**

```
tupleMinus(t1, t2)
```

**Aliases**: `vectorDifference`

**Arguments**

- `t1` — First tuple. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)
- `t2` — Second tuple. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)

**Returned value**

Returns a tuple containing the results of the subtractions. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)

**Examples**

**Basic usage**

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

```
(-1, -1)
```

## tupleModulo[​](#tupleModulo "Direct link to tupleModulo")

Introduced in: v23.8.0

Returns a tuple of the remainders (moduli) of division operations of two tuples.

**Syntax**

```
tupleModulo(tuple_num, tuple_mod)
```

**Arguments**

- `tuple_num` — Tuple of numerator values. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)
- `tuple_mod` — Tuple of modulus values. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT tupleModulo((15, 10, 5), (5, 3, 2))
```

```
(0, 1, 1)
```

## tupleModuloByNumber[​](#tupleModuloByNumber "Direct link to tupleModuloByNumber")

Introduced in: v23.8.0

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

**Syntax**

```
tupleModuloByNumber(tuple_num, div)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT tupleModuloByNumber((15, 10, 5), 2)
```

```
(1, 0, 1)
```

## tupleMultiply[​](#tupleMultiply "Direct link to tupleMultiply")

Introduced in: v21.11.0

Calculates the multiplication of corresponding elements of two tuples of the same size.

**Syntax**

```
tupleMultiply(t1, t2)
```

**Arguments**

- `t1` — First tuple. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)
- `t2` — Second tuple. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT tupleMultiply((1, 2), (2, 3))
```

```
(2, 6)
```

## tupleMultiplyByNumber[​](#tupleMultiplyByNumber "Direct link to tupleMultiplyByNumber")

Introduced in: v21.11.0

Returns a tuple with all elements multiplied by a number.

**Syntax**

```
tupleMultiplyByNumber(tuple, number)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT tupleMultiplyByNumber((1, 2), -2.1)
```

```
(-2.1, -4.2)
```

## tupleNames[​](#tupleNames "Direct link to tupleNames")

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

```
tupleNames(tuple)
```

**Arguments**

- None.

**Returned value**

**Examples**

**typical**

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

```
['a','b']
```

## tupleNegate[​](#tupleNegate "Direct link to tupleNegate")

Introduced in: v21.11.0

Calculates the negation of the tuple elements.

**Syntax**

```
tupleNegate(t)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT tupleNegate((1, 2))
```

```
(-1, -2)
```

## tuplePlus[​](#tuplePlus "Direct link to tuplePlus")

Introduced in: v21.11.0

Calculates the sum of corresponding elements of two tuples of the same size.

**Syntax**

```
tuplePlus(t1, t2)
```

**Aliases**: `vectorSum`

**Arguments**

- `t1` — First tuple. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)
- `t2` — Second tuple. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)

**Returned value**

Returns a tuple containing the sums of corresponding input tuple arguments. [`Tuple((U)Int*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Float*)`](/docs/sql-reference/data-types/tuple) or [`Tuple(Decimal)`](/docs/sql-reference/data-types/tuple)

**Examples**

**Basic usage**

```
SELECT tuplePlus((1, 2), (2, 3))
```

```
(3, 5)
```

## tupleToNameValuePairs[​](#tupleToNameValuePairs "Direct link to tupleToNameValuePairs")

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

```
tupleToNameValuePairs(tuple)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Named tuple**

```
SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))
```

```
[('1', 1593), ('2', 2502)]
```

**Unnamed tuple**

```
SELECT tupleToNameValuePairs(tuple(3, 2, 1))
```

```
[('1', 3), ('2', 2), ('3', 1)]
```

## untuple[​](#untuple "Direct link to untuple")