Другие функции

hostName

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

Синтаксис

hostName()

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

Имя хоста. String.

getMacro

Возвращает именованное значение из секции macros конфигурации сервера.

Синтаксис

getMacro(name);

Аргументы

name — Имя макроса, которое нужно получить из секции <macros>. String.

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

Значение указанного макроса. String.

Пример

Пример секции <macros> в файле конфигурации сервера:

<macros>
    <test>Value</test>
</macros>

Запрос:

SELECT getMacro('test');

Результат:

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

То же самое значение можно получить следующим образом:

SELECT * FROM system.macros
WHERE macro = 'test';

┌─macro─┬─substitution─┐
│ test  │ Value        │
└───────┴──────────────┘

fqdn

Возвращает полностью квалифицированное доменное имя сервера ClickHouse.

Синтаксис

fqdn();

Псевдонимы: fullHostName, FQDN.

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

Строка с полностью квалифицированным доменным именем. String.

Пример

SELECT FQDN();

Результат:

┌─FQDN()──────────────────────────┐
│ clickhouse.ru-central1.internal │
└─────────────────────────────────┘

basename

Извлекает часть строки после последнего слэша или обратного слэша. Эта функция часто используется для извлечения имени файла из пути.

basename(expr)

Аргументы

expr — Значение типа String. Обратные слэши должны быть экранированы.

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

Строка, содержащая:

Конец входной строки после последнего слэша или обратного слэша. Если входная строка заканчивается слэшем или обратным слэшем (например, / или c:\), функция возвращает пустую строку.
Исходная строка, если слэшей или обратных слэшей нет.

Пример

Запрос:

SELECT 'some/long/path/to/file' AS a, basename(a)

Результат:

┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file                                   │
└────────────────────────┴────────────────────────────────────────┘

Запрос:

SELECT 'some\\long\\path\\to\\file' AS a, basename(a)

Результат:

┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file                                   │
└────────────────────────┴────────────────────────────────────────┘

Запрос:

SELECT 'some-file-name' AS a, basename(a)

Результат:

┌─a──────────────┬─basename('some-file-name')─┐
│ some-file-name │ some-file-name             │
└────────────────┴────────────────────────────┘

visibleWidth

Вычисляет приблизительную ширину при выводе значений на консоль в текстовом формате (разделённом табуляцией). Эта функция используется системой для реализации Pretty форматов.

NULL представлен как строка, соответствующая NULL в Pretty форматах.

Синтаксис

visibleWidth(x)

Пример

Запрос:

SELECT visibleWidth(NULL)

Результат:

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

toTypeName

Возвращает имя типа переданного аргумента.

Если передан NULL, функция возвращает тип Nullable(Nothing), который соответствует внутреннему представлению NULL в ClickHouse.

Синтаксис

toTypeName(value)

Аргументы

value — Значение произвольного типа.

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

Имя типа данных входного значения. String.

Пример

Запрос:

SELECT toTypeName(123);

Результат:

┌─toTypeName(123)─┐
│ UInt8           │
└─────────────────┘

blockSize

В ClickHouse запросы обрабатываются в блоках (чанках). Эта функция возвращает размер (количество строк) блока, на котором была вызвана функция.

Синтаксис

blockSize()

Пример

Запрос:

DROP TABLE IF EXISTS test;
CREATE TABLE test (n UInt8) ENGINE = Memory;

INSERT INTO test
SELECT * FROM system.numbers LIMIT 5;

SELECT blockSize()
FROM test;

Результат:

   ┌─blockSize()─┐
1. │           5 │
2. │           5 │
3. │           5 │
4. │           5 │
5. │           5 │
   └─────────────┘

byteSize

Возвращает оценку не сжатого объёма памяти своих аргументов.

Синтаксис

byteSize(argument [, ...])

Аргументы

argument — Значение.

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

Оценка объёма памяти аргументов. UInt64.

Примеры

Для String аргументов функция возвращает длину строки + 9 (терминальный ноль + длина).

Запрос:

SELECT byteSize('string');

Результат:

┌─byteSize('string')─┐
│                 15 │
└────────────────────┘

Запрос:

CREATE TABLE test
(
    `key` Int32,
    `u8` UInt8,
    `u16` UInt16,
    `u32` UInt32,
    `u64` UInt64,
    `i8` Int8,
    `i16` Int16,
    `i32` Int32,
    `i64` Int64,
    `f32` Float32,
    `f64` Float64
)
ENGINE = MergeTree
ORDER BY key;

INSERT INTO test VALUES(1, 8, 16, 32, 64,  -8, -16, -32, -64, 32.32, 64.64);

SELECT key, byteSize(u8) AS `byteSize(UInt8)`, byteSize(u16) AS `byteSize(UInt16)`, byteSize(u32) AS `byteSize(UInt32)`, byteSize(u64) AS `byteSize(UInt64)`, byteSize(i8) AS `byteSize(Int8)`, byteSize(i16) AS `byteSize(Int16)`, byteSize(i32) AS `byteSize(Int32)`, byteSize(i64) AS `byteSize(Int64)`, byteSize(f32) AS `byteSize(Float32)`, byteSize(f64) AS `byteSize(Float64)` FROM test ORDER BY key ASC FORMAT Vertical;

Результат:

Row 1:
──────
key:               1
byteSize(UInt8):   1
byteSize(UInt16):  2
byteSize(UInt32):  4
byteSize(UInt64):  8
byteSize(Int8):    1
byteSize(Int16):   2
byteSize(Int32):   4
byteSize(Int64):   8
byteSize(Float32): 4
byteSize(Float64): 8

Если у функции несколько аргументов, она накапливает их объёмы.

Запрос:

SELECT byteSize(NULL, 1, 0.3, '');

Результат:

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         19 │
└────────────────────────────┘

materialize

Превращает константу в полноценную колонку, содержащую одно значение. Полные колонки и константы представлены по-разному в памяти. Функции обычно выполняют разный код для нормальных и постоянных аргументов, хотя результат обычно должен быть одинаковым. Эта функция может использоваться для отладки этого поведения.

Синтаксис

materialize(x)

Параметры

x — Константа. Constant.

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

Колонка, содержащая единственное значение x.

Пример

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

Запрос:

SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));

Результат:

2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String

ignore

Принимает произвольные аргументы и безусловно возвращает 0. Аргумент всё ещё оценивается внутренне, что делает его полезным, например, для бенчмаркинга.

Синтаксис

