Функции работы с кортежами

Примечание

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

flattenTuple

Добавлена в версии v22.6

Разворачивает именованный и вложенный tuple. Элементы возвращаемого tuple представляют собой пути к элементам входного tuple.

Синтаксис

flattenTuple(input)

Аргументы

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

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

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

Примеры

Пример использования

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

Впервые представлена в: v

Возвращает кортеж, группируя входные аргументы.

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

Функция реализует оператор (x, y, ...).

Синтаксис

Аргументы

Нет.

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

Примеры

Типичный

SELECT tuple(1, 2)

(1,2)

tupleConcat

Появилось в версии: v23.8

Объединяет кортежи, переданные в качестве аргументов.

Синтаксис

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

Аргументы

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

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

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

Примеры

Пример использования

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

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

tupleDivide

Введена в версии: v21.11

Выполняет деление соответствующих элементов двух кортежей одинакового размера.

Примечание

При делении на ноль возвращается значение 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)

Примеры

Базовое использование

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

(0.5, 0.6666666666666666)

tupleDivideByNumber

Впервые представлена в: v21.11

Возвращает кортеж, в котором каждый элемент делится на число.

Примечание

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

Синтаксис

tupleDivideByNumber(tuple, number)

Аргументы

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

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

Возвращает кортеж с разделёнными элементами. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Примеры

Базовое использование

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement

Впервые появилась в: v1.1

Извлекает элемент из кортежа по индексу или имени.

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

Поддерживаются отрицательные индексы. В этом случае выбирается соответствующий элемент, нумерация ведется с конца. Например, tuple.-1 — это последний элемент кортежа.

Необязательный третий аргумент задает значение по умолчанию, которое возвращается вместо выброса исключения, если запрашиваемый элемент не существует. Все аргументы должны быть константами.

Эта функция имеет нулевую стоимость выполнения и реализует операторы 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

Примеры

Доступ по индексу

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

hello

Отрицательные индексы

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

hello

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

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

Alice

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

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

not_found

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

SELECT (1, 'hello').2

hello

tupleHammingDistance

Добавлено в: v21.1

Возвращает расстояние Хэмминга между двумя кортежами одинакового размера.

Примечание

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

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

Примеры

Пример использования

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

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

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

tupleIntDiv

Введено в: v23.8

Выполняет целочисленное поэлементное деление кортежа числителей на кортеж знаменателей. Возвращает кортеж частных. Если какой-либо из кортежей содержит нецелочисленные элементы, результат вычисляется с округлением до ближайшего целого для каждого нецелочисленного числителя или делителя. Деление на 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)

Примеры

Базовое использование

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

(3, 2, 1)

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

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

(2, 1, 0)

tupleIntDivByNumber

Введено в: v23.8

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

Синтаксис

tupleIntDivByNumber(tuple_num, div)

Аргументы

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

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

Возвращает кортеж результатов деления. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Примеры

Базовое использование

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

(3, 2, 1)

Для десятичных значений

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

(2, 1, 0)

tupleIntDivOrZero

Введена в версии v23.8

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

Синтаксис

tupleIntDivOrZero(tuple_num, tuple_div)

Аргументы

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

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

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

Примеры

С нулевыми делителями

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

(0, 0, 0)

tupleIntDivOrZeroByNumber

Введено в: v23.8

Как и tupleIntDivByNumber, выполняет целочисленное деление кортежа числителей на заданный знаменатель и возвращает кортеж частных. Не вызывает ошибку при нулевом делителе, а вместо этого возвращает частное, равное нулю. Если кортеж числителей или делитель содержат нецелочисленные элементы, результат вычисляется путём округления до ближайшего целого для каждого нецелочисленного числителя или делителя.

Синтаксис

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)

Примеры

Базовый пример

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

(3, 2, 1)

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

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

(0, 0, 0)

tupleMinus

Добавлена в: v21.11

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

Синтаксис

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)

Примеры

Базовое использование

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

(-1, -1)

tupleModulo

Появилась в версии: v23.8

Возвращает кортеж остатков (модулей) поэлементного деления двух кортежей.

Синтаксис

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)

Примеры

Базовое использование

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

(0, 1, 1)

tupleModuloByNumber

Добавлена в версии: v23.8

Возвращает кортеж остатков от деления элементов кортежа на заданный делитель.

Синтаксис

tupleModuloByNumber(tuple_num, div)

Аргументы

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

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

Примеры

Базовое использование

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

(1, 0, 1)

tupleMultiply

Введено в версии: v21.11

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

Синтаксис

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)

Примеры

Базовое использование

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

(2, 6)

tupleMultiplyByNumber

Добавлена в версии: v21.11

Возвращает кортеж, в котором все элементы умножены на число.

Синтаксис

tupleMultiplyByNumber(tuple, number)

Аргументы

tuple — кортеж, который нужно умножить. Tuple((U)Int*) или Tuple(Float*) или Tuple(Decimal)
number — множитель. (U)Int* или Float* или Decimal

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

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

Примеры

Базовое использование

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

(-2.1, -4.2)

tupleNames

Добавлена в: v

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

Синтаксис

Аргументы

Нет

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

Примеры

Типичный пример

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

['a','b']

tupleNegate

Введена в версии v21.11

Вычисляет отрицание элементов кортежа.

Синтаксис

tupleNegate(t)

Аргументы

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

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

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

Примеры

Базовое использование

SELECT tupleNegate((1, 2))

(-1, -2)

tuplePlus

Добавлена в версии v21.11

Вычисляет сумму соответствующих элементов двух кортежей одинаковой длины.

Синтаксис

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)

Примеры

Базовое использование

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

(3, 5)

tupleToNameValuePairs

Впервые появился в: v21.9

Преобразует кортеж в массив пар (name, value). Например, кортеж 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))

Примеры

Именованный кортеж

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

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

Неименованный кортеж

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

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

untuple

Выполняет синтаксическую подстановку элементов tuple на месте вызова.

Имена результирующих столбцов зависят от реализации и могут изменяться. Не полагайтесь на конкретные имена столбцов после 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:

Запрос:

SELECT untuple(v6) FROM kv;

Результат:

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

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

Запрос:

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

Результат:

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

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

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

flattenTuple​

tuple​

tupleConcat​

tupleDivide​

tupleDivideByNumber​

tupleElement​

tupleHammingDistance​

tupleIntDiv​

tupleIntDivByNumber​

tupleIntDivOrZero​

tupleIntDivOrZeroByNumber​

tupleMinus​

tupleModulo​

tupleModuloByNumber​

tupleMultiply​

tupleMultiplyByNumber​

tupleNames​

tupleNegate​

tuplePlus​

tupleToNameValuePairs​

untuple​

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

flattenTuple

tuple

tupleConcat

tupleDivide

tupleDivideByNumber

tupleElement

tupleHammingDistance

tupleIntDiv

tupleIntDivByNumber

tupleIntDivOrZero

tupleIntDivOrZeroByNumber

tupleMinus

tupleModulo

tupleModuloByNumber

tupleMultiply

tupleMultiplyByNumber

tupleNames

tupleNegate

tuplePlus

tupleToNameValuePairs

untuple

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