---
title: Tuple Functions reference
meta:
    description: Functions for working with tuples.
headingMaxLevels: 2
---

# Tuple functions

The following functions are available for working with tuples.

## tuple

Creates a tuple from a list of values. This function groups multiple expressions or column values into a single tuple, which can be named or unnamed.

### Syntax

```sql
tuple(x, y, ...)
```

### Arguments

- `x, y, ...`: Any type. The values to include in the tuple.

### Returns

A tuple containing the input values. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tuple(1, 'hello', 3.14) AS my_tuple
```

Result:

```result
┌─my_tuple───────────┐
│ (1,'hello',3.14)   │
└────────────────────┘
```

## tupleElement

Extracts a specific element from a tuple by its 1-based index or by its name. An optional default value can be provided to avoid errors if the element is not found.

### Syntax

```sql
tupleElement(tuple, index [, default_value])
tupleElement(tuple, name [, default_value])
```

### Arguments

- `tuple`: [Tuple](../data-types/tuple). The tuple to extract an element from.
- `index`: [UInt](../data-types/int-uint). The 1-based index of the element to retrieve.
- `name`: [String](../data-types/string). The name of the element to retrieve (for named tuples).
- `default_value`: Any. An optional value to return if the element is not found.

### Returns

The value of the specified element. Type of the element.

### Example

```sql
SELECT
    tupleElement(('apple', 'banana', 'cherry'), 2) AS by_index,
    tupleElement((1 AS id, 'Alice' AS name), 'name') AS by_name,
    tupleElement(('a', 'b'), 3, 'default') AS with_default