ignore([arg1[, arg2[, ...]])

Аргументы

Принимает произвольное количество аргументов произвольного типа, включая NULL.

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

Возвращает 0.

Пример

Запрос:

SELECT ignore(0, 'ClickHouse', NULL);

Результат:

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

sleep

Используется для вступления задержки или паузы в выполнение запроса. Основное назначение — тестирование и отладка.

Синтаксис

sleep(seconds)

Аргументы

seconds: UInt* или Float Количество секунд, на которое нужно приостановить выполнение запроса, максимум 3 секунды. Это может быть дробное значение для указания долей секунды.

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

Эта функция ничего не возвращает.

Пример

SELECT sleep(2);

Эта функция ничего не возвращает. Однако, если вы выполните функцию с помощью clickhouse client, вы увидите что-то похожее на:

SELECT sleep(2)

Query id: 8aa9943e-a686-45e1-8317-6e8e3a5596ac

┌─sleep(2)─┐
│        0 │
└──────────┘

1 row in set. Elapsed: 2.012 sec.

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

Детали реализации

Функция sleep() обычно не используется в производственных средах, так как она может негативно повлиять на производительность запросов и отзывчивость системы. Однако она может быть полезна в следующих сценариях:

Тестирование: При тестировании или бенчмаркинге ClickHouse может возникнуть необходимость симулировать задержки или вводить паузы, чтобы наблюдать за поведением системы при определённых условиях.
Отладка: Если нужно проверить состояние системы или выполнение запроса в определённый момент времени, вы можете использовать sleep() для введения паузы, позволяющей вам собирать или наблюдать за соответствующей информацией.
Симуляция: В некоторых случаях вы можете захотеть смоделировать сценарии из реальной жизни, где возникают задержки или паузы, такие как сетевые задержки или внешние зависимости систем.

Важно использовать функцию sleep() разумно и только в случае необходимости, так как она может негативно повлиять на общую производительность и отзывчивость вашей системы ClickHouse.

sleepEachRow

Приостанавливает выполнение запроса на определённое количество секунд для каждой строки в результирующем наборе.

Синтаксис

sleepEachRow(seconds)

Аргументы

seconds: UInt* или Float* Количество секунд, на которое нужно приостановить выполнение запроса для каждой строки в результирующем наборе, максимум 3 секунды. Это может быть дробное значение для указания долей секунды.

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

Эта функция возвращает те же входные значения, что и получает, не изменяя их.

Пример

SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

┌─number─┬─sleepEachRow(0.5)─┐
│      0 │                 0 │
│      1 │                 0 │
│      2 │                 0 │
│      3 │                 0 │
│      4 │                 0 │
└────────┴───────────────────┘

Однако вывод будет отсрочен, с паузой в 0.5 секунды между каждой строкой.

Функция sleepEachRow() используется в основном для тестирования и отладки, как и функция sleep(). Она позволяет вам смоделировать задержки или вводить паузы в обработку каждой строки, что может быть полезным в таких сценариях, как:

Тестирование: При тестировании или бенчмаркинге производительности ClickHouse при определённых условиях вы можете использовать sleepEachRow() для моделирования задержек или ввода пауз для каждой обрабатываемой строки.
Отладка: Если вам нужно изучить состояние системы или выполнение запроса для каждой обрабатываемой строки, вы можете использовать sleepEachRow(), чтобы ввести паузы, позволяя вам собирать или проверять соответствующую информацию.
Симуляция: В некоторых случаях вы можете захотеть смоделировать сценарии из реальной жизни, где задержки или паузы происходят для каждой обрабатываемой строки, например, при взаимодействии с внешними системами или сетевыми задержками.

Как и функция sleep(), важно использовать sleepEachRow() разумно и только в случае необходимости, так как это может значительно повлиять на общую производительность и отзывчивость вашей системы ClickHouse, особенно при работе с большими наборами результатов.

currentDatabase

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

Синтаксис

currentDatabase()

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

Возвращает имя текущей базы данных. String.

Пример

Запрос:

SELECT currentDatabase()

Результат:

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

currentUser

Возвращает имя текущего пользователя. В случае распределённого запроса возвращается имя пользователя, инициировавшего запрос.

Синтаксис

currentUser()

Псевдонимы: user(), USER(), current_user(). Псевдонимы нечувствительны к регистру.

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

Имя текущего пользователя. String.
В распределённых запросах — логин пользователя, инициировавшего запрос. String.

Пример

SELECT currentUser();

Результат:

┌─currentUser()─┐
│ default       │
└───────────────┘

currentSchemas

Возвращает массив с единственным элементом с именем текущей схемы базы данных.

Синтаксис

currentSchemas(bool)

Псевдоним: current_schemas.

Аргументы

bool: логическое значение. Bool.

примечание

Логический аргумент игнорируется. Он существует только для совместимости с реализацией этой функции в PostgreSQL.

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

Возвращает массив с единственным элементом — именем текущей базы данных.

Пример

SELECT currentSchemas(true);

Результат:

['default']

isConstant

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

Константное выражение — это выражение, результат которого известен во время анализа запроса, то есть до выполнения. Например, выражения по литералам являются константными выражениями.

Эта функция в основном предназначена для разработки, отладки и демонстрации.

Синтаксис

isConstant(x)

Аргументы

x — Выражение для проверки.

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

1, если x является константой. UInt8.
0, если x является неконстантным. UInt8.

Примеры

Запрос:

SELECT isConstant(x + 1) FROM (SELECT 43 AS x)

Результат:

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

Запрос:

WITH 3.14 AS pi SELECT isConstant(cos(pi))

Результат:

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

Запрос:

SELECT isConstant(number) FROM numbers(1)

Результат:

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

hasColumnInTable

Учитывая имя базы данных, имя таблицы и имя колонки как константные строки, возвращает 1, если данная колонка существует, иначе 0.

Синтаксис

hasColumnInTable(\['hostname'\[, 'username'\[, 'password'\]\],\] 'database', 'table', 'column')

Параметры

database : имя базы данных. String literal
table : имя таблицы. String literal
column : имя колонки. String literal
hostname : имя удалённого сервера для проверки. String literal
username : имя пользователя для удалённого сервера. String literal
password : пароль для удалённого сервера. String literal

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

1, если данная колонка существует.
0, в противном случае.

Детали реализации

Для элементов в вложенной структуре данных функция проверяет существование колонки. Для самой вложенной структуры данных функция возвращает 0.

Пример

Запрос:

SELECT hasColumnInTable('system','metrics','metric')

SELECT hasColumnInTable('system','metrics','non-existing_column')

hasThreadFuzzer

Возвращает, эффективно ли работает Thread Fuzzer. Может использоваться в тестах, чтобы предотвратить длительное выполнение.

Синтаксис

hasThreadFuzzer();

bar

Строит гистограмму.

bar(x, min, max, width) рисует полосу с шириной, пропорциональной (x - min) и равной width символов, когда x = max.

Аргументы

x — Размер для отображения.
min, max — Целые константы. Значение должно помещаться в Int64.
width — Константа, положительное целое число, может быть дробным.

Полоса рисуется с точностью до одной восьмой символа.

Пример:

SELECT
    toHour(EventTime) AS h,
    count() AS c,
    bar(c, 0, 600000, 20) AS bar
FROM test.hits
GROUP BY h
ORDER BY h ASC

┌──h─┬──────c─┬─bar────────────────┐
│  0 │ 292907 │ █████████▋         │
│  1 │ 180563 │ ██████             │
│  2 │ 114861 │ ███▋               │
│  3 │  85069 │ ██▋                │
│  4 │  68543 │ ██▎                │
│  5 │  78116 │ ██▌                │
│  6 │ 113474 │ ███▋               │
│  7 │ 170678 │ █████▋             │
│  8 │ 278380 │ █████████▎         │
│  9 │ 391053 │ █████████████      │
│ 10 │ 457681 │ ███████████████▎   │
│ 11 │ 493667 │ ████████████████▍  │
│ 12 │ 509641 │ ████████████████▊  │
│ 13 │ 522947 │ █████████████████▍ │
│ 14 │ 539954 │ █████████████████▊ │
│ 15 │ 528460 │ █████████████████▌ │
│ 16 │ 539201 │ █████████████████▊ │
│ 17 │ 523539 │ █████████████████▍ │
│ 18 │ 506467 │ ████████████████▊  │
│ 19 │ 520915 │ █████████████████▎ │
│ 20 │ 521665 │ █████████████████▍ │
│ 21 │ 542078 │ ██████████████████ │
│ 22 │ 493642 │ ████████████████▍  │
│ 23 │ 400397 │ █████████████▎     │
└────┴────────┴────────────────────┘

transform

Преобразует значение в соответствии с явно определённым сопоставлением некоторых элементов с другими. Существует два варианта этой функции:

transform(x, array_from, array_to, default)

x – Что трансформировать.

array_from – Константный массив значений для преобразования.

array_to – Константный массив значений для преобразования значений из from.

default – Какое значение использовать, если x не равно никакому из значений в from.

array_from и array_to должны содержать одинаковое количество элементов.

Подпись:

Для x, равного одному из элементов в array_from, функция возвращает соответствующий элемент в array_to, то есть тот, который находится на том же индексе массива. В противном случае возвращается default. Если в array_from существует несколько совпадающих элементов, возвращается элемент, соответствующий первому из них.

transform(T, Array(T), Array(U), U) -> U

T и U могут быть числовыми, строковыми, или типов Date или DateTime. Та же буква (T или U) означает, что типы должны быть совместимыми, но не обязательно одинаковыми. Например, первым аргументом может быть тип Int64, в то время как вторым аргументом может быть тип Array(UInt16).

Пример:

SELECT
    transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
    count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC

┌─title─────┬──────c─┐
│ Yandex    │ 498635 │
│ Google    │ 229872 │
│ Other     │ 104472 │
└───────────┴────────┘

transform(x, array_from, array_to)

Аналогично другому варианту, но не имеет аргумента default. Если сопоставление не может быть найдено, возвращается x.

Пример:

SELECT
    transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s,
    count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10

┌─s──────────────┬───────c─┐
│                │ 2906259 │
│ www.yandex     │  867767 │
│ ███████.ru     │  313599 │
│ mail.yandex.ru │  107147 │
│ ██████.ru      │  100355 │
│ █████████.ru   │   65040 │
│ news.yandex.ru │   64515 │
│ ██████.net     │   59141 │
│ example.com    │   57316 │
└────────────────┴─────────┘

formatReadableDecimalSize

Учитывая размер (количество байт), эта функция возвращает читаемый, округленный размер с суффиксом (КБ, МБ и т.д.) в виде строки.

Обратные операции для этой функции — parseReadableSize, parseReadableSizeOrZero и parseReadableSizeOrNull.

Синтаксис

formatReadableDecimalSize(x)

Пример

Запрос:

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

Результат:

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.02 KB   │
│        1048576 │ 1.05 MB   │
│      192851925 │ 192.85 MB │
└────────────────┴────────────┘

formatReadableSize

Учитывая размер (количество байт), эта функция возвращает читаемый, округленный размер с суффиксом (КиБ, МиБ и т.д.) в виде строки.

Обратные операции для этой функции — parseReadableSize, parseReadableSizeOrZero и parseReadableSizeOrNull.

Синтаксис

formatReadableSize(x)

Псевдоним: FORMAT_BYTES.

примечание

Эта функция принимает любой числовой тип в качестве входа, но внутренне они преобразуются в Float64. Результаты могут быть не оптимальными для больших значений.

Пример

Запрос:

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

Результат:

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

formatReadableQuantity

Учитывая число, эта функция возвращает округлённое число с суффиксом (тысяча, миллион, миллиард и т.д.) в виде строки.

Синтаксис

formatReadableQuantity(x)

примечание

Пример

Запрос:

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

Результат:

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

formatReadableTimeDelta

Учитывая временной интервал (дельту) в секундах, эта функция возвращает временную дельту с годом/месяцем/днем/часом/минутой/секундой/миллисекундой/микросекундой/наносекундой в виде строки.

Синтаксис

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

примечание

Аргументы

column — Колонка с числовой временной дельтой.
maximum_unit — Необязательно. Максимальная единица для отображения.
- Допустимые значения: наносекунды, микросекунды, миллисекунды, секунды, минуты, часы, дни, месяцы, годы.
- Значение по умолчанию: годы.
minimum_unit — Необязательно. Минимальная единица для отображения. Все меньшие единицы обрезаются.
- Допустимые значения: наносекунды, микросекунды, миллисекунды, секунды, минуты, часы, дни, месяцы, годы.
- Если явно указываемое значение больше, чем maximum_unit, выдается исключение.
- Значение по умолчанию: секунды, если maximum_unit — секунды или больше, наносекунды в противном случае.

Пример

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

┌────elapsed─┬─time_delta ─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                         │
│      12345 │ 3 hours, 25 minutes and 45 seconds                              │
│  432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds │
└────────────┴─────────────────────────────────────────────────────────────────┘

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

┌────elapsed─┬─time_delta ─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                         │
│      12345 │ 205 minutes and 45 seconds                                      │
│  432546534 │ 7209108 minutes and 54 seconds                                  │
└────────────┴─────────────────────────────────────────────────────────────────┘

SELECT
    arrayJoin([100, 12345, 432546534.00000006]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes', 'nanoseconds') AS time_delta

┌────────────elapsed─┬─time_delta─────────────────────────────────────┐
│                100 │ 1 minute and 40 seconds                        │
│              12345 │ 205 minutes and 45 seconds                     │
│ 432546534.00000006 │ 7209108 minutes, 54 seconds and 60 nanoseconds │
└────────────────────┴────────────────────────────────────────────────┘

parseReadableSize

Учитывая строку, содержащую размер байтов и B, KiB, KB, MiB, MB и т.д. в качестве единицы (т.е. ISO/IEC 80000-13 или десятичная единица байта), эта функция возвращает соответствующее количество байтов.
Если функция не может разобрать входное значение, она выдаёт исключение.

Обратные операции для этой функции — formatReadableSize и formatReadableDecimalSize.

Синтаксис

parseReadableSize(x)

Аргументы

x : Читаемый размер с единицей байта по ISO/IEC 80000-13 или десятичной единицы байта (String).

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

Количество байт, округлённое до ближайшего целого числа (UInt64).

Пример

SELECT
    arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes,  
    parseReadableSize(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

parseReadableSizeOrNull

Обратные операции для этой функции — formatReadableSize и formatReadableDecimalSize.

Синтаксис

parseReadableSizeOrNull(x)

Аргументы

x : Читаемый размер с единицей байта по ISO/IEC 80000-13 или десятичной единицы байта (String).

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

Количество байтов, округленное до ближайшего целого числа, или NULL, если разбор входного значения не удался (Nullable(UInt64)).

Пример

SELECT
    arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes,  
    parseReadableSizeOrNull(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

parseReadableSizeOrZero

Учитывая строку, содержащую размер байтов и B, KiB, KB, MiB, MB и т.д. в качестве единицы (т.е. ISO/IEC 80000-13 или десятичная единица байта), эта функция возвращает соответствующее количество байтов. Если функция не может разобрать входное значение, она возвращает 0.

Обратные операции для этой функции — formatReadableSize и formatReadableDecimalSize.

Синтаксис

parseReadableSizeOrZero(x)

Аргументы

x : Читаемый размер с единицей байта по ISO/IEC 80000-13 или десятичной единицы байта (String).

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

Количество байт, округленное до ближайшего целого числа, или 0, если разбор входного значения не удался (UInt64).

Пример

SELECT
    arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes,  
    parseReadableSizeOrZero(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

title: 'Функции ClickHouse'
sidebar_label: 'Функции ClickHouse'
keywords: ['функции', 'ClickHouse', 'база данных']
description: 'Описание различных функций в ClickHouse для работы с данными и агрегациями.'

parseTimeDelta

Разбирает последовательность чисел, за которой следует что-то, напоминающее единицу времени.

Синтаксис

parseTimeDelta(timestr)

Аргументы

timestr — Последовательность чисел, за которой следует что-то, напоминающее единицу времени.

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

Число с плавающей запятой, представляющее количество секунд.

Пример

SELECT parseTimeDelta('11s+22min')

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

SELECT parseTimeDelta('1yr2mo')

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

least

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

Синтаксис

least(a, b)

примечание

Версия 24.12 ввела изменения, несовместимые с предыдущими версиями, так что значения NULL игнорируются, в то время как раньше возвращалось NULL, если один из аргументов был NULL. Чтобы сохранить предыдущее поведение, установите настройку least_greatest_legacy_null_behavior (по умолчанию: false) в true.

greatest

Возвращает наибольшее значение из одного или нескольких входных аргументов. Аргументы NULL игнорируются.

Синтаксис

greatest(a, b)

примечание

uptime

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

Синтаксис

uptime()

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

Значение времени в секундах. UInt32.

Пример

Запрос:

SELECT uptime() as Uptime;

Результат:

┌─Uptime─┐
│  55867 │
└────────┘

version

Возвращает текущую версию ClickHouse в виде строки в формате:

Основная версия
Минимальная версия
Версия исправлений
Количество коммитов с момента последнего стабильного релиза.

major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release

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

Синтаксис

version()

Аргументы

Нет.

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

Текущая версия ClickHouse. String.

Детали реализации

Нет.

Пример

Запрос:

SELECT version()

Результат:

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

buildId

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

Синтаксис

buildId()

blockNumber

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

Синтаксис

blockNumber()

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

Последовательный номер блока данных, в котором находится строка. UInt64.

Пример

Запрос:

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

Результат:

┌─blockNumber()─┐
│             7 │
│             7 │
└───────────────┘
┌─blockNumber()─┐
│             8 │
│             8 │
└───────────────┘
┌─blockNumber()─┐
│             9 │
│             9 │
└───────────────┘
┌─blockNumber()─┐
│            10 │
│            10 │
└───────────────┘
┌─blockNumber()─┐
│            11 │
│            11 │
└───────────────┘

rowNumberInBlock

Возвращает для каждого блока, обрабатываемого rowNumberInBlock, номер текущей строки. Возвращаемый номер начинается с 0 для каждого блока.

Синтаксис

rowNumberInBlock()

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

Порядковый номер строки в блоке данных, начиная с 0. UInt64.

Пример

Запрос:

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

Результат:

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘

rowNumberInAllBlocks

Возвращает уникальный номер строки для каждой строки, обработанной rowNumberInAllBlocks. Возвращаемые номера начинаются с 0.

Синтаксис

rowNumberInAllBlocks()

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

Порядковый номер строки в блоке данных, начиная с 0. UInt64.

Пример

Запрос:

SELECT rowNumberInAllBlocks()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
)
SETTINGS max_block_size = 2

Результат:

┌─rowNumberInAllBlocks()─┐
│                      0 │
│                      1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      4 │
│                      5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      2 │
│                      3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      6 │
│                      7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      8 │
│                      9 │
└────────────────────────┘

normalizeQuery

Заменяет литералы, последовательности литералов и сложные алиасы (содержащие пробелы, более двух цифр или длиной не менее 36 байт, такие как UUID) на плейсхолдер ?.

Синтаксис

normalizeQuery(x)

Аргументы

x — Последовательность символов. String.

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

Последовательность символов с плейсхолдерами. String.

Пример

Запрос:

SELECT normalizeQuery('[1, 2, 3, x]') AS query;

Результат:

┌─query────┐
│ [?.., x] │
└──────────┘

normalizeQueryKeepNames

Заменяет литералы, последовательности литералов на плейсхолдер ?, но не заменяет сложные алиасы (содержащие пробелы, более двух цифр или длиной не менее 36 байт, такие как UUID). Это помогает лучше анализировать сложные журналы запросов.

Синтаксис

normalizeQueryKeepNames(x)

Аргументы

x — Последовательность символов. String.

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

Последовательность символов с плейсхолдерами. String.

Пример

Запрос:

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123');

Результат:

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

normalizedQueryHash

Возвращает идентичные 64-разрядные хэш-значения без значений литералов для схожих запросов. Может быть полезным для анализа журналов запросов.

Синтаксис

normalizedQueryHash(x)

Аргументы

x — Последовательность символов. String.

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

Хэш-значение. UInt64.

Пример

Запрос:

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res;

Результат:

┌─res─┐
│   1 │
└─────┘

normalizedQueryHashKeepNames

Как normalizedQueryHash, возвращает идентичные 64-разрядные хэш-значения без значений литералов для схожих запросов, но не заменяет сложные алиасы (содержащие пробелы, более двух цифр или длиной не менее 36 байт, такие как UUID) на плейсхолдер перед хешированием. Может быть полезным для анализа журналов запросов.

Синтаксис

normalizedQueryHashKeepNames(x)

Аргументы

x — Последовательность символов. String.

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

Хэш-значение. UInt64.

Пример

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

Результат:

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

neighbor

Deprecated feature

Оконная функция, которая предоставляет доступ к строке с указанным смещением перед или после текущей строки данного столбца.

Синтаксис

neighbor(column, offset[, default_value])

Результат функции зависит от затронутых блоков данных и порядка данных в блоке.

примечание

Возвращает соседей только внутри обрабатываемого блока данных. Из-за этого ошибочного поведения функция считается УСТАРЕВШЕЙ; пожалуйста, используйте правильные оконные функции вместо этого.

Порядок строк во время вычисления neighbor() может отличаться от порядка строк, возвращенных пользователю. Чтобы избежать этого, вы можете создать подзапрос с ORDER BY и вызвать функцию из вне подзапроса.

Аргументы

column — Имя колонки или скалярное выражение.
offset — Количество строк для просмотра перед или после текущей строки в column. Int64.
default_value — Необязательный. Возвращаемое значение, если смещение превышает границы блока. Тип данных аффектируемых блоков данных.

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

Значение column на расстоянии offset от текущей строки, если offset не выходит за границы блока.
Значение по умолчанию из column или default_value (если указано), если offset находится за пределами границ блока.

примечание

Тип возвращаемого значения будет соответствовать типу данных аффектируемых блоков или типу значения по умолчанию.

Пример

Запрос:

SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

Результат:

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

Запрос:

SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

Результат:

┌─number─┬─neighbor(number, 2, 999)─┐
│      0 │                        2 │
│      1 │                        3 │
│      2 │                        4 │
│      3 │                        5 │
│      4 │                        6 │
│      5 │                        7 │
│      6 │                        8 │
│      7 │                        9 │
│      8 │                      999 │
│      9 │                      999 │
└────────┴──────────────────────────┘

Эту функцию можно использовать для вычисления показателя за год:

Запрос:

WITH toDate('2018-01-01') AS start_date
SELECT
    toStartOfMonth(start_date + (number * 32)) AS month,
    toInt32(month) % 100 AS money,
    neighbor(money, -12) AS prev_year,
    round(prev_year / money, 2) AS year_over_year
FROM numbers(16)

Результат:

┌──────month─┬─money─┬─prev_year─┬─year_over_year─┐
│ 2018-01-01 │    32 │         0 │              0 │
│ 2018-02-01 │    63 │         0 │              0 │
│ 2018-03-01 │    91 │         0 │              0 │
│ 2018-04-01 │    22 │         0 │              0 │
│ 2018-05-01 │    52 │         0 │              0 │
│ 2018-06-01 │    83 │         0 │              0 │
│ 2018-07-01 │    13 │         0 │              0 │
│ 2018-08-01 │    44 │         0 │              0 │
│ 2018-09-01 │    75 │         0 │              0 │
│ 2018-10-01 │     5 │         0 │              0 │
│ 2018-11-01 │    36 │         0 │              0 │
│ 2018-12-01 │    66 │         0 │              0 │
│ 2019-01-01 │    97 │        32 │           0.33 │
│ 2019-02-01 │    28 │        63 │           2.25 │
│ 2019-03-01 │    56 │        91 │           1.62 │
│ 2019-04-01 │    87 │        22 │           0.25 │
└────────────┴───────┴───────────┴────────────────┘

runningDifference

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

примечание

Возвращает различия только внутри обрабатываемого блока данных. Из-за этого ошибочного поведения функция считается УСТАРЕВШЕЙ; пожалуйста, используйте правильные оконные функции вместо этого.

Результат функции зависит от затронутых блоков данных и порядка данных в блоке.

Порядок строк во время вычисления runningDifference() может отличаться от порядка строк, возвращенных пользователю. Чтобы избежать этого, вы можете создать подзапрос с ORDER BY и вызвать функцию из вне подзапроса.

Синтаксис

runningDifference(x)

Пример

Запрос:

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2016-11-24'
    ORDER BY EventTime ASC
    LIMIT 5
)

Результат:

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2016-11-24 00:00:04 │     0 │
│    1107 │ 2016-11-24 00:00:05 │     1 │
│    1108 │ 2016-11-24 00:00:05 │     0 │
│    1109 │ 2016-11-24 00:00:09 │     4 │
│    1110 │ 2016-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

Обратите внимание, что размер блока влияет на результат. Внутреннее состояние runningDifference сбрасывается для каждого нового блока.

Запрос:

SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1

Результат:

┌─number─┬─diff─┐
│      0 │    0 │
└────────┴──────┘
┌─number─┬─diff─┐
│  65536 │    0 │
└────────┴──────┘

Запрос:

set max_block_size=100000 -- default value is 65536!

SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1

Результат:

┌─number─┬─diff─┐
│      0 │    0 │
└────────┴──────┘

runningDifferenceStartingWithFirstValue

примечание

Эта функция УСТАРЕЛА (см. примечание к runningDifference).

То же самое, что и runningDifference, но возвращает значение первой строки как значение первой строки.

runningConcurrency

Вычисляет количество одновременных событий. Каждое событие имеет время начала и время окончания. Время начала включается в событие, тогда как время окончания исключается. Столбцы с временем начала и временем окончания должны быть одного и того же типа данных. Функция вычисляет общее количество активных (одновременных) событий для каждого времени начала события.

подсказка

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

Синтаксис

runningConcurrency(start, end)

Аргументы

start — Столбец с временем начала событий. Date, DateTime или DateTime64.
end — Столбец с временем окончания событий. Date, DateTime или DateTime64.

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

Количество одновременных событий на каждое время начала события. UInt32

Пример

Рассмотрим таблицу:

┌──────start─┬────────end─┐
│ 2021-03-03 │ 2021-03-11 │
│ 2021-03-06 │ 2021-03-12 │
│ 2021-03-07 │ 2021-03-08 │
│ 2021-03-11 │ 2021-03-12 │
└────────────┴────────────┘

Запрос:

SELECT start, runningConcurrency(start, end) FROM example_table;

Результат:

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2021-03-03 │                              1 │
│ 2021-03-06 │                              2 │
│ 2021-03-07 │                              3 │
│ 2021-03-11 │                              2 │
└────────────┴────────────────────────────────┘

MACNumToString

Интерпретирует число UInt64 как MAC-адрес в формате big endian. Возвращает соответствующий MAC-адрес в формате AA:BB:CC:DD:EE:FF (числа в шестнадцатеричном формате, разделенные двоеточиями) в виде строки.

Синтаксис

MACNumToString(num)

MACStringToNum

Обратная функция MACNumToString. Если MAC-адрес имеет недопустимый формат, возвращает 0.

Синтаксис

MACStringToNum(s)

MACStringToOUI

Учитывая MAC-адрес в формате AA:BB:CC:DD:EE:FF (числа в шестнадцатеричном формате, разделенные двоеточиями), возвращает первые три октета как число UInt64. Если у MAC-адреса недопустимый формат, возвращает 0.

Синтаксис

MACStringToOUI(s)

getSizeOfEnumType

Возвращает количество полей в Enum. Исключение выбрасывается, если тип не Enum.

Синтаксис

getSizeOfEnumType(value)

Аргументы:

value — Значение типа Enum.

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

Количество полей с входными значениями Enum.

Пример

SELECT getSizeOfEnumType( CAST('a' AS Enum8('a' = 1, 'b' = 2) ) ) AS x

┌─x─┐
│ 2 │
└───┘

blockSerializedSize

Возвращает размер на диске без учета сжатия.

blockSerializedSize(value[, value[, ...]])

Аргументы

value — Любое значение.

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

Количество байтов, которые будут записаны на диск для блока значений без сжатия.

Пример

Запрос:

SELECT blockSerializedSize(maxState(1)) as x

Результат:

┌─x─┐
│ 2 │
└───┘

toColumnTypeName

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

Синтаксис

toColumnTypeName(value)

Аргументы:

value — Значение любого типа.

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

Внутреннее имя типа данных, используемое для представления value.

Пример

Разница между toTypeName и toColumnTypeName:

SELECT toTypeName(CAST('2018-01-01 01:02:03' AS DateTime))

Результат:

┌─toTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime                                            │
└─────────────────────────────────────────────────────┘

Запрос:

SELECT toColumnTypeName(CAST('2018-01-01 01:02:03' AS DateTime))

Результат:

┌─toColumnTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32)                                             │
└───────────────────────────────────────────────────────────┘

Пример показывает, что тип данных DateTime внутренне хранится как Const(UInt32).

dumpColumnStructure

Выводит подробное описание структур данных в оперативной памяти.

dumpColumnStructure(value)

Аргументы:

value — Значение любого типа.

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

Описание структуры столбца, используемой для представления value.

Пример

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

defaultValueOfArgumentType

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

Не включает значения по умолчанию для пользовательских колонок, установленных пользователем.

Синтаксис

defaultValueOfArgumentType(expression)

Аргументы:

expression — Произвольный тип значения или выражение, которое возвращает значение произвольного типа.

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

0 для чисел.
Пустая строка для строк.
ᴺᵁᴸᴸ для Nullable.

Пример

Запрос:

SELECT defaultValueOfArgumentType( CAST(1 AS Int8) )

Результат:

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

Запрос:

SELECT defaultValueOfArgumentType( CAST(1 AS Nullable(Int8) ) )

Результат:

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

defaultValueOfTypeName

Возвращает значение по умолчанию для данного имени типа.

Не включает значения по умолчанию для пользовательских колонок, установленных пользователем.

defaultValueOfTypeName(type)

Аргументы:

type — Строка, представляющая имя типа.

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

0 для чисел.
Пустая строка для строк.
ᴺᵁᴸᴸ для Nullable.

Пример

Запрос:

SELECT defaultValueOfTypeName('Int8')

Результат:

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

Запрос:

SELECT defaultValueOfTypeName('Nullable(Int8)')

Результат:

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

indexHint

Эта функция предназначена для отладки и инспекции. Она игнорирует свой аргумент и всегда возвращает 1. Аргументы не оцениваются.

Однако во время анализа индекса считается, что аргумент этой функции не обернут в indexHint. Это позволяет выбирать данные в диапазонах индекса по соответствующему условию, но без дальнейшей фильтрации по этому условию. Индекс в ClickHouse разреженный, и использование indexHint приведет к получению большего объема данных, чем указание того же условия напрямую.

Синтаксис

SELECT * FROM table WHERE indexHint(<expression>)

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

1. Uint8.

Пример

Вот пример тестовых данных из таблицы ontime.

Таблица:

SELECT count() FROM ontime

┌─count()─┐
│ 4276457 │
└─────────┘

В таблице есть индексы по полям (FlightDate, (Year, FlightDate)).

Создайте запрос, который не использует индекс:

SELECT FlightDate AS k, count() FROM ontime GROUP BY k ORDER BY k

ClickHouse обработал всю таблицу (Обработано 4.28 миллиона строк).

Результат:

┌──────────k─┬─count()─┐
│ 2017-01-01 │   13970 │
│ 2017-01-02 │   15882 │
........................
│ 2017-09-28 │   16411 │
│ 2017-09-29 │   16384 │
│ 2017-09-30 │   12520 │
└────────────┴─────────┘

Чтобы применить индекс, выберите конкретную дату:

SELECT FlightDate AS k, count() FROM ontime WHERE k = '2017-09-15' GROUP BY k ORDER BY k

Теперь ClickHouse использует индекс для обработки значительно меньшего количества строк (Обработано 32.74 тысячи строк).

Результат:

┌──────────k─┬─count()─┐
│ 2017-09-15 │   16428 │
└────────────┴─────────┘

Теперь оберните выражение k = '2017-09-15' в функцию indexHint:

Запрос:

SELECT
    FlightDate AS k,
    count()
FROM ontime
WHERE indexHint(k = '2017-09-15')
GROUP BY k
ORDER BY k ASC

ClickHouse использовал индекс так же, как и ранее (Обработано 32.74 тысячи строк). Выражение k = '2017-09-15' не использовалось при генерации результата. В примере функция indexHint позволяет увидеть соседние даты.

Результат:

┌──────────k─┬─count()─┐
│ 2017-09-14 │    7071 │
│ 2017-09-15 │   16428 │
│ 2017-09-16 │    1077 │
│ 2017-09-30 │    8167 │
└────────────┴─────────┘

replicate

Создает массив с единственным значением.

примечание

Эта функция используется для внутренней реализации arrayJoin.

Синтаксис

replicate(x, arr)

Аргументы

x — Значение, которым заполнит результирующий массив.
arr — Массив. Array.

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

Массив такой же длины, как arr, заполненный значением x. Array.

Пример

Запрос:

SELECT replicate(1, ['a', 'b', 'c']);

Результат:

┌─replicate(1, ['a', 'b', 'c'])─┐
│ [1,1,1]                       │
└───────────────────────────────┘

revision

Возвращает текущую ревизию сервера ClickHouse.

Синтаксис

revision()

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

Текущая ревизия сервера ClickHouse. UInt32.

Пример

Запрос:

SELECT revision();

Результат:

┌─revision()─┐
│      54485 │
└────────────┘

filesystemAvailable

Возвращает количество свободного места в файловой системе, хранящей данные базы данных. Возвращаемое значение всегда меньше общего свободного места (filesystemUnreserved), так как часть места зарезервирована для операционной системы.

Синтаксис

filesystemAvailable()

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

Количество оставшегося пространства в байтах. UInt64.

Пример

Запрос:

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

Результат:

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

filesystemUnreserved

Возвращает общий объем свободного пространства на файловой системе, хранящей данные базы данных. (ранее filesystemFree). См. также filesystemAvailable.

Синтаксис

filesystemUnreserved()

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

Количество свободного пространства в байтах. UInt64.

Пример

Запрос:

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

Результат:

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

filesystemCapacity

Возвращает емкость файловой системы в байтах. Необходимо настроить path к каталогу данных.

Синтаксис

filesystemCapacity()

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

Емкость файловой системы в байтах. UInt64.

Пример

Запрос:

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

Результат:

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

initializeAggregation

Вычисляет результат агрегатной функции на основе единственного значения. Эта функция может быть использована для инициализации агрегатных функций с комбинатором -State. Вы можете создавать состояния агрегатных функций и вставлять их в колонки типа AggregateFunction или использовать инициализированные агрегаты в качестве значений по умолчанию.

Синтаксис

initializeAggregation (aggregate_function, arg1, arg2, ..., argN)

Аргументы

aggregate_function — Имя агрегатной функции для инициализации. String.
arg — Аргументы агрегатной функции.

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

Результат агрегирования для каждой строки, переданной функции.

Тип возвращаемого значения остается таким же, как тип возвращаемого значения функции, то есть initializeAggregation берет в качестве первого аргумента.

Пример

Запрос:

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

Результат:

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

Запрос:

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

Результат:

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

Пример с использованием движка таблицы AggregatingMergeTree и колонки AggregateFunction:

CREATE TABLE metrics
(
    key UInt64,
    value AggregateFunction(sum, UInt64) DEFAULT initializeAggregation('sumState', toUInt64(0))
)
ENGINE = AggregatingMergeTree
ORDER BY key

INSERT INTO metrics VALUES (0, initializeAggregation('sumState', toUInt64(42)))

См. также

arrayReduce

title: 'Функции агрегирования'
sidebar_label: 'Функции агрегирования'
keywords: ['finalizeAggregation', 'runningAccumulate', 'joinGet', 'joinGetOrNull', 'catboostEvaluate', 'throwIf', 'identity', 'getSetting', 'getSettingOrDefault', 'isDecimalOverflow', 'countDigits', 'errorCodeToName', 'tcpPort', 'currentProfiles', 'enabledProfiles', 'defaultProfiles', 'currentRoles', 'enabledRoles', 'defaultRoles', 'getServerPort', 'queryID', 'initialQueryID', 'initialQueryStartTime', 'partitionID', 'shardNum', 'shardCount', 'getOSKernelVersion', 'zookeeperSessionUptime']
description: 'Документация по функциям агрегирования ClickHouse'

finalizeAggregation

Учитывая состояние агрегатной функции, эта функция возвращает результат агрегации (или финализированное состояние при использовании комбинирования -State).

Синтаксис

finalizeAggregation(state)

Аргументы

state — Состояние агрегации. AggregateFunction.

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

Значение/значения, которые были агрегированы.

примечание

Тип возвращаемого значения равен типам, которые были агрегированы.

Примеры

Запрос:

SELECT finalizeAggregation(( SELECT countState(number) FROM numbers(10)));

Результат:

┌─finalizeAggregation(_subquery16)─┐
│                               10 │
└──────────────────────────────────┘

Запрос:

SELECT finalizeAggregation(( SELECT sumState(number) FROM numbers(10)));

Результат:

┌─finalizeAggregation(_subquery20)─┐
│                               45 │
└──────────────────────────────────┘

Обратите внимание, что значения NULL игнорируются.

Запрос:

SELECT finalizeAggregation(arrayReduce('anyState', [NULL, 2, 3]));

Результат:

┌─finalizeAggregation(arrayReduce('anyState', [NULL, 2, 3]))─┐
│                                                          2 │
└────────────────────────────────────────────────────────────┘

Скомбинированный пример:

Запрос:

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(10);

Результат:

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
│      5 │           5 │             15 │
│      6 │           6 │             21 │
│      7 │           7 │             28 │
│      8 │           8 │             36 │
│      9 │           9 │             45 │
└────────┴─────────────┴────────────────┘

См. также

arrayReduce
initializeAggregation

runningAccumulate

Аккумулирует состояния агрегатной функции для каждой строки блока данных.

примечание

Состояние сбрасывается для каждого нового блока данных. Из-за этой ошибочной работы функция DEPRECATED, пожалуйста, используйте правильные оконные функции вместо этого.

Синтаксис

runningAccumulate(agg_state[, grouping]);

Аргументы

agg_state — Состояние агрегатной функции. AggregateFunction.
grouping — Ключ группировки. Опционально. Состояние функции сбрасывается, если значение grouping меняется. Это может быть любым из поддерживаемых типов данных, для которых определен оператор равенства.

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

Каждая результирующая строка содержит результат агрегатной функции, накопленный для всех входных строк от 0 до текущей позиции. runningAccumulate сбрасывает состояния для каждого нового блока данных или при изменении значения grouping.

Тип зависит от используемой агрегатной функции.

Примеры

Рассмотрите, как вы можете использовать runningAccumulate, чтобы найти кумулятивную сумму чисел без группировки и с группировкой.

Запрос:

SELECT k, runningAccumulate(sum_k) AS res FROM (SELECT number as k, sumState(k) AS sum_k FROM numbers(10) GROUP BY k ORDER BY k);

Результат:

┌─k─┬─res─┐
│ 0 │   0 │
│ 1 │   1 │
│ 2 │   3 │
│ 3 │   6 │
│ 4 │  10 │
│ 5 │  15 │
│ 6 │  21 │
│ 7 │  28 │
│ 8 │  36 │
│ 9 │  45 │
└───┴─────┘

Подзапрос генерирует sumState для каждого числа от 0 до 9. sumState возвращает состояние функции sum, которое содержит сумму одного числа.

Весь запрос выполняет следующее:

Для первой строки runningAccumulate берет sumState(0) и возвращает 0.
Для второй строки функция объединяет sumState(0) и sumState(1), что приводит к sumState(0 + 1), и возвращает 1 как результат.
Для третьей строки функция объединяет sumState(0 + 1) и sumState(2), что приводит к sumState(0 + 1 + 2), и возвращает 3 как результат.
Действия повторяются до окончания блока.

Следующий пример показывает использование параметра grouping:

Запрос:

SELECT
    grouping,
    item,
    runningAccumulate(state, grouping) AS res
FROM
(
    SELECT
        toInt8(number / 4) AS grouping,
        number AS item,
        sumState(number) AS state
    FROM numbers(15)
    GROUP BY item
    ORDER BY item ASC
);

Результат:

┌─grouping─┬─item─┬─res─┐
│        0 │    0 │   0 │
│        0 │    1 │   1 │
│        0 │    2 │   3 │
│        0 │    3 │   6 │
│        1 │    4 │   4 │
│        1 │    5 │   9 │
│        1 │    6 │  15 │
│        1 │    7 │  22 │
│        2 │    8 │   8 │
│        2 │    9 │  17 │
│        2 │   10 │  27 │
│        2 │   11 │  38 │
│        3 │   12 │  12 │
│        3 │   13 │  25 │
│        3 │   14 │  39 │
└──────────┴──────┴─────┘

Как вы видите, runningAccumulate объединяет состояния для каждой группы строк отдельно.

joinGet

Эта функция позволяет извлекать данные из таблицы так же, как из словаря. Получает данные из Join таблиц, используя указанный ключ соединения.

примечание

Поддерживает только таблицы, созданные с помощью оператора ENGINE = Join(ANY, LEFT, <join_keys>).

Синтаксис

joinGet(join_storage_table_name, `value_column`, join_keys)

Аргументы

join_storage_table_name — идентификатор, указывающий, где производится поиск.
value_column — имя колонки таблицы, содержащей необходимые данные.
join_keys — список ключей.

примечание

Идентификатор ищется в базе данных по умолчанию (см. настройку default_database в файле конфигурации). Чтобы переопределить базу данных по умолчанию, используйте USE db_name или укажите базу данных и таблицу через разделитель db_name.db_table, как в примере.

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

Возвращает список значений, соответствующих списку ключей.

примечание

Если определенный ключ не существует в исходной таблице, то будет возвращено 0 или null в зависимости от настройки join_use_nulls при создании таблицы. Более подробная информация о join_use_nulls в операции Join.

Пример

Входная таблица:

CREATE DATABASE db_test;
CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val;

┌─id─┬─val─┐
│  4 │  13 │
│  2 │  12 │
│  1 │  11 │
└────┴─────┘

Запрос:

SELECT number, joinGet(db_test.id_val, 'val', toUInt32(number)) from numbers(4);

Результат:

┌─number─┬─joinGet('db_test.id_val', 'val', toUInt32(number))─┐
1. │      0 │                                                  0 │
2. │      1 │                                                 11 │
3. │      2 │                                                 12 │
4. │      3 │                                                  0 │
└────────┴────────────────────────────────────────────────────┘

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

CREATE DATABASE db_test;
CREATE TABLE db_test.id_val_nulls(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id) SETTINGS join_use_nulls=1;
INSERT INTO db_test.id_val_nulls VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val_nulls;

┌─id─┬─val─┐
│  4 │  13 │
│  2 │  12 │
│  1 │  11 │
└────┴─────┘

Запрос:

SELECT number, joinGet(db_test.id_val_nulls, 'val', toUInt32(number)) from numbers(4);

Результат:

┌─number─┬─joinGet('db_test.id_val_nulls', 'val', toUInt32(number))─┐
1. │      0 │                                                     ᴺᵁᴸᴸ │
2. │      1 │                                                       11 │
3. │      2 │                                                       12 │
4. │      3 │                                                     ᴺᵁᴸᴸ │
└────────┴──────────────────────────────────────────────────────────┘

joinGetOrNull

Как и joinGet, но возвращает NULL, когда ключ отсутствует вместо возврата значения по умолчанию.

Синтаксис

joinGetOrNull(join_storage_table_name, `value_column`, join_keys)

Аргументы

join_storage_table_name — идентификатор, указывающий, где производится поиск.
value_column — имя колонки таблицы, содержащей необходимые данные.
join_keys — список ключей.

примечание

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

Возвращает список значений, соответствующих списку ключей.

примечание

Если определенный ключ не существует в исходной таблице, для этого ключа будет возвращен NULL.

Пример

Входная таблица:

CREATE DATABASE db_test;
CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val;

┌─id─┬─val─┐
│  4 │  13 │
│  2 │  12 │
│  1 │  11 │
└────┴─────┘

Запрос:

SELECT number, joinGetOrNull(db_test.id_val, 'val', toUInt32(number)) from numbers(4);

Результат:

┌─number─┬─joinGetOrNull('db_test.id_val', 'val', toUInt32(number))─┐
1. │      0 │                                                     ᴺᵁᴸᴸ │
2. │      1 │                                                       11 │
3. │      2 │                                                       12 │
4. │      3 │                                                     ᴺᵁᴸᴸ │
└────────┴──────────────────────────────────────────────────────────┘

catboostEvaluate

Not supported in ClickHouse Cloud

примечание

Эта функция недоступна в ClickHouse Cloud.

Оцените внешнюю модель catboost. CatBoost — это библиотека градиентного бустинга с открытым исходным кодом, разработанная Яндексом для машинного обучения. Принимает путь к модели catboost и аргументы модели (признаки). Возвращает Float64.

Синтаксис

catboostEvaluate(path_to_model, feature_1, feature_2, ..., feature_n)

Пример

SELECT feat1, ..., feat_n, catboostEvaluate('/path/to/model.bin', feat_1, ..., feat_n) AS prediction
FROM data_table

Предварительные условия

Построить библиотеку оценки catboost

Перед оценкой моделей catboost библиотека libcatboostmodel.<so|dylib> должна быть доступна. Смотрите документацию CatBoost, чтобы узнать, как скомпилировать её.

Затем укажите путь к libcatboostmodel.<so|dylib> в конфигурации ClickHouse:

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

По соображениям безопасности и изоляции оценка модели не выполняется в процессе сервера, а в процессе clickhouse-library-bridge. При первом выполнении catboostEvaluate(), сервер запускает процесс библиотечного моста, если он еще не запущен. Оба процесса общаются через HTTP интерфейс. По умолчанию используется порт 9012. Можно указать другой порт следующим образом — это полезно, если порт 9012 уже занят другим сервисом.

<library_bridge>
    <port>9019</port>
</library_bridge>

Обучить модель catboost с использованием libcatboost

Смотрите Обучение и применение моделей, чтобы узнать, как обучать модели catboost на основе обучающего набора данных.

throwIf

Вызывает исключение, если аргумент x истинный.

Синтаксис

throwIf(x[, message[, error_code]])

Аргументы

x - условие для проверки.
message - константная строка, предоставляющая собственное сообщение об ошибке. Необязательно.
error_code - Константное целое число, предоставляющее собственный код ошибки. Необязательно.

Чтобы использовать аргумент error_code, необходимо включить параметр конфигурации allow_custom_error_code_in_throwif.

Пример

SELECT throwIf(number = 3, 'Слишком много') FROM numbers(10);

Результат:

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Получено исключение от сервера (версия 19.14.1):
Код: 395. DB::Exception: Получено от localhost:9000. DB::Exception: Слишком много.

identity

Возвращает свой аргумент. Предназначен для отладки и тестирования. Позволяет отменить использование индекса и получить производительность запроса полного сканирования. Когда запрос анализируется для возможного использования индекса, анализатор игнорирует все функции identity. Также отключает сведение постоянных значений.

Синтаксис

identity(x)

Пример

Запрос:

SELECT identity(42);

Результат:

┌─identity(42)─┐
│           42 │
└──────────────┘

getSetting

Возвращает текущее значение пользовательской настройки.

Синтаксис

getSetting('custom_setting');

Параметр

custom_setting — Название настройки. Строка.

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

Текущее значение настройки.

Пример

SET custom_a = 123;
SELECT getSetting('custom_a');

Результат:

См. также

Пользовательские настройки

getSettingOrDefault

Возвращает текущее значение пользовательской настройки или возвращает значение по умолчанию, указанное во втором аргументе, если пользовательская настройка не установлена в текущем профиле.

Синтаксис

getSettingOrDefault('custom_setting', default_value);

Параметр

custom_setting — Название настройки. Строка.
default_value — Значение, которое нужно вернуть, если custom_setting не установлена. Значение может быть любого типа данных или Null.

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

Текущее значение настройки или default_value, если настройка не установлена.

Пример

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

Результат:

my_value
100
NULL

См. также

Пользовательские настройки

isDecimalOverflow

Проверяет, находится ли значение Decimal вне его точности или вне заданной точности.

Синтаксис

isDecimalOverflow(d, [p])

Аргументы

d — значение. Decimal.
p — точность. Необязательно. Если опущен, используется начальная точность первого аргумента. Этот параметр может быть полезен для миграции данных из/в другую базу данных или файл. UInt8.

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

1 — Значение Decimal имеет больше цифр, чем разрешено его точностью,
0 — Значение Decimal соответствует заданной точности.

Пример

Запрос:

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

Результат:

1    1    1    1

countDigits

Возвращает количество десятичных цифр, необходимых для представления значения.

Синтаксис

countDigits(x)

Аргументы

x — значение Int или Decimal.

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

Количество цифр. UInt8.

примечание

Для значений Decimal учитывает их масштабы: рассчитывает результат для базового целочисленного типа (значение * масштаб). Например: countDigits(42) = 2, countDigits(42.000) = 5, countDigits(0.04200) = 4. То есть, вы можете проверить переполнение десятичных значений для Decimal64, используя countDecimal(x) > 18. Это медленный вариант isDecimalOverflow.

Пример

Запрос:

SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
       countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
       countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));

