2020-11-27 19:37:44 +00:00
---
2022-08-28 14:53:34 +00:00
slug: /en/sql-reference/functions/tuple-functions
2023-04-19 17:05:55 +00:00
sidebar_position: 180
2022-04-09 13:29:05 +00:00
sidebar_label: Tuples
2020-11-27 19:37:44 +00:00
---
2022-06-02 10:55:18 +00:00
## tuple
2020-11-27 19:37:44 +00:00
A function that allows grouping multiple columns.
For columns with the types T1, T2, …, it returns a Tuple(T1, T2, …) type tuple containing these columns. 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.
2020-11-28 11:38:57 +00:00
The function implements the operator `(x, y, …)` .
2020-11-27 19:37:44 +00:00
**Syntax**
``` sql
tuple(x, y, …)
```
2022-06-02 10:55:18 +00:00
## tupleElement
2020-11-27 19:37:44 +00:00
A function that allows getting a column from a tuple.
2023-06-28 10:49:46 +00:00
If the second argument is a number `index` , it is the column index, starting from 1. If the second argument is a string `name` , it represents the name of the element. Besides, we can provide the third optional argument, such that when index out of bounds or no element exist for the name, the default value returned instead of throwing an exception. The second and third arguments, if provided, must be constants. There is no cost to execute the function.
2023-03-17 14:17:33 +00:00
2023-06-28 10:49:46 +00:00
The function implements operators `x.index` and `x.name` .
2020-11-28 11:38:57 +00:00
2020-11-27 19:37:44 +00:00
**Syntax**
``` sql
2023-06-28 10:49:46 +00:00
tupleElement(tuple, index, [, default_value])
tupleElement(tuple, name, [, default_value])
2020-11-27 19:37:44 +00:00
```
2022-06-02 10:55:18 +00:00
## untuple
2020-11-27 19:37:44 +00:00
Performs syntactic substitution of [tuple ](../../sql-reference/data-types/tuple.md#tuplet1-t2 ) elements in the call location.
2023-10-08 09:32:02 +00:00
The names of the result columns are implementation-specific and subject to change. Do not assume specific column names after `untuple` .
2020-11-27 19:37:44 +00:00
**Syntax**
``` sql
untuple(x)
```
You can use the `EXCEPT` expression to skip columns as a result of the query.
2021-02-15 21:22:10 +00:00
**Arguments**
2020-11-27 19:37:44 +00:00
2023-04-19 15:55:29 +00:00
- `x` — A `tuple` function, column, or tuple of elements. [Tuple ](../../sql-reference/data-types/tuple.md ).
2020-11-27 19:37:44 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- None.
2020-11-27 19:37:44 +00:00
**Examples**
Input table:
``` text
┌─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:
Query:
``` sql
SELECT untuple(v6) FROM kv;
```
Result:
``` text
┌─_ut_1─┬─_ut_2─┐
│ 33 │ ab │
│ 44 │ cd │
│ 55 │ ef │
│ 66 │ gh │
│ 77 │ kl │
└───────┴───────┘
```
Example of using an `EXCEPT` expression:
Query:
``` sql
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;
```
Result:
``` text
┌─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') │
└─────┴────┴────┴────┴───────────┘
```
**See Also**
2023-04-19 15:55:29 +00:00
- [Tuple ](../../sql-reference/data-types/tuple.md )
2020-11-27 19:37:44 +00:00
2022-06-02 10:55:18 +00:00
## tupleHammingDistance
2021-04-02 11:19:25 +00:00
Returns the [Hamming Distance ](https://en.wikipedia.org/wiki/Hamming_distance ) between two tuples of the same size.
**Syntax**
``` sql
tupleHammingDistance(tuple1, tuple2)
```
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple1` — First tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
- `tuple2` — Second tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-04-02 11:19:25 +00:00
Tuples should have the same type of the elements.
**Returned value**
2023-04-19 15:55:29 +00:00
- The Hamming distance.
2021-04-02 11:19:25 +00:00
2023-05-04 16:35:18 +00:00
Type: The result type is calculated the same way it is for [Arithmetic functions ](../../sql-reference/functions/arithmetic-functions.md ), based on the number of elements in the input tuples.
2022-01-18 23:11:28 +00:00
``` 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
```
``` text
┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
│ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
└───────┴────────┴────────┴────────┴────────┘
```
2021-04-02 11:19:25 +00:00
**Examples**
Query:
``` sql
SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1)) AS HammingDistance;
```
Result:
``` text
┌─HammingDistance─┐
│ 2 │
└─────────────────┘
```
Can be used with [MinHash ](../../sql-reference/functions/hash-functions.md#ngramminhash ) functions for detection of semi-duplicate strings:
``` sql
2021-05-27 19:49:41 +00:00
SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) as HammingDistance FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string);
2021-04-02 11:19:25 +00:00
```
Result:
``` text
┌─HammingDistance─┐
│ 2 │
└─────────────────┘
```
2021-10-25 11:18:51 +00:00
2022-06-02 10:55:18 +00:00
## tupleToNameValuePairs
2021-10-25 11:18:51 +00:00
2021-10-25 21:01:31 +00:00
Turns a named tuple into an array of (name, value) pairs. For a `Tuple(a T, b T, ..., c T)` returns `Array(Tuple(String, T), ...)`
2021-10-25 21:15:46 +00:00
in which the `Strings` represents the named fields of the tuple and `T` are the values associated with those names. All values in the tuple should be of the same type.
2021-10-25 11:18:51 +00:00
**Syntax**
``` sql
2021-10-25 21:01:31 +00:00
tupleToNameValuePairs(tuple)
2021-12-06 09:57:09 +00:00
```
2021-10-25 11:18:51 +00:00
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple` — Named tuple. [Tuple ](../../sql-reference/data-types/tuple.md ) with any types of values.
2021-10-25 11:18:51 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- An array with (name, value) pairs.
2021-10-25 11:18:51 +00:00
2021-10-25 21:01:31 +00:00
Type: [Array ](../../sql-reference/data-types/array.md )([Tuple](../../sql-reference/data-types/tuple.md)([String](../../sql-reference/data-types/string.md), ...)).
2021-10-25 11:18:51 +00:00
**Example**
2021-10-25 21:01:31 +00:00
Query:
``` sql
2023-04-03 13:47:44 +00:00
CREATE TABLE tupletest (col Tuple(user_ID UInt64, session_ID UInt64)) ENGINE = Memory;
2021-10-25 21:01:31 +00:00
INSERT INTO tupletest VALUES (tuple( 100, 2502)), (tuple(1,100));
SELECT tupleToNameValuePairs(col) FROM tupletest;
2021-12-06 09:57:09 +00:00
```
2021-10-25 21:01:31 +00:00
Result:
``` text
┌─tupleToNameValuePairs(col)────────────┐
│ [('user_ID',100),('session_ID',2502)] │
│ [('user_ID',1),('session_ID',100)] │
└───────────────────────────────────────┘
```
2023-05-04 16:35:18 +00:00
It is possible to transform columns to rows using this function:
2021-10-25 21:01:31 +00:00
``` sql
2023-04-03 13:47:44 +00:00
CREATE TABLE tupletest (col Tuple(CPU Float64, Memory Float64, Disk Float64)) ENGINE = Memory;
2021-10-25 21:01:31 +00:00
INSERT INTO tupletest VALUES(tuple(3.3, 5.5, 6.6));
2023-04-03 13:47:44 +00:00
SELECT arrayJoin(tupleToNameValuePairs(col)) FROM tupletest;
2021-10-25 21:01:31 +00:00
```
Result:
``` text
┌─arrayJoin(tupleToNameValuePairs(col))─┐
│ ('CPU',3.3) │
│ ('Memory',5.5) │
│ ('Disk',6.6) │
└───────────────────────────────────────┘
```
If you pass a simple tuple to the function, ClickHouse uses the indexes of the values as their names:
``` sql
SELECT tupleToNameValuePairs(tuple(3, 2, 1));
```
Result:
``` text
┌─tupleToNameValuePairs(tuple(3, 2, 1))─┐
│ [('1',3),('2',2),('3',1)] │
└───────────────────────────────────────┘
2022-01-18 19:38:30 +00:00
```
2021-10-25 22:15:13 +00:00
2022-06-02 10:55:18 +00:00
## tuplePlus
2021-10-19 22:42:05 +00:00
Calculates the sum of corresponding values of two tuples of the same size.
**Syntax**
```sql
tuplePlus(tuple1, tuple2)
```
Alias: `vectorSum` .
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple1` — First tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
- `tuple2` — Second tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with the sum.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
SELECT tuplePlus((1, 2), (2, 3));
```
Result:
```text
┌─tuplePlus((1, 2), (2, 3))─┐
│ (3,5) │
└───────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## tupleMinus
2021-10-19 22:42:05 +00:00
Calculates the subtraction of corresponding values of two tuples of the same size.
**Syntax**
```sql
tupleMinus(tuple1, tuple2)
```
Alias: `vectorDifference` .
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple1` — First tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
- `tuple2` — Second tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with the result of subtraction.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
SELECT tupleMinus((1, 2), (2, 3));
```
Result:
```text
┌─tupleMinus((1, 2), (2, 3))─┐
│ (-1,-1) │
└────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## tupleMultiply
2021-10-19 22:42:05 +00:00
Calculates the multiplication of corresponding values of two tuples of the same size.
**Syntax**
```sql
tupleMultiply(tuple1, tuple2)
```
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple1` — First tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
- `tuple2` — Second tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with the multiplication.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
SELECT tupleMultiply((1, 2), (2, 3));
```
Result:
```text
┌─tupleMultiply((1, 2), (2, 3))─┐
│ (2,6) │
└───────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## tupleDivide
2021-10-19 22:42:05 +00:00
Calculates the division of corresponding values of two tuples of the same size. Note that division by zero will return `inf` .
**Syntax**
```sql
tupleDivide(tuple1, tuple2)
```
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple1` — First tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
- `tuple2` — Second tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with the result of division.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
SELECT tupleDivide((1, 2), (2, 3));
```
Result:
```text
┌─tupleDivide((1, 2), (2, 3))─┐
│ (0.5,0.6666666666666666) │
└─────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## tupleNegate
2021-10-19 22:42:05 +00:00
Calculates the negation of the tuple values.
**Syntax**
```sql
tupleNegate(tuple)
```
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple` — [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with the result of negation.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
2021-10-25 11:13:12 +00:00
SELECT tupleNegate((1, 2));
2021-10-19 22:42:05 +00:00
```
Result:
```text
┌─tupleNegate((1, 2))─┐
│ (-1,-2) │
└─────────────────────┘
```
2022-06-02 10:55:18 +00:00
## tupleMultiplyByNumber
2021-10-19 22:42:05 +00:00
Returns a tuple with all values multiplied by a number.
**Syntax**
```sql
tupleMultiplyByNumber(tuple, number)
```
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple` — [Tuple ](../../sql-reference/data-types/tuple.md ).
- `number` — Multiplier. [Int/UInt ](../../sql-reference/data-types/int-uint.md ), [Float ](../../sql-reference/data-types/float.md ) or [Decimal ](../../sql-reference/data-types/decimal.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with multiplied values.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
SELECT tupleMultiplyByNumber((1, 2), -2.1);
```
Result:
```text
┌─tupleMultiplyByNumber((1, 2), -2.1)─┐
│ (-2.1,-4.2) │
└─────────────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## tupleDivideByNumber
2021-10-19 22:42:05 +00:00
Returns a tuple with all values divided by a number. Note that division by zero will return `inf` .
**Syntax**
```sql
tupleDivideByNumber(tuple, number)
```
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple` — [Tuple ](../../sql-reference/data-types/tuple.md ).
- `number` — Divider. [Int/UInt ](../../sql-reference/data-types/int-uint.md ), [Float ](../../sql-reference/data-types/float.md ) or [Decimal ](../../sql-reference/data-types/decimal.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Tuple with divided values.
2021-10-19 22:42:05 +00:00
Type: [Tuple ](../../sql-reference/data-types/tuple.md ).
**Example**
Query:
```sql
SELECT tupleDivideByNumber((1, 2), 0.5);
```
Result:
```text
┌─tupleDivideByNumber((1, 2), 0.5)─┐
│ (2,4) │
└──────────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## dotProduct
2021-10-19 22:42:05 +00:00
Calculates the scalar product of two tuples of the same size.
**Syntax**
```sql
dotProduct(tuple1, tuple2)
```
Alias: `scalarProduct` .
**Arguments**
2023-04-19 15:55:29 +00:00
- `tuple1` — First tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
- `tuple2` — Second tuple. [Tuple ](../../sql-reference/data-types/tuple.md ).
2021-10-19 22:42:05 +00:00
**Returned value**
2023-04-19 15:55:29 +00:00
- Scalar product.
2021-10-19 22:42:05 +00:00
Type: [Int/UInt ](../../sql-reference/data-types/int-uint.md ), [Float ](../../sql-reference/data-types/float.md ) or [Decimal ](../../sql-reference/data-types/decimal.md ).
**Example**
Query:
```sql
SELECT dotProduct((1, 2), (2, 3));
```
Result:
```text
┌─dotProduct((1, 2), (2, 3))─┐
│ 8 │
└────────────────────────────┘
```
2023-08-09 20:52:09 +00:00
## tupleConcat
Combines tuples passed as arguments.
``` sql
tupleConcat(tuples)
```
**Arguments**
- `tuples` – Arbitrary number of arguments of [Tuple ](../../sql-reference/data-types/tuple.md ) type.
**Example**
``` sql
SELECT tupleConcat((1, 2), (3, 4), (true, false)) AS res
```
``` text
┌─res──────────────────┐
│ (1,2,3,4,true,false) │
└──────────────────────┘
```
2021-10-19 22:42:05 +00:00
2022-07-13 10:29:13 +00:00
## Distance functions
2021-10-19 22:42:05 +00:00
2022-07-13 10:29:13 +00:00
All supported functions are described in [distance functions documentation ](../../sql-reference/functions/distance-functions.md ).