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

Примечание

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

FQDN

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

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

Синтаксис

fqdn()

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

Аргументы

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

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

Возвращает полное доменное имя сервера 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

__filterContains

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

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

Синтаксис

__filterContains(filter_name, key)

Аргументы

• filter_name — внутреннее имя runtime-фильтра. Создаётся при выполнении BuildRuntimeFilterStep. String
• key — значение произвольного типа, для которого проверяется его наличие в фильтре

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

True, если ключ был найден в фильтре 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 │
└─────────────┘

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 — это библиотека градиентного бустинга с открытым исходным кодом, разработанная компанией Yandex для задач машинного обучения. Принимает путь к модели 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 см. на сайте https://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 (хрома, >= 0) и H (тон в градусах из диапазона [0...360]). OKLab/OKLCH спроектировано как перцептивно равномерное при сохранении низкой вычислительной стоимости.

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

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

Для примеров цветов в пространстве OKLCH и их соответствия цветам в sRGB см. https://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:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

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:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

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), если display_name не задан. 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:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────────────────────┘

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 "Емкость";

┌─Ёмкость───┐
│ 39.32 ГиБ │
└───────────┘

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

Примеры

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

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

Примеры

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

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

Примеры

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)

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 Б     │
│           1024 │ 1.02 КБ    │
│        1048576 │ 1.05 МБ    │
│      192851925 │ 192.85 МБ  │
└────────────────┴────────────┘

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

Синтаксис

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

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

Синтаксис

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

Реализует логику преобразования truncate в Iceberg: https://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

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

Во всех случаях возвращает 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

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

Синтаксис

joinGet(имя_таблицы_join, столбец_значения, ключи_соединения)

Аргументы

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

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

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

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

Возвращает ключи словаря. 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
Код: 44. DB::Exception: Получено от localhost:9000. DB::Exception: Недопустимый тип аргумента #2 'pattern' функции countMatches, ожидается константа типа String, получен тип 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 - вероятность ошибки II рода). (U)Int* или Float*
• alpha — требуемый уровень значимости теста (вероятность ошибки I рода). (U)Int* или Float*

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

Возвращает именованный Tuple из трёх элементов: 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 - вероятность ошибки второго рода). Float*
• alpha — Требуемый уровень значимости теста (вероятность ошибки первого рода). 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 и не предназначена для прямого использования.

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

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

Синтаксис

Аргументы

• Нет.

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

Примеры

nested

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

Вычисляет идентификатор партиции.

Примечание

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

Синтаксис

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

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

Устарело

Состояние сбрасывается для каждого нового блока данных. Из‑за такого подверженного ошибкам поведения функция объявлена устаревшей, и вместо неё рекомендуется использовать оконные функции. Вы можете использовать настройку 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.

Устарела

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

Вы можете использовать настройку 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

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

Синтаксис

showCertificate()

Аргументы

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

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

Возвращает карту пар «ключ–значение», содержащих сведения о настроенном SSL‑сертификате. Map(String, String)

Примеры

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

SELECT showCertificate() FORMAT LineAsString;

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

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 row in set. Elapsed: 2.012 sec.

sleepEachRow

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

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

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

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

Примечание

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

Синтаксис

sleepEachRow(секунды)

Аргументы

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

Синтаксис

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, 'Too many') FROM numbers(10);

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Получено исключение от сервера (версия 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

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

Примечание

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

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

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

Синтаксис

## transactionID \{#transactionID}

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


<ExperimentalBadge/>
<CloudNotSupportedBadge/>

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

:::note
Эта функция является частью экспериментального набора возможностей.
Включите экспериментальную поддержку транзакций, добавив эту настройку в ваш [конфигурационный файл](/operations/configuration-files):

```xml
<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>
```

Дополнительную информацию см. на странице [Поддержка транзакций (ACID)](/guides/developer/transactional#transactions-commit-and-rollback).
:::
    

**Синтаксис**

```sql
transactionID()
```

**Аргументы**

- Отсутствуют.

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

Возвращает кортеж, состоящий из `start_csn`, `local_tid` и `host_id`.
- `start_csn`: Глобальный порядковый номер, самая новая временная метка фиксации, которая была видна на момент начала этой транзакции.
- `local_tid`: Локальный порядковый номер, уникальный для каждой транзакции, запущенной этим хостом в рамках конкретного start_csn.
- `host_id`: UUID хоста, запустившего эту транзакцию.
     [`Tuple(UInt64, UInt64, UUID)`](/sql-reference/data-types/tuple)

**Примеры**

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

```sql title=Запрос
BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;
```

```response title=Результат
┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘
```

Аргументы

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

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

Возвращает кортеж, состоящий из start_csn, local_tid и host_id.

• start_csn: глобальный последовательный номер, последняя метка времени фиксации, которая была видна на момент начала этой транзакции.
• 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) транзакции, доступный для чтения.

Примечание

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

<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), который виден для некоторой выполняющейся транзакции.

Примечание

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

<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 (четырёхпараметрная версия), либо исходное x (трёхпараметрная версия). Если в array_from существует несколько совпадающих элементов, возвращается элемент, соответствующий первому совпадению.

Требования:

• array_from и array_to должны иметь одинаковое количество элементов
• Для четырёхпараметрной версии: transform(T, Array(T), Array(U), U) -> U, где T и U могут быть разными совместимыми типами
• Для трёхпараметрной версии: 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

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

Синтаксис

uptime()

Аргументы

• Нет.

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

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

Примеры

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

SELECT uptime() AS 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. Если строка содержит NULL, для неё возвращается 'None'.

Синтаксис

variantType(variant)

Аргументы

• variant — столбец типа Variant. Variant

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

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

Синтаксис

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