Результат:

10    10    19    19    39    39

errorCodeToName

Текстовое название кода ошибки. LowCardinality(String).

Синтаксис

errorCodeToName(1)

Результат:

UNSUPPORTED_METHOD

tcpPort

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

Синтаксис

tcpPort()

Аргументы

Нет.

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

Номер порта TCP. UInt16.

Пример

Запрос:

SELECT tcpPort();

Результат:

┌─tcpPort()─┐
│      9000 │
└───────────┘

См. также

tcp_port

currentProfiles

Возвращает список текущих профилей настроек для текущего пользователя.

Команда SET PROFILE может быть использована для изменения текущего профиля настроек. Если команда SET PROFILE не использовалась, функция возвращает профили, указанные в определении текущего пользователя (см. CREATE USER).

Синтаксис

currentProfiles()

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

Список текущих пользовательских профилей настроек. Массив(Строка).

enabledProfiles

Возвращает профили настроек, назначенные текущему пользователю как явно, так и неявно. Явно назначенные профили такие же, как возвращенные функцией currentProfiles. Неявно назначенные профили включают родительские профили других назначенных профилей, профили, назначенные через предоставленные роли, профили, назначенные через собственные настройки и основной профиль по умолчанию (см. раздел default_profile в основном файле конфигурации сервера).

