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

Примечание

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

FQDN

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

Возвращает полное доменное имя сервера ClickHouse.

Синтаксис

fqdn()

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

Аргументы

• Нет.

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

Возвращает полное доменное имя (FQDN) сервера ClickHouse. String

Примеры

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

SELECT fqdn()

┌─FQDN()──────────────────────────┐
│ clickhouse.us-east-2.internal │
└─────────────────────────────────┘

MACNumToString

Появилась в версии: v1.1

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

Синтаксис

MACNumToString(num)

Аргументы

• num — число типа UInt64. UInt64

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

Возвращает MAC-адрес в формате AA:BB:CC:DD:EE:FF. String

Примеры

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

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:00:11:22:33:44 │
└───────────────────┘

MACStringToNum

Добавлена в версии: v1.1

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

Синтаксис

MACStringToNum(s)

Аргументы

• s — строка с MAC-адресом. String

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

Возвращает число типа UInt64. UInt64

Примеры

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

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

1108152157446

MACStringToOUI

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

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

Синтаксис

MACStringToOUI(s)

Аргументы

• s — строка с MAC-адресом. String

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

Первые три октета в виде числа типа UInt64. UInt64

Примеры

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

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

20566

__applyFilter

Добавлена в версии: v25.10

Специальная функция для runtime-фильтрации при выполнении JOIN.

Синтаксис

__applyFilter(filter_name, key)

Аргументы

• filter_name — Внутреннее имя фильтра времени выполнения (runtime-фильтра). Формируется на этапе BuildRuntimeFilterStep. String
• key — Значение любого типа, которое проверяется на наличие в фильтре

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

False, если ключ должен быть отфильтрован Bool

Примеры

Пример

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

__patchPartitionID

Появилась в: v25.5

Внутренняя функция. Получает на вход имя части и хеш имён столбцов патч-части. Возвращает имя партиции патч-части. Аргумент должен быть корректным именем части; в противном случае поведение не определено.

Синтаксис

Аргументы

• Отсутствуют.

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

Примеры

authenticatedUser

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

Если пользователь сессии был переключён с помощью команды EXECUTE AS, эта функция возвращает имя исходного пользователя, который использовался для аутентификации и создания сессии. Псевдоним: authUser()

Синтаксис

authenticatedUser()

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

Аргументы

• Нет.

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

Имя аутентифицированного пользователя. String

Примеры

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

EXECUTE as u1;
            SELECT currentUser(), authenticatedUser();

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

bar

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

Строит столбчатую диаграмму. Рисует полосу с шириной, пропорциональной (x - min), и равной width символам, когда x = max. Полоса рисуется с точностью до одной восьмой символа.

Синтаксис

bar(x, min, max[, width])

Аргументы

• x — Отображаемое значение. (U)Int* или Float* или Decimal
• min — Минимальное значение. (U)Int* или Float* или Decimal
• max — Максимальное значение. (U)Int* или Float* или Decimal
• width — Необязательный параметр. Ширина полосы в символах. Значение по умолчанию — 80. const (U)Int* или const Float* или const Decimal

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

Возвращает строку с Unicode-гистограммой. String

Примеры

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

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

blockNumber

Добавлено в версии: v1.1

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

Синтаксис

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

blockSerializedSize

Добавлено в версии: v20.3

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

Синтаксис

blockSerializedSize(x1[, x2[, ...]])

Аргументы

• x1[, x2, ...] — Произвольное число значений, для которых нужно получить размер блока без сжатия. Any

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

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

Примеры

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

SELECT blockSerializedSize(maxState(1)) AS x;

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

blockSize

Появилась в версии: v1.1

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

Синтаксис

blockSize()

Аргументы

• Нет аргументов.

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

Возвращает количество строк в текущем блоке. UInt64

Примеры

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

SELECT blockSize()
FROM system.numbers LIMIT 5

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

buildId

Появилась в версии v20.5

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

Синтаксис

buildId()

Аргументы

• Нет.

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

Возвращает идентификатор сборки. String

Примеры

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

SELECT buildId()

┌─buildId()────────────────────────────────┐
│ AB668BEF095FAA6BD26537F197AC2AF48A927FB4 │
└──────────────────────────────────────────┘

byteSize

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

Возвращает оценку объёма памяти в байтах, занимаемой её аргументами в несжатом виде. Для аргументов типа String функция возвращает длину строки + 8 (длина). Если функция вызывается с несколькими аргументами, она суммирует их размеры в байтах.

Синтаксис

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

Аргументы

• arg1[, arg2, ...] — значения любого типа данных, для которых нужно оценить несжатый размер в байтах. Any

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

Возвращает примерный размер аргументов в памяти в байтах. UInt64

Примеры

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

SELECT byteSize('string')

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

Несколько аргументов

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

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

catboostEvaluate

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

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

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

1. Соберите библиотеку для оценки моделей CatBoost

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

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

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

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

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

2. Обучите модель catboost с помощью libcatboost

См. раздел Training and applying models о том, как обучать модели catboost на основе обучающего набора данных.

Синтаксис

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

Аргументы

• path_to_model — Путь к модели CatBoost. const String
• feature — Один или несколько признаков/аргументов модели. Float*

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

Возвращает результат оценки модели. Float64

Примеры

catboostEvaluate

