Функции Tuple - ClickHouse Documentation

Приведённая ниже документация сгенерирована на основе системной таблицы system.functions.

dotProduct

Добавленный в: v21.11.0 Вычисляет скалярное произведение двух векторов (кортежей или массивов одинакового размера). Возвращает сумму произведений соответствующих элементов. Синтаксис

dotProduct(vector1, vector2)

Псевдонимы: scalarProduct Аргументы

vector1 — Первый вектор. Array(T) или Tuple(T)
vector2 — Второй вектор. Должен быть того же размера, что и первый. Array(T) или Tuple(T)

Возвращаемое значение Возвращает скалярное произведение двух векторов. (U)Int* или Float* или Decimal Примеры Базовое использование

Query

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

Response

flattenTuple

Добавленный в: v22.6.0 Преобразует именованный вложенный кортеж в плоский. Элементами возвращаемого кортежа являются пути входного кортежа. Синтаксис

flattenTuple(input)

Аргументы

input — Именованный вложенный кортеж, который нужно развернуть. Tuple(n1 T1[, n2 T2, ... ])

Возвращаемое значение Возвращает выходной кортеж, элементы которого представляют собой пути из исходного входного значения. Tuple(T) Примеры Пример использования

Query

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;

Response

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

tuple

Добавленный в: v1.1.0 Возвращает кортеж, объединяя входные аргументы. Для столбцов C1, C2, … с типами T1, T2, … возвращается кортеж именованного типа Tuple(C1 T1, C2 T2, …), содержащий эти столбцы, если их имена уникальны и могут использоваться как идентификаторы без кавычек; в противном случае возвращается Tuple(T1, T2, …). Выполнение этой функции не требует дополнительных затрат. Tuple обычно используются как промежуточные значения для аргументов операторов IN или для создания списка формальных параметров лямбда-функций. Tuple нельзя записывать в таблицу. Функция реализует оператор (x, y, ...). Синтаксис

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

Аргументы

Отсутствуют.

Возвращаемое значение Примеры обычный

Query

SELECT tuple(1, 2)

Response

(1,2)

tupleConcat

Добавленный в: v23.8.0 Объединяет кортежи, переданные в качестве аргументов. Синтаксис

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

Аргументы

tupleN — Произвольное количество аргументов типа Tuple. Tuple(T)

Возвращаемое значение Возвращает кортеж, содержащий все элементы входных кортежей. Tuple(T) Примеры Пример использования

Query

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

Response

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

tupleDivide

Добавленный в: v21.11.0 Вычисляет результат деления соответствующих элементов двух кортежей одинакового размера.

При делении на ноль возвращается inf.

Синтаксис

tupleDivide(t1, t2)

Аргументы

t1 — Первый кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
t2 — Второй кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает кортеж с результатом деления. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(0.5, 0.6666666666666666)

tupleDivideByNumber

Добавленный в: v21.11.0 Возвращает кортеж, все элементы которого разделены на число.

Деление на ноль вернёт inf.

Синтаксис

tupleDivideByNumber(tuple, number)

Аргументы

tuple — Кортеж для деления. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
number — Делитель. (U)Int* или Float* или Decimal

Возвращаемое значение Возвращает кортеж с элементами, полученными в результате деления. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

SELECT tupleDivideByNumber((1, 2), 0.5)

Response

(2, 4)

tupleElement

Добавленный в: v1.1.0 Извлекает элемент из Tuple по индексу или имени. Для доступа по индексу ожидается числовой индекс, начиная с 1. Для доступа по имени имя элемента можно указать в виде строки (работает только для именованных Tuple). Поддерживаются отрицательные индексы. В этом случае выбирается соответствующий элемент с нумерацией от конца. Например, tuple.-1 — это последний элемент в Tuple. Необязательный третий аргумент задает значение по умолчанию, которое возвращается вместо того, чтобы генерировать исключение, если запрашиваемый элемент не существует. Все аргументы должны быть константами. Эта функция не имеет накладных расходов во время выполнения и реализует операторы x.index и x.name. Синтаксис

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

Аргументы

tuple — Кортеж или массив кортежей. Tuple(T) или Array(Tuple(T))
index — Индекс столбца, нумерация с 1. const UInt8/16/32/64
name — Имя элемента. const String
default_value — Значение по умолчанию, возвращаемое, если индекс выходит за границы или элемент отсутствует. Any

Возвращаемое значение Возвращает элемент по указанному индексу или имени. Any Примеры Доступ по индексу

Query

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

Response

hello

Индексация с отрицательными индексами

Query

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

Response

hello

Именованный кортеж с таблицей

Query

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

Response

Alice

Со значением по умолчанию

Query

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

Response

not_found

Синтаксис оператора

Query

SELECT (1, 'hello').2

Response

hello

tupleHammingDistance

Добавленный в: v21.1.0 Возвращает расстояние Хэмминга между двумя кортежами одинаковой длины.

Тип результата определяется так же, как для арифметических функций, на основе количества элементов во входных кортежах.

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

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