Синтаксис

enabledProfiles()

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

Список включенных профилей настроек. Массив(Строка).

defaultProfiles

Возвращает все профили, указанные в определении текущего пользователя (см. оператор CREATE USER).

Синтаксис

defaultProfiles()

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

Список профилей настроек по умолчанию. Массив(Строка).

currentRoles

Возвращает роли, назначенные текущему пользователю. Роли можно изменить с оператором SET ROLE. Если оператора SET ROLE не было, функция currentRoles возвращает то же самое, что и defaultRoles.

Синтаксис

currentRoles()

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

Список текущих ролей для текущего пользователя. Массив(Строка).

enabledRoles

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

Синтаксис

enabledRoles()

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

Список включенных ролей для текущего пользователя. Массив(Строка).

defaultRoles

Возвращает роли, которые включены по умолчанию для текущего пользователя при входе. Изначально это все роли, предоставленные текущему пользователю (см. GRANT), но это можно изменить с помощью оператора SET DEFAULT ROLE.

Синтаксис

defaultRoles()

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

Список ролей по умолчанию для текущего пользователя. Массив(Строка).

getServerPort

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

Синтаксис

getServerPort(port_name)

Аргументы

port_name — Название порта сервера. Строка. Возможные значения:
- 'tcp_port'
- 'tcp_port_secure'
- 'http_port'
- 'https_port'
- 'interserver_http_port'
- 'interserver_https_port'
- 'mysql_port'
- 'postgresql_port'
- 'grpc_port'
- 'prometheus.port'

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

