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

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

Примечание

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

dotProduct​

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

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

Синтаксис

dotProduct(vector1, vector2)

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

Аргументы

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

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

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

Примеры

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

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

11

flattenTuple​

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

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

Синтаксис

flattenTuple(input)

Аргументы

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

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

Впервые представлена в: v1.1.0

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

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

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

Синтаксис

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

Аргументы

  • Нет.

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

Примеры

Типичный

SELECT tuple(1, 2)

(1,2)

tupleConcat​

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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

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

tupleDivide​

Добавленный в: v21.11.0

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

Примечание

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

Синтаксис

tupleDivide(t1, t2[, tN, ...])

Аргументы

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

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

Примеры

Два кортежа

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

(0.5, 0.6666666666666666)

Три Tuple

SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))

(10, 5)

tupleDivideByNumber​

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

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

Примечание

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

Синтаксис

tupleDivideByNumber(tuple, number)

Аргументы

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

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

Примеры

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

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement​

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

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

Для доступа по индексу используется числовой индекс, начинающийся с 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.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

Примеры

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

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

2

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

2

tupleIntDiv​

Добавленный в: v23.8.0

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

Синтаксис

tupleIntDiv(t1, t2[, tN, ...])

Аргументы

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

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

Примеры

Два Tuple

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)

Три Tuple

SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))

(15, 5)

tupleIntDivByNumber​

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

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

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

Синтаксис

tupleIntDivOrZero(t1, t2[, tN, ...])

Аргументы

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

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

Примеры

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

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

(0, 0, 0)

Три Tuple

SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))

(15, 5)

tupleIntDivOrZeroByNumber​

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

Как и 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.0

Вычисляет поэлементную разность двух или более Tuple одинакового размера; операция применяется слева направо.

Синтаксис

tupleMinus(t1, t2[, tN, ...])

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

Аргументы

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

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

Примеры

Два кортежа

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

(-1, -1)

Три Tuple

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

(5, 5)

tupleModulo​

Добавленный в: v23.8.0

Возвращает Tuple с поэлементными остатками от деления двух или более Tuple одинакового размера; операция выполняется слева направо.

Синтаксис

tupleModulo(t1, t2[, tN, ...])

Аргументы

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

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

Примеры

Два кортежа

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

(0, 1, 1)

Три Tuple

SELECT tupleModulo((10, 20), (7, 9), (3, 5))

(0, 2)

tupleModuloByNumber​

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

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

Синтаксис

tupleModuloByNumber(tuple_num, div)

Аргументы

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

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

Примеры

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

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

(1, 0, 1)

tupleMultiply​

Добавленный в: v21.11.0

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

Синтаксис

tupleMultiply(t1, t2[, tN, ...])

Аргументы

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

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

Примеры

Два кортежа

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

(2, 6)

Три Tuple

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

(2, 12)

tupleMultiplyByNumber​

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

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

Синтаксис

tupleMultiplyByNumber(tuple, number)

Аргументы

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

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

Примеры

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

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

(-2.1, -4.2)

tupleNames​

Добавлена в: v24.8.0

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

Синтаксис

tupleNames(tuple)

Аргументы

  • Нет

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

Примеры

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

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

['a','b']

tupleNegate​

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

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

Синтаксис

tupleNegate(t)

Аргументы

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

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

Примеры

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

SELECT tupleNegate((1, 2))

(-1, -2)

tuplePlus​

Добавленный в: v21.11.0

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

Синтаксис

tuplePlus(t1, t2[, tN, ...])

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

Аргументы

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

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

Примеры

Два кортежа

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

(3, 5)

Три Tuple

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

(6, 9)

tuplePositiveModuloByNumber​

Добавлено в: v26.4.0

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

Синтаксис

tuplePositiveModuloByNumber(tuple_num, div)

Аргументы

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

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

Примеры

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

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

(1, 0, 1)

tupleToNameValuePairs​

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

Преобразует кортеж в массив пар (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') │
└─────┴────┴────┴────┴───────────┘

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

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