SELECT catboostEvaluate('/root/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

4.695691092573497

colorOKLCHToSRGB

Добавлена в v25.7

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

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

Примечание

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

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

1. OKLCH в OKLab.
2. OKLab в линейный sRGB.
3. Линейный sRGB в sRGB.

Второй аргумент gamma используется на последнем этапе.

Для примеров цветов в пространстве OKLCH и их соответствия цветам sRGB см. http://oklch.com/.

Синтаксис

colorOKLCHToSRGB(tuple [, gamma])

Аргументы

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

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

Возвращает кортеж (R, G, B), представляющий значения цвета в пространстве sRGB. Tuple(Float64, Float64, Float64)

Примеры

Преобразование OKLCH в sRGB

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

colorSRGBToOKLCH

Добавлена в версии: v25.7

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

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

Примечание

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

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

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

Для примеров цветов в пространстве OKLCH и их соответствия цветам в sRGB см. http://OKLCH.com/.

Синтаксис

colorSRGBToOKLCH(tuple[, gamma])

Аргументы

• tuple — кортеж из трёх компонент R, G, B в диапазоне [0...255]. Tuple(UInt8, UInt8, UInt8)
• gamma — необязательный параметр. Показатель степени, который используется для линеаризации sRGB путём применения (x / 255)^gamma к каждому каналу x. По умолчанию — 2.2. Float64

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

Возвращает кортеж (L, C, H), представляющий значения в цветовом пространстве OKLCH. Tuple(Float64, Float64, Float64)

Примеры

Преобразование sRGB в OKLCH

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

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

connectionId

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

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

Синтаксис

connectionId()

Аргументы

• Отсутствуют.

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

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

Примеры

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

SELECT connectionId();

┌─connectionId()─┐
│              0 │
└────────────────┘

countDigits

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

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

Примечание

Эта функция учитывает масштаб десятичных значений, то есть вычисляет результат по базовому целочисленному типу, равному (value * scale).

Например:

• countDigits(42) = 2
• countDigits(42.000) = 5
• countDigits(0.04200) = 4

Совет

Вы можете проверять переполнение для Decimal64 с помощью countDigits(x) > 18, однако это медленнее, чем isDecimalOverflow.

Синтаксис

countDigits(x)

Аргументы

• x — целое или десятичное число. (U)Int* или Decimal

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

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

Примеры

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

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

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

currentDatabase

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

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

См. также команду SET.

Синтаксис

currentDatabase()

Псевдонимы: current_database, SCHEMA, DATABASE

Аргументы

• Отсутствуют.

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

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

Примеры

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

SELECT currentDatabase()

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

currentProfiles

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

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

Синтаксис

currentProfiles()

Аргументы

• Отсутствуют.

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

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

Примеры

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

SELECT currentProfiles();

┌─currentProfiles()─────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics'] │
└───────────────────────────────────────────────┘

currentQueryID

Впервые появилось в версии: v

Возвращает идентификатор текущего запроса.

Синтаксис

currentQueryID()

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

Аргументы

• Нет.

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

Примеры

Пример

SELECT currentQueryID();

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

currentRoles

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

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

Синтаксис

currentRoles()

Аргументы

• Отсутствуют.

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

Возвращает массив ролей, назначенных текущему пользователю. Array(String)

Примеры

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

SELECT currentRoles();

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:[email protected]'] │
└────────────────────────────────────────────────┘

currentSchemas

Впервые появилась в версии v23.7

Та же функция, что и currentDatabase, но

• принимает булевый аргумент, который игнорируется;
• возвращает имя базы данных в виде массива с одним значением.

Функция currentSchemas существует только для совместимости с PostgreSQL. Используйте вместо неё currentDatabase.

См. также команду SET.

Синтаксис

currentSchemas(bool)

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

Аргументы

• bool — булево значение, которое не используется. Bool

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

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

Примеры

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

SELECT currentSchemas(true)

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

currentUser

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

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

Синтаксис

currentUser()

Псевдонимы: current_user, user

Аргументы

• Нет.

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

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

Примеры

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

SELECT currentUser()

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

defaultProfiles

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

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

Синтаксис

defaultProfiles()

Аргументы

• Нет.

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

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

Примеры

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

SELECT defaultProfiles();

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

defaultRoles

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

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

Синтаксис

defaultRoles()

Аргументы

• Нет.

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

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

Примеры

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

SELECT defaultRoles();

┌─defaultRoles()─────────────────────────────────┐
│ ['sql-console-role:[email protected]'] │
└────────────────────────────────────────────────┘

defaultValueOfArgumentType

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

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

Синтаксис

defaultValueOfArgumentType(expression)

Аргументы

• expression — Значение произвольного типа или выражение, которое вычисляется в значение произвольного типа. Any

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

Возвращает значение 0 для чисел, пустую строку для строк или NULL для типов Nullable. Значение типа UInt8 или String или NULL

Примеры

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

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

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

Пример типа Nullable

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

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

defaultValueOfTypeName

Появилась в версии: v1.1

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

Синтаксис

defaultValueOfTypeName(type)

Аргументы

• type — строка, задающая имя типа. String

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

Возвращает значение по умолчанию для заданного имени типа: 0 для чисел, пустую строку для строк или NULL для типов Nullable UInt8 и String, а также для значения NULL.

Примеры

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

SELECT defaultValueOfTypeName('Int8');

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

Пример типа Nullable

SELECT defaultValueOfTypeName('Nullable(Int8)');

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

displayName

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

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

Синтаксис

displayName()

Аргументы

• Нет.

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

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

Примеры

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

SELECT displayName();

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

dumpColumnStructure

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

Выводит подробное описание внутренней структуры столбца и его типа данных.

Синтаксис

dumpColumnStructure(x)

Аргументы

• x — Значение, для которого нужно получить описание. Any

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

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

Примеры

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

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

enabledProfiles

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

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

Синтаксис

enabledProfiles()

Аргументы

• Отсутствуют.

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

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

Примеры

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

SELECT enabledProfiles();

┌─enabledProfiles()─────────────────────────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics', 'batch_processing'] │
└───────────────────────────────────────────────────────────────────┘

enabledRoles

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

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

Синтаксис

enabledRoles()

Аргументы

• Нет.

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

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

Примеры

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

SELECT enabledRoles();

┌─enabledRoles()─────────────────────────────────────────────────┐
│ ['general_data', 'sql-console-role:[email protected]'] │
└────────────────────────────────────────────────────────────────┘

errorCodeToName

Введена в версии v20.12

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

Синтаксис

errorCodeToName(error_code)

Аргументы

• error_code — код ошибки ClickHouse. (U)Int* или Float* или Decimal

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

Возвращает текстовое название error_code. String

Примеры

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

SELECT errorCodeToName(252);

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

file

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

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

См. также табличную функцию file.

Синтаксис

file(path[, default])

Аргументы

• path — Путь к файлу относительно user_files_path. Поддерживает шаблоны *, **, ?, {abc,def} и {N..M}, где N, M — числа, а 'abc', 'def' — строки. String
• default — Значение, которое возвращается, если файл не существует или к нему нет доступа. String или NULL

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

Возвращает содержимое файла в виде строки. String

Примеры

Добавление файлов в таблицу

INSERT INTO table SELECT file('a.txt'), file('b.txt');

filesystemAvailable

Добавлена в версии: v20.1

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

Синтаксис

filesystemAvailable([disk_name])

Аргументы

• disk_name — необязательный параметр. Имя диска, для которого нужно определить объём свободного пространства. Если не указано, используется диск по умолчанию. String или FixedString

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

Возвращает количество оставшегося свободного пространства в байтах. UInt64

Примеры

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

SELECT formatReadableSize(filesystemAvailable()) AS "Доступное место";

┌─Доступное пространство─┐
│ 30.75 GiB               │
└─────────────────────────┘

filesystemCapacity

Введена в версии v20.1

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

Синтаксис

filesystemCapacity([disk_name])

Аргументы

• disk_name — необязательный параметр. Имя диска, для которого нужно получить ёмкость. Если не указано, используется диск по умолчанию. String или FixedString

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

Возвращает ёмкость файловой системы в байтах. UInt64

Примеры

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

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

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

filesystemUnreserved

Добавлен в: v22.12

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

Синтаксис

filesystemUnreserved([disk_name])

Аргументы

• disk_name — необязательный параметр. Имя диска, для которого нужно определить общее количество свободного места. Если не указан, используется диск по умолчанию. String или FixedString

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

Возвращает количество свободного места в байтах. UInt64

Примеры

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

SELECT formatReadableSize(filesystemUnreserved()) AS "Свободное место";

┌─Свободное место─┐
│ 32.39 GiB       │
└─────────────────┘

finalizeAggregation

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

Функция принимает состояние агрегации и возвращает результат агрегации (или финализированное состояние при использовании комбинатора -State).

Синтаксис

finalizeAggregation(state)

Аргументы

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

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

Возвращает окончательный результат агрегации. Any

Примеры

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

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

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

Совместно с initializeAggregation

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

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

flipCoordinates

Добавлена в версии: v25.10

Меняет местами координаты Point, Ring, Polygon или MultiPolygon. Для Point просто переставляет координаты. Для массивов рекурсивно применяет то же преобразование к каждой паре координат.

Синтаксис

flipCoordinates(geometry)

Аргументы

• geometry — Геометрия для преобразования. Поддерживаемые типы: Point (Tuple(Float64, Float64)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)).

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

