tuple-functions

tuple

A function that allows grouping multiple columns. 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

tupleElement

A function that allows getting a column from a tuple.

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.

The function implements operators x.index and x.name.

Syntax

untuple

Performs syntactic substitution of 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

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.

Returned value

• None.

Examples

Input table:

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

Query:

Result:

Example of using an EXCEPT expression:

Query:

Result:

See Also

• Tuple

tupleHammingDistance

Returns the Hamming Distance between two tuples of the same size.

Syntax

Arguments

• tuple1 — First tuple. Tuple.
• tuple2 — Second tuple. Tuple.

Tuples should have the same type of the elements.

Returned value

• The Hamming distance.

Note

The result type is calculated the same way it is for Arithmetic functions, based on the number of elements in the input tuples.

Examples

Query:

Result:

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

Result:

tupleToNameValuePairs

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), ...) 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.

Syntax

Arguments

• tuple — Named tuple. Tuple with any types of values.

Returned value

• An array with (name, value) pairs. Array(Tuple(String, ...)).

Example

Query:

Result:

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

Result:

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

Result:

tupleNames

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

Arguments

• tuple — Named tuple. Tuple with any types of values.

Returned value

• An array with strings.

Type: Array(Tuple(String, ...)).

Example

Query:

Result:

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

Result:

tuplePlus

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

Syntax

Alias: vectorSum.

Arguments

• tuple1 — First tuple. Tuple.
• tuple2 — Second tuple. Tuple.

Returned value

• Tuple with the sum. Tuple.

Example

Query:

Result:

tupleMinus

Calculates the subtraction of corresponding values of two tuples of the same size.

Syntax

Alias: vectorDifference.

Arguments

• tuple1 — First tuple. Tuple.
• tuple2 — Second tuple. Tuple.

Returned value

• Tuple with the result of subtraction. Tuple.

Example

Query:

Result:

tupleMultiply

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

Syntax

Arguments

• tuple1 — First tuple. Tuple.
• tuple2 — Second tuple. Tuple.

Returned value

• Tuple with the multiplication. Tuple.

Example

Query:

Result:

tupleDivide

Calculates the division of corresponding values of two tuples of the same size. Note that division by zero will return inf.

Syntax

Arguments

• tuple1 — First tuple. Tuple.
• tuple2 — Second tuple. Tuple.

Returned value

• Tuple with the result of division. Tuple.

Example

Query:

Result:

tupleNegate

Calculates the negation of the tuple values.

Syntax

Arguments

• tuple — Tuple.

Returned value

• Tuple with the result of negation. Tuple.

Example

Query:

Result:

tupleMultiplyByNumber

Returns a tuple with all values multiplied by a number.

Syntax

Arguments

• tuple — Tuple.
• number — Multiplier. Int/UInt, Float or Decimal.

Returned value

• Tuple with multiplied values. Tuple.

Example

Query:

Result:

tupleDivideByNumber

Returns a tuple with all values divided by a number. Note that division by zero will return inf.

Syntax

Arguments

• tuple — Tuple.
• number — Divider. Int/UInt, Float or Decimal.

Returned value

• Tuple with divided values. Tuple.

Example

Query:

Result:

tupleConcat

Combines tuples passed as arguments.

Arguments

• tuples – Arbitrary number of arguments of Tuple type.

Example

tupleIntDiv

Does integer division of a tuple of numerators and a tuple of denominators, and returns a tuple of the quotients.

Syntax

Parameters

• tuple_num: Tuple of numerator values. Tuple of numeric type.
• tuple_div: Tuple of divisor values. Tuple of numeric type.

Returned value

• Tuple of the quotients of tuple_num and tuple_div. Tuple of integer values.

Implementation details

• If either tuple_num or tuple_div contain non-integer values 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.

Examples

Query:

Result:

Query:

Result:

tupleIntDivOrZero

Like tupleIntDiv it does integer division of a tuple of numerators and a tuple of denominators, and returns a tuple of the quotients. It does not throw an error for 0 divisors, but rather returns the quotient as 0.

Syntax

• tuple_num: Tuple of numerator values. Tuple of numeric type.
• tuple_div: Tuple of divisor values. Tuple of numeric type.

Returned value

• Tuple of the quotients of tuple_num and tuple_div. Tuple of integer values.
• Returns 0 for quotients where the divisor is 0.

Implementation details

• If either tuple_num or tuple_div contain non-integer values then the result is calculated by rounding to the nearest integer for each non-integer numerator or divisor as in tupleIntDiv.

Examples

Query:

Result:

tupleIntDivByNumber

Does integer division of a tuple of numerators by a given denominator, and returns a tuple of the quotients.

Syntax

Parameters

• tuple_num: Tuple of numerator values. Tuple of numeric type.
• div: The divisor value. Numeric type.

Returned value

• Tuple of the quotients of tuple_num and div. Tuple of integer values.

Implementation details

• If either tuple_num or div contain non-integer values 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.

Examples

Query:

Result:

Query:

Result:

tupleIntDivOrZeroByNumber

Like 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 0 divisors, but rather returns the quotient as 0.

Syntax

Parameters

• tuple_num: Tuple of numerator values. Tuple of numeric type.
• div: The divisor value. Numeric type.

Returned value

• Tuple of the quotients of tuple_num and div. Tuple of integer values.
• Returns 0 for quotients where the divisor is 0.

Implementation details

• If either tuple_num or div contain non-integer values then the result is calculated by rounding to the nearest integer for each non-integer numerator or divisor as in tupleIntDivByNumber.

Examples

Query:

Result:

Query:

Result:

tupleModulo

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

Syntax

Parameters

• tuple_num: Tuple of numerator values. Tuple of numeric type.
• tuple_div: Tuple of modulus values. Tuple of numeric type.

Returned value

• Tuple of the remainders of division of tuple_num and tuple_div. Tuple of non-zero integer values.
• An error is thrown for division by zero.

Examples

Query:

Result:

tupleModuloByNumber

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

Syntax

Parameters

• tuple_num: Tuple of numerator values. Tuple of numeric type.
• div: The divisor value. Numeric type.

Returned value

• Tuple of the remainders of division of tuple_num and div. Tuple of non-zero integer values.
• An error is thrown for division by zero.

Examples

Query:

Result:

flattenTuple

Returns a flattened output tuple from a nested named input tuple. Elements of the output tuple are the paths from the original input tuple. For instance: Tuple(a Int, Tuple(b Int, c Int)) -> Tuple(a Int, b Int, c Int). flattenTuple can be used to select all paths from type Object as separate columns.

Syntax

Parameters

• input: Nested named tuple to flatten. Tuple.

Returned value

• output tuple whose elements are paths from the original input. Tuple.

Example

Query:

Result:

Distance functions

All supported functions are described in distance functions documentation.