Номер порта сервера. UInt16.

Пример

Запрос:

SELECT getServerPort('tcp_port');

Результат:

┌─getServerPort('tcp_port')─┐
│ 9000                      │
└───────────────────────────┘

queryID

Возвращает ID текущего запроса. Другие параметры запроса можно извлечь из таблицы system.query_log через query_id.

В отличие от функции initialQueryID, queryID может возвращать разные результаты на разных шардах (см. пример).

Синтаксис

queryID()

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

ID текущего запроса. Строка

Пример

Запрос:

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Результат:

┌─count()─┐
│ 3       │
└─────────┘

initialQueryID

Возвращает ID начального текущего запроса. Другие параметры запроса можно извлечь из таблицы system.query_log через initial_query_id.

В отличие от функции queryID, initialQueryID возвращает одни и те же результаты на разных шардах (см. пример).

Синтаксис

initialQueryID()

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

ID начального текущего запроса. Строка

Пример

Запрос:

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Результат:

┌─count()─┐
│ 1       │
└─────────┘

initialQueryStartTime

Возвращает время начала начального текущего запроса.

initialQueryStartTime возвращает одни и те же результаты на разных шардах (см. пример).

Синтаксис

initialQueryStartTime()

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

Время начала начального текущего запроса. DateTime

Пример