Геометрия с переставленными координатами. Тип совпадает с входным типом. Point или Ring или Polygon или MultiPolygon

Примеры

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2.0, 1.0)

кольцо

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

[(2.0, 1.0), (4.0, 3.0)]

многоугольник

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

[[(2.0, 1.0), (4.0, 3.0)], [(6.0, 5.0), (8.0, 7.0)]]

formatQuery

Введена в версии: v

Возвращает отформатированный вариант заданного SQL‑запроса, возможно в несколько строк. Выбрасывает исключение при ошибке разбора. [example:multiline]

Синтаксис

formatQuery(query)

Аргументы

• query — SQL-запрос, который нужно отформатировать. String

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

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

Примеры

multiline

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

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

formatQueryOrNull

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

Возвращает отформатированный SQL-запрос, который при необходимости может занимать несколько строк. В случае ошибки синтаксического анализа возвращает NULL. [example:multiline]

Синтаксис

formatQueryOrNull(query)

Аргументы

• query — SQL-запрос, который нужно отформатировать. String

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

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

Примеры

multiline

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

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

formatQuerySingleLine

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

Аналогично formatQuery(), но возвращаемая форматированная строка не содержит разрывов строк. Выбрасывает исключение при ошибке разбора. [example:multiline]

Синтаксис

formatQuerySingleLine(query)

Аргументы

• query — SQL-запрос, который нужно отформатировать. String

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

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

Примеры

multiline

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

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatQuerySingleLineOrNull

Появилась в версии: v

Аналогично функции formatQuery(), но возвращаемая отформатированная строка не содержит переводов строк. Возвращает NULL в случае ошибки разбора. [example:multiline]

Синтаксис

formatQuerySingleLineOrNull(query)

Аргументы

• query — SQL-запрос для форматирования. String

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

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

Примеры

многострочный

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

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatReadableDecimalSize

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

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

Обратной операцией к этой функции является parseReadableSize.

Синтаксис

formatReadableDecimalSize(x)

Аргументы

• x — размер в байтах. UInt64

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

Возвращает строку с удобочитаемым, округлённым размером и суффиксом. String

Примеры

Форматирование размеров файлов

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

formatReadableQuantity

Введена в версии: v20.10

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

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

Синтаксис

formatReadableQuantity(x)

Аргументы

• x — число, которое нужно отформатировать. UInt64

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

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

Примеры

Форматирование чисел с суффиксами

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

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 тыс.         │
│        1234000 │ 1.23 млн          │
│     4567000000 │ 4.57 млрд         │
│ 98765432101234 │ 98.77 трлн        │
└────────────────┴───────────────────┘

formatReadableSize

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

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

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

Синтаксис

formatReadableSize(x)

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

Аргументы

• x — размер в байтах. UInt64

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

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

Примеры

Форматирование размеров файлов

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

formatReadableTimeDelta

Добавлена в: v20.12

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

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

Синтаксис

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

Аргументы

• column — Столбец с числовым значением дельты времени. Float64
• maximum_unit — Необязательный параметр. Максимальная единица времени для отображения. Допустимые значения: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Значение по умолчанию: years. const String
• minimum_unit — Необязательный параметр. Минимальная единица времени для отображения. Все более мелкие единицы усекаются. Допустимые значения: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Если явно заданное значение больше maximum_unit, будет сгенерировано исключение. Значение по умолчанию: seconds, если maximum_unit равно seconds или больше, иначе nanoseconds. const String

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

Возвращает дельту времени в виде строки. String

Примеры

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

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

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 минута 40 секунд                                             │
│      12345 │ 3 часа 25 минут 45 секунд                                      │
│  432546534 │ 13 лет 8 месяцев 17 дней 7 часов 48 минут 54 секунды          │
└────────────┴────────────────────────────────────────────────────────────────┘

