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

hostName

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

Синтаксис

hostName()

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

Имя хоста. Строка.

getMacro

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

Синтаксис

getMacro(name);

Аргументы

name — Имя макроса, чтобы извлечь из раздела <macros>. Строка.

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

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

Пример

Пример секции <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.

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

Строка с полным доменным именем. Строка.

Пример

SELECT FQDN();

Результат:

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

basename

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

basename(expr)

Аргументы

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

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

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

Окончание входной строки после последнего символа / или \. Если входная строка заканчивается символом / или \ (например, / или 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 — Значение произвольного типа.

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

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

Пример

Запрос:

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.

Примеры

Для Строки аргументов функция возвращает длину строки + 8 (длина).

Запрос:

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 — Константа. Константа.

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

Колонка, содержащая единичное значение 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()

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

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

Пример

Запрос:

SELECT currentDatabase()

Результат:

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

currentUser

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

Синтаксис

currentUser()

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

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

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

Пример

SELECT currentUser();

Результат:

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

currentSchemas

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

Синтаксис

currentSchemas(bool)

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

Аргументы

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

примечание

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

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

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

Пример

SELECT currentSchemas(true);

Результат:

['default']

colorSRGBToOKLCH

Преобразует цвет, закодированный в цветовом пространстве sRGB, в перцептивно однородное цветовое пространство OKLCH.

Если любой из входных каналов находится вне диапазона [0...255] или значение гаммы неположительное, поведение определяется реализацией.

примечание

OKLCH является цилиндрической версией цветового пространства OKLab. Его три координаты — L (светимость в диапазоне [0...1]), C (хрома >= 0) и H (оттенок в градусах [0...360])**.
OKLab/OKLCH разработаны для достижения перцептивной однородности, сохраняя простоту вычислений.

Синтаксис

colorSRGBToOKLCH(tuple [, gamma])

Аргументы

tuple - Три числовых значения R, G, B в диапазоне [0...255]. Кортеж.
gamma - Необязательное числовое значение. Экспонента, которая используется для линейной обработки sRGB путем применения (x / 255)^gamma к каждому каналу x. По умолчанию равна 2.2.

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

Кортеж (L, C, H) типа Tuple(Float64, Float64, Float64).

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

Преобразование состоит из трех этапов:

sRGB в линейное sRGB
Линейное sRGB в OKLab
OKLab в OKLCH.

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

Два оставшихся этапа включают матричное умножение и тригонометрические преобразования соответственно. Для получения дополнительных сведений о математике смотрите статью о цветовом пространстве OKLab: https://bottosson.github.io/posts/OKLab/

Чтобы получить ссылки на цвета в пространстве OKLCH и их соответствие цветам sRGB, смотрите https://OKLCH.com/

Пример

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;

Результат:

┌─lch─────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.10442699545678624,45.907345481930236) │
└─────────────────────────────────────────────────────────────┘

colorOKLCHToSRGB

Преобразует цвет из перцептивного цветового пространства OKLCH в знакомое цветовое пространство sRGB.

Если L находится вне диапазона [0...1], C отрицательная, или H находится вне диапазона [0...360], результат определяется реализацией.

примечание

OKLCH является цилиндрической версией цветового пространства OKLab. Его три координаты — L (светимость в диапазоне [0...1]), C (хрома >= 0) и H (оттенок в градусах [0...360])**. OKLab/OKLCH разработаны для достижения перцептивной однородности, сохраняя простоту вычислений.

Синтаксис

colorOKLCHToSRGB(tuple [, gamma])

Аргументы

tuple - Три числовых значения L, C, H, представленные в виде кортежа, где L находится в диапазоне [0...1], C >= 0 и H находится в диапазоне [0...360]. Кортеж.
gamma - Необязательное числовое значение. Экспонента, которая используется для преобразования линейного sRGB обратно в sRGB, применяя (x ^ (1 / gamma)) * 255 для каждого канала x. По умолчанию равна 2.2.

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

Кортеж (R, G, B) типа Tuple(Float64, Float64, Float64).

примечание

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

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

Преобразование является обратным к colorSRGBToOKLCH:

OKLCH в OKLab.
OKLab в линейное sRGB
Линейное sRGB в sRGB

Второй аргумент гамма используется на последнем этапе. Обратите внимание, что все три канала обрезаются в диапазоне [0...1] непосредственно перед вычислением линейного sRGB, а затем возводятся в степень 1 / gamma. Если гамма равна 0, 1 / gamma изменяется на 1'000'000. Таким образом, независимо от ввода у нас обычно будут возвращены числа с плавающей запятой в диапазоне [0...255].

Как и в случае с colorSRGBToOKLCH, два других этапа включают тригонометрические преобразования и матричное умножение соответственно. Для получения дополнительных сведений о математике смотрите статью о цветовом пространстве OKLab: https://bottosson.github.io/posts/oklab/

Чтобы получить ссылки на цвета в пространстве OKLCH и их соответствие цветам sRGB, смотрите https://oklch.com/

Пример

SELECT colorOKLCHToSRGB((0.4466, 0.0991, 45.44), 2.2) AS rgb
WITH colorOKLCHToSRGB((0.7, 0.1, 54)) as t SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB

Результат:

┌─rgb──────────────────────────────────────────────────────┐
│ (127.03349738778945,66.06672044472008,37.11802592155851) │
└──────────────────────────────────────────────────────────┘