Запрос:

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Результат:

┌─count()─┐
│ 1       │
└─────────┘

partitionID

Вычисляет ID партиции.

примечание

Эта функция медленная и не должна вызываться для большого объема строк.

Синтаксис

partitionID(x[, y, ...]);

Аргументы

x — Колонка, для которой нужно вернуть ID партиции.
y, ... — Оставшиеся N колонок, для которых нужно вернуть ID партиции (опционально).

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

ID партиции, к которой будет принадлежать строка. Строка.

Пример

Запрос:

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionID(i), _partition_id FROM tab ORDER BY i, j;

Результат:

┌─i─┬─j─┬─partitionID(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
└───┴───┴────────────────┴───────────────┘
┌─i─┬─j─┬─partitionID(i)─┬─_partition_id─┐
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

shardNum

Возвращает индекс шара, который обрабатывает часть данных в распределенном запросе. Индексы начинаются с 1. Если запрос не распределен, то возвращается постоянное значение 0.

Синтаксис

shardNum()

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

Индекс шара или постоянное значение 0. UInt32.

Пример

В следующем примере используется конфигурация с двумя шарами. Запрос выполняется на таблице system.one на каждом шаре.

Запрос:

CREATE TABLE shard_num_example (dummy UInt8)
    ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;

Результат:

┌─dummy─┬─shardNum()─┬─shardCount()─┐
│     0 │          2 │            2 │
│     0 │          1 │            2 │
└───────┴────────────┴──────────────┘

См. также

Движок распределенной таблицы

shardCount

Возвращает общее количество шаров для распределенного запроса. Если запрос не распределен, то возвращается постоянное значение 0.

Синтаксис

shardCount()

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

Общее количество шаров или 0. UInt32.

См. также

Пример функции shardNum() также содержит вызов функции shardCount().

getOSKernelVersion

Возвращает строку с текущей версией ядра ОС.

Синтаксис

getOSKernelVersion()

Аргументы

Нет.

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

Текущая версия ядра ОС. Строка.

Пример

Запрос:

SELECT getOSKernelVersion();

Результат:

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

zookeeperSessionUptime

Возвращает время работы текущей сессии ZooKeeper в секундах.

Синтаксис

zookeeperSessionUptime()

Аргументы

Нет.

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

Время работы текущей сессии ZooKeeper в секундах. UInt32.

Пример

Запрос:

SELECT zookeeperSessionUptime();

Результат:

┌─zookeeperSessionUptime()─┐
│                      286 │
└──────────────────────────┘

title: 'Генерация случайных структур таблиц'
sidebar_label: 'generateRandomStructure'
keywords: ['генерация', 'случайная структура', 'таблицы']
description: 'Генерация случайной структуры таблицы в формате `column1_name column1_type, column2_name column2_type, ...`.'

generateRandomStructure

Генерирует случайную структуру таблицы в формате column1_name column1_type, column2_name column2_type, ....

Синтаксис

generateRandomStructure([number_of_columns, seed])

Аргументы

number_of_columns — Желаемое количество колонок в структуре таблицы результата. Если установлено в 0 или Null, количество колонок будет случайным от 1 до 128. Значение по умолчанию: Null.
seed - Случайное семя для получения стабильных результатов. Если семя не указано или установлено в Null, оно генерируется случайным образом.

Все аргументы должны быть константами.

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

Случайно сгенерированная структура таблицы. String.

Примеры

Запрос:

SELECT generateRandomStructure()

Результат:

┌─generateRandomStructure()─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Запрос:

SELECT generateRandomStructure(1)

Результат:

┌─generateRandomStructure(1)─┐
│ c1 Map(UInt256, UInt16)    │
└────────────────────────────┘

Запрос:

SELECT generateRandomStructure(NULL, 33)

Результат:

┌─generateRandomStructure(NULL, 33)─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ c1 DateTime, c2 Enum8('c2V0' = 0, 'c2V1' = 1, 'c2V2' = 2, 'c2V3' = 3), c3 LowCardinality(Nullable(FixedString(30))), c4 Int16, c5 Enum8('c5V0' = 0, 'c5V1' = 1, 'c5V2' = 2, 'c5V3' = 3), c6 Nullable(UInt8), c7 String, c8 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(70))) │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Примечание: максимальная глубина вложенности сложных типов (Array, Tuple, Map, Nested) ограничена 16.