Синтаксис

tupleHammingDistance(t1, t2)

Аргументы

t1 — Первый кортеж. Tuple(*)
t2 — Второй кортеж. Tuple(*)

Возвращаемое значение Возвращает расстояние Хэмминга. UInt8/16/32/64 Примеры Пример использования

Query

SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))

Response

С MinHash для обнаружения почти одинаковых строк

Query

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

Response

tupleIntDiv

Добавленный в: v23.8.0 Выполняет целочисленное деление кортежа числителей на кортеж знаменателей. Возвращает кортеж частных. Если хотя бы один из кортежей содержит нецелочисленные элементы, результат вычисляется с округлением каждого нецелочисленного числителя или делителя до ближайшего целого. При делении на 0 генерируется ошибка. Синтаксис

tupleIntDiv(tuple_num, tuple_div)

Аргументы

tuple_num — Кортеж значений числителя. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
tuple_div — Кортеж значений делителя. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает кортеж частных. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(3, 2, 1)

С десятичными дробями

Query

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

Response

(2, 1, 0)

tupleIntDivByNumber

Добавленный в: v23.8.0 Выполняет целочисленное деление кортежа числителей на заданный знаменатель и возвращает кортеж частных. Если один из входных параметров содержит нецелые элементы, результат вычисляется с округлением до ближайшего целого для каждого нецелого числителя или делителя. При делении на 0 будет сгенерировано исключение. Синтаксис

tupleIntDivByNumber(tuple_num, div)

Аргументы

tuple_num — Кортеж значений делимого. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
div — Значение делителя. (U)Int* или Float* или Decimal

Query

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

Response

(3, 2, 1)

С десятичными числами

Query

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

Response

(2, 1, 0)

tupleIntDivOrZero

Добавленный в: v23.8.0 Как и tupleIntDiv, выполняет целочисленное деление кортежа числителей на кортеж знаменателей и возвращает кортеж частных. В случае деления на 0 возвращает частное 0 вместо того, чтобы генерировать исключение. Если любой из кортежей содержит нецелочисленные элементы, результат вычисляется путем округления каждого нецелочисленного числителя или делителя до ближайшего целого числа. Синтаксис

tupleIntDivOrZero(tuple_num, tuple_div)

Аргументы

tuple_num — Tuple значений делимого. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
tuple_div — Tuple значений делителя. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает Tuple частных. Для частных, где делитель равен 0, возвращает 0. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры С нулевыми делителями

Query

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

Response

(0, 0, 0)

tupleIntDivOrZeroByNumber

Добавленный в: v23.8.0 Как и tupleIntDivByNumber, выполняет целочисленное деление кортежа числителей на заданный делитель и возвращает кортеж частных. При делении на ноль не вызывает ошибку, а вместо этого возвращает нулевое частное. Если кортеж или div содержат нецелочисленные элементы, результат вычисляется с округлением каждого нецелочисленного числителя или делителя до ближайшего целого. Синтаксис

tupleIntDivOrZeroByNumber(tuple_num, div)

Аргументы

tuple_num — Кортеж значений числителя. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
div — Значение делителя. (U)Int* или Float* или Decimal

Возвращаемое значение Возвращает кортеж частных; для частных, где делитель равен 0, возвращается 0. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(3, 2, 1)

При нулевом делителе

Query

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

Response

(0, 0, 0)

tupleMinus

Добавленный в: v21.11.0 Вычисляет разность соответствующих элементов двух кортежей одинакового размера. Синтаксис

tupleMinus(t1, t2)

Псевдонимы: vectorDifference Аргументы

t1 — Первый кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
t2 — Второй кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает кортеж с результатами вычитания. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(-1, -1)

tupleModulo

Добавленный в: v23.8.0 Возвращает кортеж остатков от деления двух кортежей. Синтаксис

tupleModulo(tuple_num, tuple_mod)

Аргументы

tuple_num — Кортеж значений делимого. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
tuple_mod — Кортеж значений модуля. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает кортеж остатков от деления. При делении на ноль генерируется исключение. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(0, 1, 1)

tupleModuloByNumber

Добавленный в: v23.8.0 Возвращает кортеж остатков от деления элементов кортежа на заданный делитель. Синтаксис

tupleModuloByNumber(tuple_num, div)

Аргументы

tuple_num — Кортеж элементов делимого. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
div — Значение делителя. (U)Int* или Float* или Decimal

Возвращаемое значение Возвращает кортеж остатков от деления. При делении на ноль возникает ошибка. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(1, 0, 1)

tupleMultiply

Добавленный в: v21.11.0 Вычисляет произведение соответствующих элементов двух кортежей одного размера. Синтаксис

tupleMultiply(t1, t2)

Аргументы

t1 — Первый кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
t2 — Второй кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает кортеж с результатами умножения. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(2, 6)

tupleMultiplyByNumber

Добавленный в: v21.11.0 Возвращает кортеж, все элементы которого умножены на число. Синтаксис

tupleMultiplyByNumber(tuple, number)