```

Result:

```result
┌─by_index─┬─by_name─┬─with_default─┐
│ banana   │ Alice   │ default      │
└──────────┴─────────┴──────────────┘
```

## untuple

Expands the elements of a tuple into separate columns in the query result. The resulting column names are generated automatically and should not be relied upon for stability.

### Syntax

```sql
untuple(x)
```

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

### Arguments

- `x`: [Tuple](../data-types/tuple). The tuple to expand.

### Returns

None (syntactic substitution, effectively returns multiple columns).

### Examples

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

```sql
-- Assuming a Data Source `kv` with a column `v6` of type Tuple(Int, String)
SELECT untuple(v6) FROM kv LIMIT 1
```

Result:

```result
┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
└───────┴───────┘
```

Example of using an `EXCEPT` expression:

```sql
-- Assuming a Data Source `kv` with columns key, v1, v2, v3, v4, v5, v6
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv LIMIT 1
```

Result:

```result
┌─key─┬─v1─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 30 │ 15 │ (33,'ab') │
└─────┴────┴────┴────┴───────────┘
```

## tupleHammingDistance

Calculates the Hamming distance between two tuples of identical structure and size. The Hamming distance is the number of positions at which the corresponding elements are different.

### Syntax

```sql
tupleHammingDistance(tuple1, tuple2)
```

### Arguments

- `tuple1`: [Tuple](../data-types/tuple). The first tuple.
- `tuple2`: [Tuple](../data-types/tuple). The second tuple.

Tuples should have the same type of the elements.

### Returns

The Hamming distance as an integer. [UInt8](../data-types/int-uint), [UInt16](../data-types/int-uint), [UInt32](../data-types/int-uint), or [UInt64](../data-types/int-uint) depending on tuple size.

{% callout type="info" %}
The result type is calculated the same way it's for Arithmetic functions, based on the number of elements in the input tuples.
{% /callout %}

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

Result:

```result
┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
│ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
└───────┴────────┴────────┴────────┴────────┘
```

### Example

```sql
SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1)) AS HammingDistance
```

Result:

```result
┌─HammingDistance─┐
│               2 │
└─────────────────┘
```

Can be used with MinHash functions for detection of semi-duplicate strings:

```sql
SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) AS HammingDistance
FROM (SELECT 'Bazinga is a column-oriented database management system for online analytical processing of queries.' AS string)
```

Result:

```result
┌─HammingDistance─┐
│               2 │
└─────────────────┘
```

## tupleToNameValuePairs

Converts a named tuple into an array of `(name, value)` pairs. Each pair consists of the field's name as a string and its corresponding value. If the tuple is unnamed, element indices are used as names.

### Syntax

```sql
tupleToNameValuePairs(tuple)
```

### Arguments

- `tuple`: [Tuple](../data-types/tuple). The tuple to convert.

### Returns

An array of `Tuple(String, Any)` pairs. [Array](../data-types/array)([Tuple](../data-types/tuple)([String](../data-types/string), ...)).

### Example

```sql
SELECT tupleToNameValuePairs(col) FROM
(select (c1,c2)::Tuple(user_ID UInt64, session_ID UInt64) as col from values((100, 2502), (1, 100)))
```

Result:

```result
┌─tupleToNameValuePairs(col)────────────┐
│ [('user_ID',100),('session_ID',2502)] │
│ [('user_ID',1),('session_ID',100)]    │
└───────────────────────────────────────┘
```

It is possible to transform columns to rows using this function:

```sql
SELECT arrayJoin(tupleToNameValuePairs(col)) FROM
(select (c1,c2,c3)::Tuple(CPU Float64, Memory Float64, Disk Float64) as col from values((tuple(3.3, 5.5, 6.6))))
```

Result:

```result
┌─arrayJoin(tupleToNameValuePairs(col))─┐
│ ('CPU',3.3)                           │
│ ('Memory',5.5)                        │
│ ('Disk',6.6)                          │
└───────────────────────────────────────┘
```

If you pass a simple tuple to the function, Tinybird uses the indexes of the values as their names:

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

Result:

```result
┌─tupleToNameValuePairs(tuple(3, 2, 1))─┐
│ [('1',3),('2',2),('3',1)]             │
└───────────────────────────────────────┘
```

## tupleNames

Extracts the names of elements from a tuple and returns them as an array of strings. For unnamed tuples, it uses the 1-based indices as names.

### Syntax

```sql
tupleNames(tuple)
```

### Arguments

- `tuple`: [Tuple](../data-types/tuple). The tuple to extract names from.

### Returns

An array of strings representing the element names. [Array](../data-types/array)([String](../data-types/string)).

### Example

```sql
SELECT tupleNames(col) FROM (select (c1,c2)::Tuple(user_ID UInt64, session_ID UInt64) as col from values((1, 2)))
```

Result:

```result
┌─tupleNames(col)──────────┐
│ ['user_ID','session_ID'] │
└──────────────────────────┘
```

If you pass a simple tuple to the function, Tinybird uses the indexes of the columns as their names:

```sql
SELECT tupleNames(tuple(3, 2, 1))
```

Result:

```result
┌─tupleNames((3, 2, 1))─┐
│ ['1','2','3']         │
└───────────────────────┘
```

## tuplePlus

Adds corresponding elements of two tuples of the same size, returning a new tuple with the sums.

### Syntax

```sql
tuplePlus(tuple1, tuple2)
```

Alias: `vectorSum`.

### Arguments

- `tuple1`: [Tuple](../data-types/tuple). The first tuple.
- `tuple2`: [Tuple](../data-types/tuple). The second tuple.

### Returns

A tuple containing the sums of corresponding elements. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tuplePlus((1, 2), (2, 3))─┐
│ (3,5)                     │
└───────────────────────────┘
```

## tupleMinus

Subtracts corresponding elements of the second tuple from the first tuple, returning a new tuple with the differences. Both tuples must be of the same size.

### Syntax

```sql
tupleMinus(tuple1, tuple2)
```

Alias: `vectorDifference`.

### Arguments

- `tuple1`: [Tuple](../data-types/tuple). The first tuple.
- `tuple2`: [Tuple](../data-types/tuple). The second tuple.

### Returns

A tuple containing the differences of corresponding elements. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tupleMinus((1, 2), (2, 3))─┐
│ (-1,-1)                    │
└────────────────────────────┘
```

## tupleMultiply

Multiplies corresponding elements of two tuples of the same size, returning a new tuple with the products.

### Syntax

```sql
tupleMultiply(tuple1, tuple2)
```

### Arguments

- `tuple1`: [Tuple](../data-types/tuple). The first tuple.
- `tuple2`: [Tuple](../data-types/tuple). The second tuple.

### Returns

A tuple containing the products of corresponding elements. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tupleMultiply((1, 2), (2, 3))─┐
│ (2,6)                         │
└───────────────────────────────┘
```

