Tuple functions

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/sql-reference/functions/tuple-functions.md)

Note

The documentation below is generated from the `system.functions` system table.

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

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

```
dotProduct(vector1, vector2)
```

**Aliases**: `scalarProduct`

**Arguments**

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

**Returned value**

Returns the dot product of the two vectors. [`(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)

**Examples**

**Basic usage**

```
SELECT dotProduct((1, 2), (3, 4))
```

```
11
```

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

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

```
flattenTuple(input)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

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

```
┌─flattenTuple(t)┐
│ (3, 'c', 4)    │
└────────────────┘
```

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

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

```
tuple([t1[, t2[ ...]])
```

**Arguments**

- None.

**Returned value**

**Examples**

**typical**

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

```
(1,2)
```

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

Introduced in: v23.8.0

Combines tuples passed as arguments.

**Syntax**

```
tupleConcat(tuple1[, tuple2, [...]])
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

```
SELECT tupleConcat((1, 2), ('a',), (true, false))
```

```
(1, 2, 'a', true, false)
```

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

Introduced in: v21.11.0

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

Note

Division by zero will return `inf`.

**Syntax**

```
tupleDivide(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 tuple with the result of division. [`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 tupleDivide((1, 2), (2, 3))
```

```
(0.5, 0.6666666666666666)
```

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

Introduced in: v21.11.0

Returns a tuple with all elements divided by a number.

Note

Division by zero will return `inf`.

**Syntax**

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

**Arguments**

- `tuple` — Tuple to divide. [`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` — Divider. [`(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 divided 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 tupleDivideByNumber((1, 2), 0.5)
```

```
(2, 4)
```

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

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

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

**Arguments**

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

**Returned value**

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

**Examples**

**Index access**

```
SELECT tupleElement((1, 'hello'), 2)
```

```
hello
```

**Negative indexing**

```
SELECT tupleElement((1, 'hello'), -1)
```

```
hello
```

**Named tuple with table**

```
CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;
```

```
Alice
```

**With default value**

```
SELECT tupleElement((1, 2), 5, 'not_found')
```

```
not_found
```

**Operator syntax**

```
SELECT (1, 'hello').2
```

```
hello
```

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

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](/docs/sql-reference/functions/arithmetic-functions), based on the number of elements in the input tuples.

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