Перейти к основному содержанию
Перейти к основному содержанию

Функции кортежей (Tuple)

Примечание

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

flattenTuple​

Впервые появилось в: v22.6

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

Синтаксис

расплющитьКортеж(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 или для создания списка формальных параметров лямбда-функций. Кортежи нельзя записывать в таблицу.

Функция реализует оператор (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)

Аргументы

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

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

Примеры

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

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

(0.5, 0.6666666666666666)

tupleDivideByNumber​

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

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

Примечание

При делении на ноль будет возвращено значение inf.

Синтаксис

tupleРазделитьНаЧисло(tuple, number)

Аргументы

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

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

Примеры

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

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement​

Введена в версии: v1.1

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

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

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

Эта функция не имеет накладных затрат во время выполнения и реализует операторы x.index и x.name.

Синтаксис

tupleElement(кортеж, индекс|имя[, значение_по_умолчанию])

Аргументы

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

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

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

Примеры

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

SELECT tupleElement((1, 'привет'), 2)

Здравствуйте

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

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

Алиса

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

SELECT tupleElement((1, 2), 5, 'не_найдено')

не найдено

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

SELECT (1, 'hello').2

Здравствуйте

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

2

Поиск почти дублирующихся строк с помощью MinHash

SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse — колоночная система управления базами данных для онлайн-аналитической обработки запросов.' AS string)

2

tupleIntDiv​

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

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

Синтаксис

tupleIntDiv(tuple_num, tuple_div)

Аргументы

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

Возвращает кортеж результатов деления. 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((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)

Аргументы

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

Возвращает кортеж результатов деления. Для делений, где знаменатель равен 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)

Аргументы

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

Возвращает кортеж результатов деления, где для элементов с делителем 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

Аргументы

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

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

Примеры

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

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

(-1, -1)

tupleModulo​

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

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

Синтаксис

tupleModulo(tuple_num, tuple_mod)

Аргументы

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

Возвращает кортеж остатков деления. При делении на ноль выдается ошибка. 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((U)Int*) или Tuple(Float*) или Tuple(Decimal)

Примеры

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

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

(1, 0, 1)

tupleMultiply​

Появилась в версии: v21.11

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

Синтаксис

tupleMultiply(t1, t2)

Аргументы

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

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

Примеры

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

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

(2, 6)

tupleMultiplyByNumber​

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

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

Синтаксис

tupleMultiplyByNumber(кортеж, число)

Аргументы

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

Возвращает кортеж с элементами, умноженными на заданный множитель. 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)

Аргументы

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

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

Примеры

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

SELECT tupleNegate((1, 2))

(-1, -2)

tuplePlus​

Появился в версии: v21.11

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

Синтаксис

tuplePlus(t1, t2)

Псевдонимы: vectorSum

Аргументы

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

Возвращает кортеж, содержащий суммы соответствующих элементов входных кортежей. 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)

Аргументы

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

Возвращает массив пар вида (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') │
└─────┴────┴────┴────┴───────────┘

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

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