Аргументы

tuple — Кортеж для умножения. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
number — Множитель. (U)Int* или Float* или Decimal

Возвращаемое значение Возвращает кортеж с умноженными элементами. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(-2.1, -4.2)

tupleNames

Добавленный в: v24.8.0 Преобразует кортеж в массив имён столбцов. Для кортежа вида Tuple(a T, b T, ...) возвращает массив строк, представляющих именованные столбцы кортежа. Если элементы кортежа не имеют явных имён, в качестве имён столбцов вместо них будут использоваться их индексы. Синтаксис

tupleNames(tuple)

Аргументы

Нет.

Возвращаемое значение Примеры обычный

Query

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

Response

['a','b']

tupleNegate

Добавленный в: v21.11.0 Вычисляет значения, противоположные элементам кортежа. Синтаксис

tupleNegate(t)

Аргументы

t — кортеж, к которому применяется отрицание. Tuple((U)Int*) or Tuple(Float*) or Tuple(Decimal)

Возвращаемое значение Возвращает кортеж с результатом отрицания. Tuple((U)Int*) or Tuple(Float*) or Tuple(Decimal) Примеры Базовое использование

Query

SELECT tupleNegate((1, 2))

Response

(-1, -2)

tuplePlus

Добавленный в: v21.11.0 Вычисляет сумму соответствующих элементов двух кортежей одного размера. Синтаксис

tuplePlus(t1, t2)

Псевдонимы: vectorSum Аргументы

t1 — Первый кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
t2 — Второй кортеж. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Возвращаемое значение Возвращает кортеж, содержащий суммы соответствующих элементов входных кортежей. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

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

Response

(3, 5)

tuplePositiveModuloByNumber

Добавленный в: v26.4.0 Возвращает кортеж положительных остатков от деления элементов кортежа на заданный делитель. В отличие от tupleModuloByNumber, результат всегда неотрицательный. Синтаксис

tuplePositiveModuloByNumber(tuple_num, div)

Аргументы

tuple_num — Tuple значений числителя. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
div — Значение делителя. (U)Int* или Float* или Decimal

Возвращаемое значение Возвращает Tuple неотрицательных остатков. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal) Примеры Базовое использование

Query

SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)

Response

(1, 0, 1)

tupleToNameValuePairs

Добавленный в: v21.9.0 Преобразует кортеж в массив пар (имя, значение). Например, кортеж Tuple(n1 T1, n2 T2, ...) преобразуется в Array(Tuple('n1', T1), Tuple('n2', T2), ...). Все значения в кортеже должны быть одного типа. Синтаксис

tupleToNameValuePairs(tuple)

Аргументы

tuple — Именованный кортеж со значениями любых типов. Tuple(n1 T1[, n2 T2, ...])

Возвращаемое значение Возвращает массив из пар (name, value). Array(Tuple(String, T)) Примеры Именованный кортеж

Query

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

Response

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

Безымянный кортеж

Query

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

Response

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

untuple

Выполняет синтаксическую подстановку элементов кортежа в месте вызова. Имена результирующих столбцов зависят от реализации и могут меняться. Не следует полагаться на конкретные имена столбцов после untuple. Синтаксис

untuple(x)

Вы можете использовать выражение EXCEPT, чтобы исключить столбцы из результата запроса. Аргументы

x — функция tuple, столбец или кортеж элементов. Tuple.

Возвращаемое значение

Отсутствует.

Примеры Входная таблица:

┌─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') │
└─────┴────┴────┴────┴────┴────┴───────────┘

Пример использования столбца типа Tuple в качестве параметра функции untuple:

Query

SELECT untuple(v6) FROM kv;

Response

┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘

Пример использования выражения EXCEPT:

Query

SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;

Response

┌─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') │
└─────┴────┴────┴────┴───────────┘

Функции расстояния

Описание всех поддерживаемых функций приведено в документации по функциям расстояния.

​dotProduct

​flattenTuple

​tuple

​tupleConcat

​tupleDivide

​tupleDivideByNumber

​tupleElement

​tupleHammingDistance

​tupleIntDiv

​tupleIntDivByNumber

​tupleIntDivOrZero

​tupleIntDivOrZeroByNumber

​tupleMinus

​tupleModulo

​tupleModuloByNumber

​tupleMultiply

​tupleMultiplyByNumber

​tupleNames

​tupleNegate

​tuplePlus

​tuplePositiveModuloByNumber

​tupleToNameValuePairs

​untuple

​Функции расстояния

dotProduct

flattenTuple

tuple

tupleConcat

tupleDivide

tupleDivideByNumber

tupleElement

tupleHammingDistance

tupleIntDiv

tupleIntDivByNumber

tupleIntDivOrZero

tupleIntDivOrZeroByNumber

tupleMinus

tupleModulo

tupleModuloByNumber

tupleMultiply

tupleMultiplyByNumber

tupleNames

tupleNegate

tuplePlus

tuplePositiveModuloByNumber

tupleToNameValuePairs

untuple

Функции расстояния