С максимальной единицей измерения

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

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 минута и 40 секунд                                            │
│      12345 │ 205 минут и 45 секунд                                           │
│  432546534 │ 7209108 минут и 54 секунды                                      │
└────────────┴─────────────────────────────────────────────────────────────────┘

generateRandomStructure

Впервые появилась в версии v23.5

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

Синтаксис

generateRandomStructure([number_of_columns, seed])

Аргументы

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

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

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

Примеры

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

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

c1 Map(UInt256, UInt16)

с заданным значением seed

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

generateSerialID

Впервые добавлена в: v25.1

Генерирует и возвращает последовательные числа, начиная с предыдущего значения счётчика. Эта функция принимает строковый аргумент — идентификатор серии, а также необязательное начальное значение. Сервер должен быть настроен с Keeper. Серии хранятся в узлах Keeper по пути, который можно задать параметром series_keeper_path в конфигурации сервера.

Синтаксис

generateSerialID(series_identifier[, start_value])

Аргументы

• series_identifier — идентификатор серии const String
• start_value — необязательный параметр. Начальное значение счётчика, по умолчанию 0. Примечание: это значение используется только при создании новой серии и игнорируется, если серия уже существует UInt*

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

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

Примеры

первый вызов

SELECT generateSerialID('id1')

┌─generateSerialID('id1')──┐
│                        1 │
└──────────────────────────┘

второй вызов

SELECT generateSerialID('id1')

┌─generateSerialID('id1')──┐
│                        2 │
└──────────────────────────┘

обращение к столбцу

SELECT *, generateSerialID('id1') FROM test_table

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')──┐
│         1 │      3 │   3 │                        3 │
│         1 │      1 │   1 │                        4 │
│         1 │      2 │   2 │                        5 │
│         1 │      5 │   5 │                        6 │
│         1 │      4 │   4 │                        7 │
└───────────┴────────┴─────┴──────────────────────────┘

с начальным значением

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)──┐
│                           100 │
└───────────────────────────────┘

со стартовым значением, второй вызов

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)──┐
│                           101 │
└───────────────────────────────┘

getClientHTTPHeader

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

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

Примечание

Необходимо включить настройку allow_get_client_http_header

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

Для этой функции в HTTP-заголовках учитывается регистр. Если функция используется в контексте распределённого запроса, она возвращает непустой результат только на инициирующем узле.

Синтаксис

getClientHTTPHeader(name)

Аргументы

• name — имя HTTP-заголовка. String

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

Возвращает значение заголовка. String

Примеры

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

SELECT getClientHTTPHeader('Content-Type');

┌─getClientHTTPHeader('Content-Type')─┐
│ application/x-www-form-urlencoded   │
└─────────────────────────────────────┘

getMacro

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

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

Синтаксис

getMacro(name)

Аргументы

• name — Имя макроса, значение которого нужно получить. const String

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

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

Примеры

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

SELECT getMacro('test');

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

getMaxTableNameLengthForDatabase

Появилась в версии: v

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

Синтаксис

getMaxTableNameLengthForDatabase(database_name)

Аргументы

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

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

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

Примеры

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

SELECT getMaxTableNameLengthForDatabase('default');

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

getMergeTreeSetting

Введена в версии: v25.6

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

Синтаксис

getMergeTreeSetting(setting_name)

Аргументы

• setting_name — имя настройки. String

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

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

Примеры

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

SELECT getMergeTreeSetting('index_granularity');

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

getOSKernelVersion

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

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

Синтаксис

getOSKernelVersion()

Аргументы

• Нет.

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

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

Примеры

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

SELECT getOSKernelVersion();

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

getServerPort

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

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

Синтаксис

getServerPort(port_name)

Аргументы

• port_name — Имя порта. String

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

Возвращает номер серверного порта. UInt16

Примеры

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

SELECT getServerPort('tcp_port');

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

getServerSetting

Введено в: v25.6

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

Синтаксис