Эта функция может использоваться вместе с generateRandom для генерации совершенно случайных таблиц.

structureToCapnProtoSchema

Преобразует структуру таблицы ClickHouse в схему CapnProto.

Синтаксис

structureToCapnProtoSchema(structure)

Аргументы

structure — Структура таблицы в формате column1_name column1_type, column2_name column2_type, ....
root_struct_name — Имя корневой структуры в схеме CapnProto. Значение по умолчанию - Message;

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

Схема CapnProto. String.

Примеры

Запрос:

SELECT structureToCapnProtoSchema('column1 String, column2 UInt32, column3 Array(String)') FORMAT RawBLOB

Результат:

@0xf96402dd754d0eb7;

struct Message
{
    column1 @0 : Data;
    column2 @1 : UInt32;
    column3 @2 : List(Data);
}

Запрос:

SELECT structureToCapnProtoSchema('column1 Nullable(String), column2 Tuple(element1 UInt32, element2 Array(String)), column3 Map(String, String)') FORMAT RawBLOB

Результат:

@0xd1c8320fecad2b7f;

struct Message
{
    struct Column1
    {
        union
        {
            value @0 : Data;
            null @1 : Void;
        }
    }
    column1 @0 : Column1;
    struct Column2
    {
        element1 @0 : UInt32;
        element2 @1 : List(Data);
    }
    column2 @1 : Column2;
    struct Column3
    {
        struct Entry
        {
            key @0 : Data;
            value @1 : Data;
        }
        entries @0 : List(Entry);
    }
    column3 @2 : Column3;
}

Запрос:

SELECT structureToCapnProtoSchema('column1 String, column2 UInt32', 'Root') FORMAT RawBLOB

Результат:

@0x96ab2d4ab133c6e1;

struct Root
{
    column1 @0 : Data;
    column2 @1 : UInt32;
}

structureToProtobufSchema

Преобразует структуру таблицы ClickHouse в схему Protobuf.

Синтаксис

structureToProtobufSchema(structure)

Аргументы

structure — Структура таблицы в формате column1_name column1_type, column2_name column2_type, ....
root_message_name — Имя корневого сообщения в схеме Protobuf. Значение по умолчанию - Message;

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

Схема Protobuf. String.

Примеры

Запрос:

SELECT structureToProtobufSchema('column1 String, column2 UInt32, column3 Array(String)') FORMAT RawBLOB

Результат:

syntax = "proto3";

message Message
{
    bytes column1 = 1;
    uint32 column2 = 2;
    repeated bytes column3 = 3;
}

Запрос:

SELECT structureToProtobufSchema('column1 Nullable(String), column2 Tuple(element1 UInt32, element2 Array(String)), column3 Map(String, String)') FORMAT RawBLOB

Результат:

syntax = "proto3";

message Message
{
    bytes column1 = 1;
    message Column2
    {
        uint32 element1 = 1;
        repeated bytes element2 = 2;
    }
    Column2 column2 = 2;
    map<string, bytes> column3 = 3;
}

Запрос:

SELECT structureToProtobufSchema('column1 String, column2 UInt32', 'Root') FORMAT RawBLOB

Результат:

syntax = "proto3";

message Root
{
    bytes column1 = 1;
    uint32 column2 = 2;
}

formatQuery

Возвращает отформатированную, возможно многострочную, версию данного SQL-запроса.

Вызывает исключение, если запрос не является хорошо сформированным. Для возвращения NULL вместо этого может использоваться функция formatQueryOrNull().

Синтаксис

formatQuery(query)
formatQueryOrNull(query)

Аргументы

query - SQL-запрос, который необходимо отформатировать. String

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

Отформатированный запрос. String.

Пример

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

Результат:

┌─formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3')─┐
│ SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)            │
└───────────────────────────────────────────────────────────────┘

formatQuerySingleLine

Как formatQuery(), но возвращаемая отформатированная строка не содержит переносов строк.

Вызывает исключение, если запрос не является хорошо сформированным. Для возвращения NULL вместо этого может использоваться функция formatQuerySingleLineOrNull().

Синтаксис

formatQuerySingleLine(query)
formatQuerySingleLineOrNull(query)

Аргументы

query - SQL-запрос, который необходимо отформатировать. String

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

Отформатированный запрос. String.

Пример

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

Результат:

┌─formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3')─┐
│ SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)                          │
└─────────────────────────────────────────────────────────────────────────┘

variantElement

Извлекает колонку с указанным типом из колонки Variant.

Синтаксис

variantElement(variant, type_name, [, default_value])

Аргументы

variant — колонка Variant. Variant.
type_name — Имя типа варианта, который необходимо извлечь. String.
default_value - Значение по умолчанию, которое будет использоваться, если вариант не имеет варианта с указанным типом. Может быть любого типа. Необязательный.

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

Подколонка колонки Variant с указанным типом.

Пример

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

variantType

Возвращает имя типа варианта для каждой строки колонки Variant. Если строка содержит NULL, для нее возвращается 'None'.

Синтаксис

variantType(variant)

Аргументы

variant — колонка Variant. Variant.

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

Enum8 колонка с именем типа варианта для каждой строки.

Пример

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

SELECT toTypeName(variantType(v)) FROM test LIMIT 1;

┌─toTypeName(variantType(v))──────────────────────────────────────────┐
│ Enum8('None' = -1, 'Array(UInt64)' = 0, 'String' = 1, 'UInt64' = 2) │
└─────────────────────────────────────────────────────────────────────┘

minSampleSizeConversion

Вычисляет минимально необходимый размер выборки для A/B-теста, сравнивающего конверсии (доли) в двух выборках.

Синтаксис

minSampleSizeConversion(baseline, mde, power, alpha)

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

Аргументы

baseline — Базовая конверсия. Float.
mde — Минимально обнаружимый эффект (MDE) в процентных пунктах (например, для базовой конверсии 0.25, MDE 0.03 означает ожидаемое изменение до 0.25 ± 0.03). Float.
power — Необходимая статистическая мощность теста (1 - вероятность ошибки второго рода). Float.
alpha — Необходимый уровень значимости теста (вероятность ошибки первого рода). Float.

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

Именованный Tuple с 3 элементами:

"minimum_sample_size" — Необходимый размер выборки. Float64.
"detect_range_lower" — Нижняя граница диапазона значений, которые не могут быть обнаружены при возвращаемом необходимом размере выборки (т.е. все значения меньше или равные "detect_range_lower" могут быть обнаружены с предоставленными alpha и power). Вычисляется как baseline - mde. Float64.
"detect_range_upper" — Верхняя граница диапазона значений, которые не могут быть обнаружены при возвращаемом необходимом размере выборки (т.е. все значения больше или равные "detect_range_upper" могут быть обнаружены с предоставленными alpha и power). Вычисляется как baseline + mde. Float64.

Пример

Следующий запрос вычисляет необходимый размер выборки для A/B-теста с базовой конверсией 25%, MDE 3%, уровнем значимости 5% и желаемой статистической мощностью 80%:

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size;

Результат:

┌─sample_size───────────────────┐
│ (3396.077603219163,0.22,0.28) │
└───────────────────────────────┘

minSampleSizeContinuous

Вычисляет минимально необходимый размер выборки для A/B-теста, сравнивающего средние значения непрерывного показателя в двух выборках.

Синтаксис

minSampleSizeContinous(baseline, sigma, mde, power, alpha)

Псевдоним: minSampleSizeContinous

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

Аргументы

baseline — Базовое значение показателя. Integer или Float.
sigma — Базовое стандартное отклонение показателя. Integer или Float.
mde — Минимально обнаружимый эффект (MDE) в процентах от базового значения (например, для базового значения 112.25, MDE 0.03 означает ожидаемое изменение до 112.25 ± 112.25*0.03). Integer или Float.
power — Необходимая статистическая мощность теста (1 - вероятность ошибки второго рода). Integer или Float.
alpha — Необходимый уровень значимости теста (вероятность ошибки первого рода). Integer или Float.

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

Именованный Tuple с 3 элементами:

"minimum_sample_size" — Необходимый размер выборки. Float64.
"detect_range_lower" — Нижняя граница диапазона значений, которые не могут быть обнаружены при возвращаемом необходимом размере выборки (т.е. все значения меньше или равные "detect_range_lower" могут быть обнаружены с предоставленными alpha и power). Вычисляется как baseline * (1 - mde). Float64.
"detect_range_upper" — Верхняя граница диапазона значений, которые не могут быть обнаружены при возвращаемом необходимом размере выборки (т.е. все значения больше или равные "detect_range_upper" могут быть обнаружены с предоставленными alpha и power). Вычисляется как baseline * (1 + mde). Float64.

Пример

Следующий запрос вычисляет необходимый размер выборки для A/B-теста на показателе с базовым значением 112.25, стандартным отклонением 21.1, MDE 3%, уровнем значимости 5% и желаемой статистической мощностью 80%:

SELECT minSampleSizeContinous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size;

Результат:

┌─sample_size───────────────────────────┐
│ (616.2931945826209,108.8825,115.6175) │
└───────────────────────────────────────┘

connectionId

Извлекает ID подключения клиента, который отправил текущий запрос, и возвращает его в качестве целого числа UInt64.

Синтаксис

connectionId()

Псевдоним: connection_id.

Параметры

Нет.

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

Текущий ID подключения. UInt64.

Подробности реализации

Эта функция наиболее полезна в сценариях отладки или для внутренних целей в обработчике MySQL. Она была создана для совместимости с функцией MySQL CONNECTION_ID. Обычно не используется в производственных запросах.

Пример

Запрос:

SELECT connectionId();

getClientHTTPHeader

Получает значение HTTP-заголовка.

Если такого заголовка не существует или текущий запрос не выполняется через HTTP-интерфейс, функция возвращает пустую строку. Некоторые HTTP-заголовки (например, Authentication и X-ClickHouse-*) являются ограниченными.

Функция требует, чтобы настройка allow_get_client_http_header была включена. Настройка по умолчанию не включена по причинам безопасности, потому что некоторые заголовки, такие как Cookie, могут содержать конфиденциальную информацию.

HTTP-заголовки чувствительны к регистру для этой функции.

Если функция используется в контексте распределенного запроса, она возвращает ненулевой результат только на узле-инициаторе.

showCertificate

Показывает информацию о текущем сертификате Secure Sockets Layer (SSL) сервера, если он был настроен. См. Настройка SSL-TLS для получения дополнительной информации о том, как настроить ClickHouse для использования сертификатов OpenSSL для проверки соединений.

Синтаксис

showCertificate()

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

Словарь пар ключ-значение, относящихся к настроенному SSL-сертификату. Map(String, String).

Пример

Запрос:

SELECT showCertificate() FORMAT LineAsString;

Результат:

{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May  7 17:01:21 2024 GMT','not_after':'May  7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}