## tupleDivide

Divides corresponding elements of the first tuple by those of the second tuple, returning a new tuple with the quotients. Both tuples must be of the same size. Division by zero results in `inf`.

### Syntax

```sql
tupleDivide(tuple1, tuple2)
```

### Arguments

- `tuple1`: [Tuple](../data-types/tuple). The first tuple (numerators).
- `tuple2`: [Tuple](../data-types/tuple). The second tuple (denominators).

### Returns

A tuple containing the quotients of corresponding elements. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleDivide((1, 2), (2, 3))
```

Result:

```result
┌─tupleDivide((1, 2), (2, 3))─┐
│ (0.5,0.6666666666666666)    │
└─────────────────────────────┘
```

## tupleNegate

Returns a new tuple where each numeric element of the input tuple has its sign inverted.

### Syntax

```sql
tupleNegate(tuple)
```

### Arguments

- `tuple`: [Tuple](../data-types/tuple). The input tuple.

### Returns

A tuple with negated numeric values. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tupleNegate((1, 2))─┐
│ (-1,-2)             │
└─────────────────────┘
```

## tupleMultiplyByNumber

Multiplies each numeric element within a tuple by a given scalar number, returning a new tuple with the results.

### Syntax

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

### Arguments

- `tuple`: [Tuple](../data-types/tuple). The input tuple.
- `number`: [Int/UInt](../data-types/int-uint), [Float](../data-types/float) or [Decimal](../data-types/decimal). The scalar multiplier.

### Returns

A tuple with each element multiplied by the number. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tupleMultiplyByNumber((1, 2), -2.1)─┐
│ (-2.1,-4.2)                         │
└─────────────────────────────────────┘
```

## tupleDivideByNumber

Divides each numeric element within a tuple by a given scalar number, returning a new tuple with the quotients. Division by zero results in `inf`.

### Syntax

```sql
tupleDivideByNumber(tuple, number)
```

### Arguments

- `tuple`: [Tuple](../data-types/tuple). The input tuple.
- `number`: [Int/UInt](../data-types/int-uint), [Float](../data-types/float) or [Decimal](../data-types/decimal). The scalar divisor.

### Returns

A tuple with each element divided by the number. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleDivideByNumber((1, 2), 0.5)
```

Result:

```result
┌─tupleDivideByNumber((1, 2), 0.5)─┐
│ (2,4)                            │
└──────────────────────────────────┘
```

## tupleConcat

Concatenates multiple tuples into a single new tuple, combining all elements in order.

### Syntax

```sql
tupleConcat(tuples)
```

### Arguments

- `tuples`: [Tuple](../data-types/tuple). An arbitrary number of tuple arguments to concatenate.

### Returns

A single tuple containing all elements from the input tuples. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleConcat((1, 2), (3, 4), (true, false)) AS res
```

Result:

```result
┌─res──────────────────┐
│ (1,2,3,4,true,false) │
└──────────────────────┘
```

## tupleIntDiv

Performs element-wise integer division between two tuples of the same size. It returns a new tuple containing the integer quotients.

### Syntax

```sql
tupleIntDiv(tuple_num, tuple_div)
```

### Arguments

- `tuple_num`: [Tuple](../data-types/tuple). A tuple of numeric numerator values.
- `tuple_div`: [Tuple](../data-types/tuple). A tuple of numeric divisor values.

### Returns

A tuple of integer quotients. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))
```

Result:

```result
┌─tupleIntDiv((15, 10, 5), (5, 5, 5))─┐
│ (3,2,1)                             │
└─────────────────────────────────────┘
```

```sql
SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))
```

Result:

```result
┌─tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))─┐
│ (2,1,0)                                   │
└───────────────────────────────────────────┘
```

## tupleIntDivOrZero

Performs element-wise integer division between two tuples. If any divisor is zero, the corresponding quotient in the result tuple will be zero instead of throwing an error.

### Syntax

```sql
tupleIntDivOrZero(tuple_num, tuple_div)
```