getServerSetting(setting_name')

Аргументы

• setting_name — Имя настройки сервера. String

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

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

Примеры

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

SELECT getServerSetting('allow_use_jemalloc_memory');

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

getSetting

Появилась в версии: v20.7

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

Синтаксис

getSetting(setting_name)

Аргументы

• setting_Name — Имя настройки. const String

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

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

Примеры

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

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

┌─getSetting('⋯_analyzer')─┐
│ true                     │
└──────────────────────────┘
┌─getSetting('⋯_analyzer')─┐
│ false                    │
└──────────────────────────┘

getSettingOrDefault

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

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

Синтаксис

getSettingOrDefault(setting_name, default_value)

Аргументы

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

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

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

Примеры

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

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

my_value
100
NULL

getSizeOfEnumType

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

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

Синтаксис

getSizeOfEnumType(x)

Аргументы

• x — значение типа Enum. Enum

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

Возвращает количество полей со значениями типа Enum на входе функции. UInt8/16

Примеры

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

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

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

getSubcolumn

Введена в версии: v

Принимает выражение или идентификатор и константную строку с именем подстолбца.

Возвращает запрошенный подстолбец, извлечённый из выражения.

Синтаксис

Аргументы

• Нет.

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

Примеры

getSubcolumn

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')

getTypeSerializationStreams

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

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

Синтаксис

getTypeSerializationStreams(col)

Аргументы

• col — столбец или строковое представление типа данных, на основе которого определяется тип данных. Any

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

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

Примеры

tuple

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

['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

map

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

['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

globalVariable

Добавлено в: v20.5

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

Синтаксис

globalVariable(name)

Аргументы

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

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

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

Примеры

globalVariable

SELECT globalVariable('max_allowed_packet')

67108864

hasColumnInTable

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

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

Синтаксис

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

Аргументы

• database — Имя базы данных. const String
• table — Имя таблицы. const String
• column — Имя столбца. const String
• hostname — Необязательный параметр. Имя удалённого сервера, на котором выполняется проверка. const String
• username — Необязательный параметр. Имя пользователя для удалённого сервера. const String
• password — Необязательный параметр. Пароль для удалённого сервера. const String

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

Возвращает 1, если указанный столбец существует, и 0 в противном случае. UInt8

Примеры

Проверка существующего столбца

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

1

Проверка отсутствующего столбца

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

0

hasThreadFuzzer

Появилась в версии v20.6

Возвращает, включён ли thread fuzzer. Эта функция полезна только для тестирования и отладки.

Синтаксис

hasThreadFuzzer()

Аргументы

• Нет.

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

Возвращает, работает ли Thread Fuzzer. UInt8

Примеры

Проверка статуса Thread Fuzzer

SELECT hasThreadFuzzer()

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

hostName

Введена в версии: v20.5

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

Синтаксис

hostName()

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

Аргументы

• Нет.

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

Возвращает имя хоста. String

Примеры

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

SELECT hostName()

┌─hostName()─┐
│ clickhouse │
└────────────┘

icebergBucket

Введена в версии: v25.5

Реализует логику bucket-преобразования Iceberg

Синтаксис

icebergBucket(N, value)

Аргументы

• N — Количество бакетов (модуль). const (U)Int*
• value — Исходное значение для преобразования. (U)Int* или Bool или Decimal или Float* или String или FixedString или UUID или Date или Time или DateTime

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

Возвращает 32-битный хеш исходного значения. Int32

Примеры

Пример

SELECT icebergBucket(5, 1.0 :: Float32)

4

icebergTruncate

Добавлен в: v25.3

Реализует логику Iceberg-трансформации truncate: http://iceberg.apache.org/spec/#truncate-transform-details.

Синтаксис

icebergTruncate(N, value)

Аргументы

• value — значение для преобразования. String или (U)Int* или Decimal

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

Тип совпадает с типом аргумента.

Примеры

Пример

SELECT icebergTruncate(3, 'iceberg')

ice

identity

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

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

Синтаксис

identity(x)

Аргументы

• x — входное значение. Any

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

Возвращает входное значение без изменений. Any

Примеры

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

SELECT identity(42)

42

ignore

Появилась в версии v1.1

Принимает произвольные аргументы и безусловно возвращает 0.

Синтаксис

ignore(x)

Аргументы

• x — входное значение, которое не используется и передаётся только для предотвращения синтаксической ошибки. Any

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

Всегда возвращает 0. UInt8

Примеры

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

SELECT ignore(0, 'ClickHouse', NULL)

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

indexHint

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

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

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

Синтаксис

indexHint(expression)

Аргументы

• expression — Любое выражение для выбора диапазона индекса. Expression

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

Во всех случаях возвращает значение 1. UInt8

Примеры

Пример использования с фильтрацией по дате

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

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

initialQueryID

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

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

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

Синтаксис

initialQueryID()

Псевдонимы: initial_query_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(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initialQueryStartTime

Введено в: v25.4

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

Синтаксис

initialQueryStartTime()

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

Аргументы

• Нет.

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

Возвращает время начала исходного (первоначального) запроса. 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(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initializeAggregation

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

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

Синтаксис

initializeAggregation(aggregate_function, arg1[, arg2, ...])

Аргументы

• aggregate_function — имя агрегатной функции для инициализации. String
• arg1[, arg2, ...] — аргументы агрегатной функции. Any

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

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

Примеры

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

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

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

Использование с sumState и finalizeAggregation

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

isConstant

Добавлена в версии: v20.3

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

Синтаксис

isConstant(x)

Аргументы

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

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

Возвращает 1, если x — константа, и 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 │
└────────────────────┘

Поведение функции now()

SELECT isConstant(now())

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

isDecimalOverflow

Добавлено в: v20.8

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

Синтаксис

isDecimalOverflow(value[, precision])

Аргументы

• value — десятичное значение для проверки. Decimal
• precision — необязательный параметр. Точность типа Decimal. Если параметр опущен, используется исходная точность первого аргумента. UInt8

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

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

Примеры

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

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

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

joinGet

Добавлена в версии: v18.16

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

Примечание

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

Синтаксис

joinGet(join_storage_table_name, value_column, join_keys)

Аргументы

• join_storage_table_name — идентификатор, который указывает, где выполнять поиск. Идентификатор ищется в базе данных по умолчанию (см. параметр default_database в конфигурационном файле). Чтобы переопределить базу данных по умолчанию, используйте запрос USE database_name или укажите базу данных и таблицу через точку, например database_name.table_name. String
• value_column — имя столбца таблицы, который содержит требуемые данные. const String
• join_keys — список ключей соединения. Any

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

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

Примеры

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

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 joinGet(db_test.id_val, 'val', toUInt32(1));

┌─joinGet(db_test.id_val, 'val', toUInt32(1))─┐
│                                          11 │
└─────────────────────────────────────────────┘

Использование с таблицей текущей базы данных

USE db_test;
SELECT joinGet(id_val, 'val', toUInt32(2));

┌─joinGet(id_val, 'val', toUInt32(2))─┐
│                                  12 │
└─────────────────────────────────────┘

Использование массивов в качестве ключей соединения

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', 1, 11);

┌─joinGet(some_table, 'name', 1, 11)─┐
│ a                                  │
└────────────────────────────────────┘

joinGetOrNull

Введена в версии: v20.4

Позволяет извлекать данные из таблицы так же, как из словаря. Извлекает данные из таблиц Join, используя указанный ключ соединения. В отличие от joinGet, возвращает NULL, когда ключ отсутствует.

Примечание

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

Синтаксис

joinGetOrNull(join_storage_table_name, value_column, join_keys)

Аргументы

• join_storage_table_name — идентификатор, определяющий, где выполнять поиск. По умолчанию поиск выполняется в базе данных по умолчанию (см. параметр default_database в конфигурационном файле). Чтобы переопределить базу данных по умолчанию, используйте запрос USE database_name или укажите базу данных и таблицу через точку, например database_name.table_name. String
• value_column — имя столбца таблицы, который содержит требуемые данные. const String
• join_keys — список ключей соединения. Any

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

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

Примеры

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

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 joinGetOrNull(db_test.id_val, 'val', toUInt32(1)), joinGetOrNull(db_test.id_val, 'val', toUInt32(999));

┌─joinGetOrNull(db_test.id_val, 'val', toUInt32(1))─┬─joinGetOrNull(db_test.id_val, 'val', toUInt32(999))─┐
│                                                11 │                                                ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

lowCardinalityIndices

Появилась в версии: v18.12

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

Синтаксис

lowCardinalityIndices(col)

Аргументы

• col — столбец с низкой кардинальностью. LowCardinality

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

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

Примеры

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

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

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

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

SELECT s, lowCardinalityIndices(s) FROM test;

┌─s──┬─lowCardinalityIndices(s)─┐
│ ab │                        1 │
│ cd │                        2 │
│ ab │                        1 │
│ ab │                        1 │
│ df │                        3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
│ ef │                        1 │
│ cd │                        2 │
│ ab │                        3 │
│ cd │                        2 │
│ ef │                        1 │
└────┴──────────────────────────┘

lowCardinalityKeys

Появилась в версии: v18.12

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

Синтаксис

lowCardinalityKeys(col)

Аргументы

• col — столбец LowCardinality. LowCardinality

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

Возвращает ключи словаря. UInt64

Примеры

lowCardinalityKeys

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

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

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

SELECT s, lowCardinalityKeys(s) FROM test;

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

materialize

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

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

Синтаксис

materialize(x)

Аргументы

• x — константа. Any

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

Возвращает полный столбец, содержащий константное значение. Any

Примеры

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

-- В примере ниже функция `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

minSampleSizeContinuous

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

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

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

Синтаксис

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

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

Аргументы

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

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

Возвращает именованный Tuple с 3 элементами: minimum_sample_size, detect_range_lower и detect_range_upper. Это соответственно: требуемый размер выборки, нижняя граница диапазона значений, не обнаруживаемых при возвращённом требуемом размере выборки и вычисляемая как baseline * (1 - mde), и верхняя граница диапазона значений, не обнаруживаемых при возвращённом требуемом размере выборки и вычисляемая как baseline * (1 + mde) (Float64). Tuple(Float64, Float64, Float64)

Примеры

minSampleSizeContinuous

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

(616.2931945826209,108.8825,115.6175)

minSampleSizeConversion

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

Вычисляет минимально необходимый размер выборки для 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, detect_range_lower, detect_range_upper. Это, соответственно: требуемый размер выборки; нижняя граница диапазона значений, не обнаруживаемых при полученном требуемом размере выборки, вычисляемая как baseline - mde; верхняя граница диапазона значений, не обнаруживаемых при полученном требуемом размере выборки, вычисляемая как baseline + mde. Tuple(Float64, Float64, Float64)

Примеры

minSampleSizeConversion

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

(3396.077603219163,0.22,0.28)

neighbor

Введена в: v20.1

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

Функцию можно включить, установив allow_deprecated_error_prone_window_functions = 1.

Синтаксис

neighbor(column, offset[, default_value])

Аргументы

• column — Исходный столбец. Any
• offset — Смещение относительно текущей строки. Положительные значения — вперёд, отрицательные — назад. Integer
• default_value — Необязательный аргумент. Значение, которое возвращается, если смещение выходит за границы данных. Если не указано, используется значение по умолчанию для типа столбца. Any

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

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

Примеры

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

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

nested

Впервые появилась в: v

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

Возвращает массив кортежей, сформированных из нескольких массивов.

Первый аргумент должен быть константным массивом строк (String), задающим имена результирующего Tuple. Остальные аргументы должны быть массивами одинакового размера.

Синтаксис

Аргументы

• Отсутствуют.

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

Примеры

Вложенный

SELECT nested(['keys', 'values'], ['key_1', 'key_2'], ['value_1','value_2'])

normalizeQuery

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

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

Синтаксис

normalizeQuery(x)

Аргументы

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

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

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

Примеры

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

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

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

normalizeQueryKeepNames

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

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

Синтаксис

normalizeQueryKeepNames(x)

Аргументы

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

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

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

Примеры

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

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

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

normalizedQueryHash

Введена в версии: v20.8

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

Синтаксис

normalizedQueryHash(x)

Аргументы

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

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

Возвращает 64-битное хэш-значение. UInt64

Примеры

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

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

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

normalizedQueryHashKeepNames

Впервые появилась в версии v21.2

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

Синтаксис

normalizedQueryHashKeepNames(x)

Аргументы

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

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

Возвращает 64-битное значение хэша. 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 │
└──────────────────────────────┘

parseReadableSize

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

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

Обратными операциями к этой функции являются formatReadableSize и formatReadableDecimalSize.

Синтаксис

parseReadableSize(x)

Аргументы

• x — Человекочитаемый размер в единицах ISO/IEC 80000-13 или в десятичных единицах байта. String

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

Возвращает количество байт, округлённое вверх до ближайшего целого числа. UInt64

Примеры

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

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

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

parseReadableSizeOrNull

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

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

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

Синтаксис

parseReadableSizeOrNull(x)

Аргументы

• x — Размер в читаемом виде в единицах ISO/IEC 80000-13 или в десятичных единицах байта. String

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

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

Примеры

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

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

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

parseReadableSizeOrZero

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

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

Обратными операциями к этой функции являются formatReadableSize и formatReadableDecimalSize.

Синтаксис

parseReadableSizeOrZero(x)

Аргументы

• x — Размер в человекочитаемом формате с использованием единиц по ISO/IEC 80000-13 или десятичных единиц. String

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

Возвращает количество байт, округлённое до ближайшего большего целого, или 0, если не удалось распознать входное значение. UInt64

Примеры

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

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

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

parseTimeDelta

Введена в версии: v22.7

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

Строка временного интервала использует следующие обозначения единиц времени:

• years, year, yr, y
• months, month, mo
• weeks, week, w
• days, day, d
• hours, hour, hr, h
• minutes, minute, min, m
• seconds, second, sec, s
• milliseconds, millisecond, millisec, ms
• microseconds, microsecond, microsec, μs, µs, us
• nanoseconds, nanosecond, nanosec, ns

Несколько единиц времени можно комбинировать, используя разделители (пробел, ;, -, +, ,, :).

Длительности года и месяца являются приближенными: год — 365 дней, месяц — 30,5 дня.

Синтаксис

parseTimeDelta(timestr)

Аргументы

• timestr — последовательность цифр, за которой следует обозначение единицы времени. String

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

Количество секунд. Float64

Примеры

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

SELECT parseTimeDelta('11s+22min')

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

Составные единицы времени

SELECT parseTimeDelta('1yr2mo')

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

partitionId

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

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

Примечание

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

Синтаксис

partitionId(column1[, column2, ...])

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

Аргументы

• column1, column2, ... — Столбцы, для которых возвращается идентификатор партиции.

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

Возвращает идентификатор партиции, к которой принадлежит строка. 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             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

queryID

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

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

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

Синтаксис

queryID()

Псевдонимы: query_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(DISTINCT t)─┐
│                 3 │
└───────────────────┘

revision

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

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

Синтаксис

revision()

Аргументы

• Отсутствуют.

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

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

Примеры

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

SELECT revision()

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

rowNumberInAllBlocks

Добавлена в версии v1.1

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

Синтаксис

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

rowNumberInBlock

Добавлена в версии v1.1

Для каждого блока функция 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 │
└────────────────────┘

runningAccumulate

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

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

Устарело

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

Синтаксис

runningAccumulate(agg_state[, grouping])

Аргументы

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

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

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

Примеры

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

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

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

runningConcurrency

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

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

Требования

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

Устарело

Рекомендуется вместо этого использовать оконные функции.

Синтаксис

runningConcurrency(start, end)

Аргументы

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

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

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

Примеры

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

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

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

runningDifference

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

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

Устарело

Возвращает разности только внутри текущего обрабатываемого блока данных. Из-за такого потенциально ошибочного поведения функция признана устаревшей. Рекомендуется использовать вместо неё оконные функции.

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

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

Синтаксис

runningDifference(x)

Аргументы

• x — столбец, для которого вычисляется разность между соседними значениями. Any

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

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

Примеры

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

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

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

Пример влияния размера блока

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

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

runningDifferenceStartingWithFirstValue

Введена в: v1.1

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

Устарело

Возвращает разности только внутри текущего обрабатываемого блока данных. Из‑за такого потенциально ошибочного поведения функция объявлена устаревшей. Рекомендуется вместо неё использовать оконные функции.

Вы можете использовать SETTING allow_deprecated_error_prone_window_functions, чтобы разрешить использование этой функции.

Синтаксис

runningDifferenceStartingWithFirstValue(x)

Аргументы

• x — столбец, для которого вычисляется разность между последовательными значениями. Any

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

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

Примеры

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

SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

┌─number─┬─diff─┐
│      0 │    0 │
│      1 │    1 │
│      2 │    1 │
│      3 │    1 │
│      4 │    1 │
└────────┴──────┘

serverUUID

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

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

Синтаксис

serverUUID()

Аргументы

• Нет.

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

Возвращает случайный UUID сервера. UUID

Примеры

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

SELECT serverUUID();

┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f     │
└──────────────────────────────────────────┘

shardCount

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

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

Синтаксис

shardCount()

Аргументы

• Нет аргументов.

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

Возвращает общее количество сегментов или 0. UInt32

Примеры

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

-- См. пример shardNum() выше, который также демонстрирует shardCount()
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

┌─shardCount()─┐
│            2 │
│            2 │
└──────────────┘

shardNum

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

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

Синтаксис

shardNum()

Аргументы

• Нет.

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

Возвращает индекс сегмента или константу 0. UInt32

Примеры

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

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

showCertificate

Появился в версии: v22.6

Отображает информацию о текущем SSL-сертификате (Secure Sockets Layer) сервера, если он настроен. См. раздел Configuring 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'}

sleep

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

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

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

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

Примечание

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

По соображениям безопасности функция может выполняться только в профиле пользователя по умолчанию (с включённым параметром allow_sleep).

Синтаксис

sleep(seconds)

Аргументы

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

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

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

Примеры

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

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

┌─sleep(2)─┐
│        0 │
└──────────┘
Получена 1 строка. Прошло: 2.012 сек.

sleepEachRow

Введено в версии v1.1

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

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

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

Примечание

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

Синтаксис

sleepEachRow(seconds)

Аргументы

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

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

Возвращает 0 для каждой строки. UInt8

Примеры

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

-- Вывод будет задержан с паузой 0,5 секунды между каждой строкой.
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

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

structureToCapnProtoSchema

Появилась в версии: v

Функция, которая преобразует структуру таблицы ClickHouse в схему формата CapnProto

Синтаксис

Аргументы

• Нет.

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

Примеры

random

SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw

struct MessageName
{
    s @0 : Data;
    x @1 : UInt32;
}

structureToProtobufSchema

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

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

Эта функция принимает определение структуры таблицы ClickHouse и преобразует его в определение схемы Protocol Buffers (Protobuf) в синтаксисе proto3. Это полезно для генерации схем Protobuf, соответствующих структурам таблиц ClickHouse для обмена данными.

Синтаксис

structureToProtobufSchema(structure, message_name)

Аргументы

• structure — определение структуры таблицы ClickHouse в виде строки (например, 'column1 Type1, column2 Type2'). String
• message_name — имя для типа сообщения Protobuf в сгенерированной схеме. String

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

Возвращает определение схемы Protobuf в синтаксисе proto3, соответствующее входной структуре ClickHouse. String

Примеры

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

SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;

syntax = "proto3";

message MessageName
{
    bytes s = 1;
    uint32 x = 2;
}

tcpPort

Появилась в версии: v20.12

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

Синтаксис

tcpPort()

Аргументы

• Отсутствуют.

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

Возвращает номер TCP-порта. UInt16

Примеры

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

SELECT tcpPort()

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

throwIf

Добавлена в версии: v1.1

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

Синтаксис

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

Аргументы

• x — проверяемое условие. Any
• message — необязательный параметр. Пользовательское сообщение об ошибке. const String
• error_code — необязательный параметр. Пользовательский код ошибки. const Int8/16/32

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

Возвращает 0, если условие ложно, и генерирует исключение, если условие истинно. UInt8

Примеры

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

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

↙ Прогресс: 0.00 строк, 0.00 B (0.00 строк/с., 0.00 B/с.) Получено исключение от сервера (версия 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.

toColumnTypeName

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

Возвращает внутреннее имя типа данных у переданного значения. В отличие от функции toTypeName, возвращаемый тип данных потенциально включает внутренние обёртки столбцов, такие как Const и LowCardinality.

Синтаксис

toColumnTypeName(value)

Аргументы

• value — Значение, для которого возвращается внутренний тип данных. Any

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

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

Примеры

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

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

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

toTypeName

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

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

Синтаксис

toTypeName(x)

Аргументы

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

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

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

Примеры

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

SELECT toTypeName(123)

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

transactionID

Появилась в версии: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

Примечание

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

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

Дополнительные сведения см. на странице Transactional (ACID) support.

Синтаксис

transactionID()

Аргументы

• Отсутствуют.

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

Возвращает кортеж, состоящий из start_csn, local_tid и host_id.

• start_csn: глобальный последовательный номер, последний commit timestamp, который был виден на момент начала этой транзакции.
• local_tid: локальный последовательный номер, уникальный для каждой транзакции, запущенной этим хостом в пределах конкретного start_csn.
• host_id: UUID хоста, на котором была запущена эта транзакция.
  Tuple(UInt64, UInt64, UUID)

Примеры

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

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

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

transactionLatestSnapshot

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

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

Примечание

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

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

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

Синтаксис

transactionLatestSnapshot()

Аргументы

• Отсутствуют.

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

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

Примеры

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

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

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

transactionOldestSnapshot

Добавлено в: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

Примечание

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

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

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

Синтаксис

transactionOldestSnapshot()

Аргументы

• Нет.

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

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

Примеры

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

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

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

transform

Появилась в версии: v1.1

Преобразует значение в соответствии с явно заданным отображением одних элементов в другие.

Существует два варианта этой функции:

• transform(x, array_from, array_to, default) — преобразует x, используя массивы отображения со значением по умолчанию для несовпадающих элементов
• transform(x, array_from, array_to) — выполняет то же преобразование, но возвращает исходное x, если совпадение не найдено

Функция ищет значение x в array_from и возвращает соответствующий элемент из array_to с тем же индексом. Если значение x не найдено в array_from, возвращается либо значение default (4‑параметрическая версия), либо исходное x (3‑параметрическая версия). Если в array_from существует несколько совпадающих элементов, возвращается элемент, соответствующий первому совпадению.

Требования:

• array_from и array_to должны иметь одинаковое количество элементов
• Для 4‑параметрической версии: transform(T, Array(T), Array(U), U) -> U, где T и U могут быть разными, но совместимыми типами
• Для 3‑параметрической версии: transform(T, Array(T), Array(T)) -> T, где все типы должны совпадать

Синтаксис

transform(x, array_from, array_to[, default])

Аргументы

• x — Значение для преобразования. (U)Int* или Decimal или Float* или String или Date или DateTime
• array_from — Константный массив значений, в котором выполняется поиск совпадений. Array((U)Int*) или Array(Decimal) или Array(Float*) или Array(String) или Array(Date) или Array(DateTime)
• array_to — Константный массив значений, которые возвращаются для соответствующих совпадений в array_from. Array((U)Int*) или Array(Decimal) или Array(Float*) или Array(String) или Array(Date) или Array(DateTime)
• default — Необязательный аргумент. Значение, которое возвращается, если x не найден в array_from. Если аргумент опущен, возвращается x без изменений. (U)Int* или Decimal или Float* или String или Date или DateTime

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

Возвращает соответствующее значение из array_to, если x совпадает с элементом в array_from. В противном случае возвращает default (если он указан) или x (если default не указан). Any

Примеры

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

SELECT
transform(SearchEngineID, [2, 3], ['Яндекс', 'Google'], 'Другое') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC

┌─title─────┬──────c─┐
│ Yandex    │ 498635 │
│ Google    │ 229872 │
│ Другое    │ 104472 │
└───────────┴────────┘

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

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

uniqThetaIntersect

Добавлена в: v22.9

Два объекта uniqThetaSketch для выполнения операции пересечения множеств (∩); результатом является новый uniqThetaSketch.

Синтаксис

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

Аргументы

• uniqThetaSketch — объект типа uniqThetaSketch. Tuple или Array или Date или DateTime или String или (U)Int* или Float* или Decimal

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

Новый объект uniqThetaSketch, содержащий результат пересечения. UInt64

Примеры

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

SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

uniqThetaNot

Впервые представлено в: v22.9

Два объекта uniqThetaSketch для вычисления выражения a_not_b (операция над множествами ×); результатом является новый uniqThetaSketch.

Синтаксис

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

Аргументы

• uniqThetaSketch — объект типа uniqThetaSketch. Tuple или Array или Date или DateTime или String или (U)Int* или Float* или Decimal

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

Возвращает новый uniqThetaSketch, содержащий результат операции a_not_b. Значение типа UInt64

Примеры

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

SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

uniqThetaUnion

Появилась в версии v22.9

Выполняет операцию объединения множеств (∪) над двумя объектами uniqThetaSketch и возвращает новый uniqThetaSketch.

Синтаксис

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

Аргументы

• uniqThetaSketch — объект типа uniqThetaSketch. Tuple или Array или Date или DateTime или String или (U)Int* или Float* или Decimal

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

Возвращает новый uniqThetaSketch, содержащий результат объединения. UInt64

Примеры

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

SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

uptime

Добавлена в версии v1.1

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

Синтаксис

uptime()

Аргументы

• Нет.

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

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

Примеры

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

SELECT uptime() AS Uptime

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

variantElement

Введена в версии: v25.2

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

Синтаксис

variantElement(variant, type_name[, default_value])

Аргументы

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

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

Возвращает столбец с указанным вариантом типа, извлечённым из столбца Variant. Any

Примеры

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

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

Введена в версии: v24.2

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

Синтаксис

variantType(variant)

Аргументы

• variant — столбец Variant. Variant

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

Возвращает столбец Enum с именем типа Variant для каждой строки. Enum

Примеры

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

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

version

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

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

Синтаксис

version()

Аргументы

• Нет.

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

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

Примеры

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

SELECT version()

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

visibleWidth

Появилась в версии: v1.1

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

Синтаксис

visibleWidth(x)

Аргументы

• x — значение любого типа данных. Any

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

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

Примеры

Вычисление видимой ширины значения NULL

SELECT visibleWidth(NULL)

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

zookeeperSessionUptime

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

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

Синтаксис

zookeeperSessionUptime()

Аргументы

• Отсутствуют.

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

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

Примеры

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

SELECT zookeeperSessionUptime();

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