┌─RGB──────────┐
│ (205,139,97) │
└──────────────┘

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 : имя базы данных. Строковый литерал
table : имя таблицы. Строковый литерал
column : имя колонки. Строковый литерал
hostname : имя удаленного сервера для выполнения проверки. Строковой литерал
username : имя пользователя для удаленного сервера. Строковой литерал
password : пароль для удаленного сервера. Строковой литерал

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

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

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

Противоположные операции этой функции — 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 или десятичной единицей байтов (Строка).

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

Количество байтов, округленное до ближайшего целого числа (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 или десятичной единицей байтов (Строка).

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

Количество байтов, округленное до ближайшего целого числа, или 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 или десятичной единицей байтов (Строка).

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

Количество байтов, округленное до ближайшего целого числа, или 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 │
└────────────────┴─────────┘

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. Строка.

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

Нет.

Пример

Запрос:

SELECT version()

Результат:

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

buildId

Возвращает ID сборки, сгенерированный компилятором для работающего бинарного файла 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 — Последовательность символов. Строка.

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

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

Пример

Запрос:

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

Результат:

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

normalizeQueryKeepNames

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

Синтаксис

normalizeQueryKeepNames(x)

Аргументы

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

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

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

Пример

Запрос:

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 — Последовательность символов. Строка.

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

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

Пример

Запрос:

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

Результат:

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

normalizedQueryHashKeepNames

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

Синтаксис

normalizedQueryHashKeepNames(x)

Аргументы

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

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

Хэш-значение. 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

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

Синтаксис

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

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

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

примечание

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

Синтаксис

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

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

Запрос:

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. При первом выполнении 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, 'Too many') FROM numbers(10);

Результат:

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.

identity

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

Синтаксис

identity(x)

Пример

Запрос:

SELECT identity(42);

Результат:

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

getSetting

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

Синтаксис

getSetting('custom_setting');

Параметр

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

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

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

Пример

Запрос:

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

Результат:

Смотрите также

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

getSettingOrDefault

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

Синтаксис

getSettingOrDefault('custom_setting', default_value);

Параметр

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

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

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

Пример

Запрос:

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 учитывает их шкалы: подсчитывает результат по базовому целому типу, который равен (value * scale). Например: 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-порта native interface, который слушает этот сервер. Если выполнено в контексте распределенной таблицы, эта функция генерирует нормальный столбец со значениями, актуальными для каждого шарда. В противном случае она производит постоянное значение.

Синтаксис

tcpPort()

Аргументы

Нет.

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

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

Пример

Запрос:

SELECT tcpPort();

Результат:

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

Смотрите также

tcp_port

currentProfiles

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

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

Синтаксис

currentProfiles()

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

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

enabledProfiles

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

Синтаксис

enabledProfiles()

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

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

defaultProfiles

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

Синтаксис

defaultProfiles()

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

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

currentRoles

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

Синтаксис

currentRoles()

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

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

enabledRoles

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

Синтаксис

enabledRoles()

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

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

defaultRoles

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

Синтаксис

defaultRoles()

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

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

getServerPort

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

Синтаксис

getServerPort(port_name)

Аргументы

port_name — Имя порта сервера. String. Возможные значения:
- '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 текущего запроса. String

Пример

Запрос:

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 начального текущего запроса. String

Пример

Запрос:

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 партиции, к которой будет принадлежать строка. String.

Пример

Запрос:

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

См. также

Distributed Table Engine

shardCount

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

Синтаксис

shardCount()

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

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

См. также

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

getOSKernelVersion

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

Синтаксис

getOSKernelVersion()

Аргументы

Нет.

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

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

Пример

Запрос:

SELECT getOSKernelVersion();

Результат:

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

zookeeperSessionUptime

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

Синтаксис

zookeeperSessionUptime()

Аргументы

Нет.

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

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

Пример

Запрос:

SELECT zookeeperSessionUptime();

Результат:

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

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 - вероятность II рода). Float.
alpha — Необходимый уровень значимости теста (вероятность I рода). 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 - вероятность II рода). Integer или Float.
alpha — Необходимый уровень значимости теста (вероятность I рода). 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. Она была создана для совместимости с функцией CONNECTION_ID MySQL. Обычно она не используется в производственных запросах.

Пример

Запрос:

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

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

Map пар ключ-значение, относящихся к настроенному 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;

-- create two parts:

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

Синтаксис

lowCardinalityKeys(col)

Аргументы

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

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

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

Пример

Запрос:

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

-- create two parts:

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 из config или полностью квалифицированное доменное имя (FQDN) сервера, если не установлено.

Синтаксис

displayName()

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

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

Пример

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

<!-- It is the name that will be shown in the clickhouse-client.
     By default, anything with "production" will be highlighted in red in query prompt.
-->
<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

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

примечание

<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

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

примечание

<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

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

Синтаксис

getMergeTreeSetting('merge_tree_setting');

Параметр

merge_tree_setting — Название настройки. String.

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

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

Пример

SELECT getMergeTreeSetting('index_granularity');

Результат:

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

hostName​

getMacro​

fqdn​

basename​

visibleWidth​

toTypeName​

blockSize​

byteSize​

materialize​

ignore​

sleep​

sleepEachRow​

currentDatabase​

currentUser​

currentSchemas​

colorSRGBToOKLCH​

colorOKLCHToSRGB​

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​

hostName

getMacro

fqdn

basename

visibleWidth

toTypeName

blockSize

byteSize

materialize

ignore

sleep

sleepEachRow

currentDatabase

currentUser

currentSchemas

colorSRGBToOKLCH

colorOKLCHToSRGB

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