### Arguments

- `tuple_num`: [Tuple](../data-types/tuple). A tuple of numeric numerator values.
- `tuple_div`: [Tuple](../data-types/tuple). A tuple of numeric divisor values.

### Returns

A tuple of integer quotients. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))
```

Result:

```result
┌─tupleIntDivOrZero((5, 10, 15), (0, 0, 0))─┐
│ (0,0,0)                                   │
└───────────────────────────────────────────┘
```

## tupleIntDivByNumber

Divides each numeric element in a tuple by a single scalar number, returning a new tuple with the integer quotients.

### Syntax

```sql
tupleIntDivByNumber(tuple_num, div)
```

### Arguments

- `tuple_num`: [Tuple](../data-types/tuple). A tuple of numeric numerator values.
- `div`: Numeric. The scalar divisor.

### Returns

A tuple of integer quotients. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleIntDivByNumber((15, 10, 5), 5)
```

Result:

```result
┌─tupleIntDivByNumber((15, 10, 5), 5)─┐
│ (3,2,1)                             │
└─────────────────────────────────────┘
```

```sql
SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)
```

Result:

```result
┌─tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)─┐
│ (2,1,0)                                     │
└─────────────────────────────────────────────┘
```

## tupleIntDivOrZeroByNumber

Divides each numeric element in a tuple by a single scalar number. If the divisor is zero, the corresponding quotient in the result tuple will be zero instead of throwing an error.

### Syntax

```sql
tupleIntDivOrZeroByNumber(tuple_num, div)
```

### Arguments

- `tuple_num`: [Tuple](../data-types/tuple). A tuple of numeric numerator values.
- `div`: Numeric. The scalar divisor.

### Returns

A tuple of integer quotients. [Tuple](../data-types/tuple).

### Example

```sql
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)
```

Result:

```result
┌─tupleIntDivOrZeroByNumber((15, 10, 5), 5)─┐
│ (3,2,1)                                   │
└───────────────────────────────────────────┘
```

```sql
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)
```

Result:

```result
┌─tupleIntDivOrZeroByNumber((15, 10, 5), 0)─┐
│ (0,0,0)                                   │
└───────────────────────────────────────────┘
```

## tupleModulo

Calculates the remainder of element-wise division between two tuples of the same size, returning a new tuple with the moduli.

### Syntax

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

### Arguments

- `tuple_num`: [Tuple](../data-types/tuple). A tuple of numeric numerator values.
- `tuple_mod`: [Tuple](../data-types/tuple). A tuple of numeric modulus values (divisors).

### Returns

A tuple of integer remainders. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tupleModulo((15, 10, 5), (5, 3, 2))─┐
│ (0,1,1)                             │
└─────────────────────────────────────┘
```

## tupleModuloByNumber

Calculates the remainder of dividing each numeric element in a tuple by a single scalar number, returning a new tuple with the moduli.

### Syntax

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

### Arguments

- `tuple_num`: [Tuple](../data-types/tuple). A tuple of numeric numerator values.
- `div`: Numeric. The scalar divisor.

### Returns

A tuple of integer remainders. [Tuple](../data-types/tuple).

### Example

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

Result:

```result
┌─tupleModuloByNumber((15, 10, 5), 2)─┐
│ (1,0,1)                             │
└─────────────────────────────────────┘
```

## flattenTuple

Transforms a nested tuple into a single-level tuple by extracting all elements, including those from inner tuples. This is useful for simplifying complex tuple structures.

### Syntax

```sql
flattenTuple(input)
```

### Arguments

- `input`: [Tuple](../data-types/tuple). The nested tuple to flatten.

### Returns

A flattened tuple. [Tuple](../data-types/tuple).

### Example

```sql
SELECT flattenTuple(t) FROM
(select (c1,c2,c3)::Tuple(t1 Nested(a UInt32, s String), b UInt32, t2 Tuple(k String, v UInt32)) as t from values((([(1, 'a'), (2, 'b')], 3, ('c', 4)))))
```

Result:

```result
┌─flattenTuple(t)───────────┐
│ ([1,2],['a','b'],3,'c',4) │
└───────────────────────────┘
```

## Distance functions

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