lowCardinalityIndices

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

Синтаксис

lowCardinalityIndices(col)

Аргументы

col — колонка низкой кардинальности. LowCardinality.

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

Позиция значения в словаре текущей части. UInt64.

Пример

Запрос:

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- создаем две части:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityIndices(s) FROM test;

Результат:

   ┌─s──┬─lowCardinalityIndices(s)─┐
1. │ ab │                        1 │
2. │ cd │                        2 │
3. │ ab │                        1 │
4. │ ab │                        1 │
5. │ df │                        3 │
   └────┴──────────────────────────┘
    ┌─s──┬─lowCardinalityIndices(s)─┐
 6. │ ef │                        1 │
 7. │ cd │                        2 │
 8. │ ab │                        3 │
 9. │ cd │                        2 │
10. │ ef │                        1 │
    └────┴──────────────────────────┘

lowCardinalityKeys

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

Синтаксис

lowCardinalityIndices(col)

Аргументы

col — колонка низкой кардинальности. LowCardinality.

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

Ключи словаря. UInt64.

Пример

Запрос:

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- создаем две части:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

Результат:

   ┌─s──┬─lowCardinalityKeys(s)─┐
1. │ ef │                       │
2. │ cd │ ef                    │
3. │ ab │ cd                    │
4. │ cd │ ab                    │
5. │ ef │                       │
   └────┴───────────────────────┘
    ┌─s──┬─lowCardinalityKeys(s)─┐
 6. │ ab │                       │
 7. │ cd │ ab                    │
 8. │ ab │ cd                    │
 9. │ ab │ df                    │
10. │ df │                       │
    └────┴───────────────────────┘

displayName

Возвращает значение display_name из конфигурации или полное доменное имя сервера (FQDN), если не установлено.

Синтаксис

displayName()

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

Значение display_name из конфигурации или FQDN сервера, если не установлено. String.

Пример

display_name может быть установлен в config.xml. Рассмотрим, например, сервер с display_name, настроенным на 'production':

<!-- Это имя, которое будет показано в clickhouse-client.
     По умолчанию все, что содержит "production", будет выделено красным в запросе.
-->
<display_name>production</display_name>

Запрос:

SELECT displayName();

Результат:

┌─displayName()─┐
│ production    │
└───────────────┘

transactionID

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

Возвращает ID транзакции.

примечание

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

<clickhouse>
  <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

Для получения дополнительной информации см. на странице Поддержка транзакций (ACID).

Синтаксис

transactionID()

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

Возвращает кортеж, состоящий из start_csn, local_tid и host_id. Tuple.
start_csn: Глобальный последовательный номер, самая новая временная метка коммита, которую видел этот транзакция во время её начала. UInt64.
local_tid: Локальный последовательный номер, уникальный для каждой транзакции, начатой этим хостом в рамках определенного start_csn. UInt64.
host_id: UUID хоста, который запустил эту транзакцию. UUID.

Пример

Запрос:

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

Результат:

┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘

transactionLatestSnapshot

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

Возвращает новейший снимок (номер последовательности коммита) транзакции, который доступен для чтения.

примечание

<clickhouse>
  <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

Для получения дополнительной информации см. на странице Поддержка транзакций (ACID).

Синтаксис

transactionLatestSnapshot()

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

Возвращает последний снимок (CSN) транзакции. UInt64

Пример

Запрос:

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

Результат:

┌─transactionLatestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transactionOldestSnapshot

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

Возвращает самый старый снимок (номер последовательности коммита), который виден для некоторой выполняющейся транзакции.

примечание

<clickhouse>
  <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

Для получения дополнительной информации см. на странице Поддержка транзакций (ACID).

Синтаксис

transactionOldestSnapshot()

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

Возвращает самый старый снимок (CSN) транзакции. UInt64

Пример

Запрос:

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

Результат:

┌─transactionOldestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

getSubcolumn

Берет выражение таблицы или идентификатор и постоянную строку с именем подполя, и возвращает запрашиваемое подполе, извлеченное из выражения.

Синтаксис

getSubcolumn(col_name, subcol_name)

Аргументы

col_name — Выражение таблицы или идентификатор. Expression, Identifier.
subcol_name — Имя подполя. String.

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

Возвращает извлеченное подполе.

Пример

Запрос:

CREATE TABLE t_arr (arr Array(Tuple(subcolumn1 UInt32, subcolumn2 String))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO t_arr VALUES ([(1, 'Hello'), (2, 'World')]), ([(3, 'This'), (4, 'is'), (5, 'subcolumn')]);
SELECT getSubcolumn(arr, 'subcolumn1'), getSubcolumn(arr, 'subcolumn2') FROM t_arr;

Результат:

   ┌─getSubcolumn(arr, 'subcolumn1')─┬─getSubcolumn(arr, 'subcolumn2')─┐
1. │ [1,2]                           │ ['Hello','World']               │
2. │ [3,4,5]                         │ ['This','is','subcolumn']       │
   └─────────────────────────────────┴─────────────────────────────────┘

getTypeSerializationStreams

Перечисляет пути потоков сериализации типа данных.

примечание

Эта функция предназначена для использования разработчиками.

Синтаксис

getTypeSerializationStreams(col)

Аргументы

col — Колонка или строковое представление типа данных, из которого будет определен тип данных.

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

Возвращает массив со всеми под-путями сериализации. Array(String).

Примеры

Запрос:

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2));

Результат:

   ┌─getTypeSerializationStreams(('a', 1, 'b', 2))─────────────────────────────────────────────────────────────────────────┐
1. │ ['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}'] │
   └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Запрос:

SELECT getTypeSerializationStreams('Map(String, Int64)');

Результат:

   ┌─getTypeSerializationStreams('Map(String, Int64)')────────────────────────────────────────────────────────────────┐
1. │ ['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}'] │
   └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

globalVariable

Принимает постоянный строковый аргумент и возвращает значение глобальной переменной с таким именем. Эта функция предназначена для совместимости с MySQL и не нужна или не полезна для нормальной работы ClickHouse. Определены только несколько фиктивных глобальных переменных.

Синтаксис

globalVariable(name)

Аргументы

name — Имя глобальной переменной. String.

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

Возвращает значение переменной name.

Пример

Запрос:

SELECT globalVariable('max_allowed_packet');

Результат:

┌─globalVariable('max_allowed_packet')─┐
│                             67108864 │
└──────────────────────────────────────┘

getMaxTableNameLengthForDatabase

Возвращает максимальную длину имени таблицы в указанной базе данных.

Синтаксис

getMaxTableNameLengthForDatabase(database_name)

Аргументы

database_name — Имя указанной базы данных. String.

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

Возвращает длину максимального имени таблицы.

Пример

Запрос:

SELECT getMaxTableNameLengthForDatabase('default');

Результат:

┌─getMaxTableNameLengthForDatabase('default')─┐
│                                         206 │
└─────────────────────────────────────────────┘

getServerSetting

Возвращает текущее значение одной из настроек сервера

Синтаксис

getServerSetting('server_setting');

Параметр

server_setting — Имя настройки. String.

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

Текущее значение настройки сервера.

Пример

SELECT getServerSetting('allow_use_jemalloc_memory');

Результат:

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

getMergeTreeSetting

Возвращает текущее значение одной из настроек дерева слияния

Синтаксис

getMergeTreeSetting('merge_tree_setting');

Параметр

merge_tree_setting — Имя настройки. String.

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

Текущее значение настройки дерева слияния.

Пример

SELECT getMergeTreeSetting('index_granularity');

Результат:

┌─getMergeTree(index_granularity')─┐
│                     8192         │
└──────────────────────────────────┘

hostName​

getMacro​

fqdn​

basename​

visibleWidth​

toTypeName​

blockSize​

byteSize​

materialize​

ignore​

sleep​

sleepEachRow​

currentDatabase​

currentUser​

currentSchemas​

isConstant​

hasColumnInTable​

hasThreadFuzzer​

bar​

transform​

transform(x, array_from, array_to, default)​

transform(x, array_from, array_to)​

formatReadableDecimalSize​

formatReadableSize​

formatReadableQuantity​

formatReadableTimeDelta​

parseReadableSize​

parseReadableSizeOrNull​

parseReadableSizeOrZero​

parseTimeDelta​

least​

greatest​

uptime​

version​

buildId​

blockNumber​

rowNumberInBlock​

rowNumberInAllBlocks​

normalizeQuery​

normalizeQueryKeepNames​

normalizedQueryHash​

normalizedQueryHashKeepNames​

neighbor​

runningDifference​

runningDifferenceStartingWithFirstValue​

runningConcurrency​

MACNumToString​

MACStringToNum​

MACStringToOUI​

getSizeOfEnumType​

blockSerializedSize​

toColumnTypeName​

dumpColumnStructure​

defaultValueOfArgumentType​

defaultValueOfTypeName​

indexHint​

replicate​

revision​

filesystemAvailable​

filesystemUnreserved​

filesystemCapacity​

initializeAggregation​

finalizeAggregation​

runningAccumulate​

joinGet​

joinGetOrNull​

catboostEvaluate​

throwIf​

identity​

getSetting​

getSettingOrDefault​

isDecimalOverflow​

countDigits​

errorCodeToName​

tcpPort​

currentProfiles​

enabledProfiles​

defaultProfiles​

currentRoles​

enabledRoles​

hostName

getMacro

fqdn

basename

visibleWidth

toTypeName

blockSize

byteSize

materialize

ignore

sleep

sleepEachRow

currentDatabase

currentUser

currentSchemas

isConstant

hasColumnInTable

hasThreadFuzzer

bar

transform

transform(x, array_from, array_to, default)

transform(x, array_from, array_to)

formatReadableDecimalSize

formatReadableSize

formatReadableQuantity

formatReadableTimeDelta

parseReadableSize

parseReadableSizeOrNull

parseReadableSizeOrZero

parseTimeDelta

least

greatest

uptime

version

buildId

blockNumber

rowNumberInBlock

rowNumberInAllBlocks

normalizeQuery

normalizeQueryKeepNames

normalizedQueryHash

normalizedQueryHashKeepNames

neighbor

runningDifference

runningDifferenceStartingWithFirstValue

runningConcurrency

MACNumToString

MACStringToNum

MACStringToOUI

getSizeOfEnumType

blockSerializedSize

toColumnTypeName

dumpColumnStructure

defaultValueOfArgumentType

defaultValueOfTypeName

indexHint

replicate

revision

filesystemAvailable

filesystemUnreserved

filesystemCapacity

initializeAggregation

finalizeAggregation

runningAccumulate

joinGet

joinGetOrNull

catboostEvaluate

throwIf

identity

getSetting

getSettingOrDefault

isDecimalOverflow

countDigits

errorCodeToName

tcpPort

currentProfiles

enabledProfiles

defaultProfiles

currentRoles

enabledRoles