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

hostName

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

Синтаксис

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

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

getMacro

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

Синтаксис

Аргументы

• name — Имя макроса для извлечения из секции <macros>. Строка.

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

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

Пример

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

Запрос:

Результат:

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

fqdn

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

Синтаксис

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

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

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

Пример

Результат:

basename

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

Аргументы

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

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

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

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

Пример

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

visibleWidth

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

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

Синтаксис

Пример

Запрос:

Результат:

toTypeName

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

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

blockSize

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

Синтаксис

Пример

Запрос:

Результат:

byteSize

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

Синтаксис

Аргументы

• argument — Значение.

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

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

Примеры

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

Запрос:

Результат:

Запрос:

Результат:

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

Запрос:

Результат:

materialize

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

Синтаксис

Параметры

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

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

• Столбец, содержащий единственное значение x.

Пример

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

Запрос:

Результат:

ignore

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

sleep

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

Синтаксис

Аргументы

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

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

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

Пример

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

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

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

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

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

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

sleepEachRow

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

Синтаксис

Аргументы

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

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

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

Пример

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

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

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

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

currentDatabase

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

Синтаксис

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

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

Пример

Запрос:

Результат:

currentUser

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

Синтаксис

Псевдонимы: user(), USER(), current_user(). Псевдонимы регистронезависимы.

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

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

Пример

Результат:

currentSchemas

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

Синтаксис

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

Аргументы

• bool: Булевое значение. Bool.

примечание

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

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

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

Пример

Результат:

isConstant

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

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

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

Синтаксис

Аргументы

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

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

• 1, если x является постоянным. UInt8.
• 0, если x является не постоянным. UInt8.

Примеры

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

hasColumnInTable

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

Синтаксис

Параметры

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

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

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

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

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

Пример

Запрос:

hasThreadFuzzer

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

Синтаксис

bar

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

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

Аргументы

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

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

Пример:

transform

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

transform(x, array_from, array_to, default)

x – Что преобразовать.

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

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

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

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

Подпись:

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

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

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

Пример:

transform(x, array_from, array_to)

Похоже на другую вариацию, но не имеет аргумента 'default'. Если совпадение не может быть найдено, возвращает x.

Пример:

formatReadableDecimalSize

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

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

Синтаксис

Пример

Запрос:

Результат:

formatReadableSize

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

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

Синтаксис

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

примечание

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

Пример

Запрос:

Результат:

formatReadableQuantity

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

Синтаксис

примечание

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

Пример

Запрос:

Результат:

formatReadableTimeDelta

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

Синтаксис

примечание

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

Аргументы

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

Пример

parseReadableSize

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

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

Синтаксис

Аргументы

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

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

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

Пример

parseReadableSizeOrNull

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

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

Синтаксис

Аргументы

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

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

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

Пример

parseReadableSizeOrZero

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

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

Синтаксис

Аргументы

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

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

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

Пример

parseTimeDelta

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

Синтаксис

Аргументы

• timestr — Последовательность чисел, за которыми следует нечто похожее на единицу времени.

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

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

Пример

least

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

Синтаксис

примечание

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

greatest

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

Синтаксис

примечание

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

uptime

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

Синтаксис

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

• Временное значение в секундах. UInt32.

Пример

Запрос:

Результат:

version

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

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

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

Синтаксис

Аргументы

Нет.

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

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

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

Нет.

Пример

Запрос:

Результат:

buildId

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

Синтаксис

blockNumber

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

Синтаксис

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

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

Пример

Запрос:

Результат:

rowNumberInBlock

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

Синтаксис

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

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

Пример

Запрос:

Результат:

rowNumberInAllBlocks

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

Синтаксис

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

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

Пример

Запрос:

Результат:

normalizeQuery

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

normalizeQueryKeepNames

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

normalizedQueryHash

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

normalizedQueryHashKeepNames

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

Синтаксис

Аргументы

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

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

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

Пример

Результат:

neighbor

Deprecated feature

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

Синтаксис

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

примечание

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

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

Аргументы

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

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

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

примечание

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

Пример

Запрос:

Результат:

Запрос:

Результат:

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

Запрос:

Результат:

runningDifference

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

примечание

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

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

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

Синтаксис

Пример

Запрос:

Результат:

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

Запрос:

Результат:

Запрос:

Результат:

runningDifferenceStartingWithFirstValue

примечание

Эта функция СТАРАЯ (см. заметку для runningDifference).

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

runningConcurrency

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

подсказка

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

Синтаксис

Аргументы

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

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

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

Пример

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

Запрос:

Результат:

MACNumToString

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

Синтаксис

MACStringToNum

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

Синтаксис

MACStringToOUI

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

Синтаксис

getSizeOfEnumType

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

Синтаксис

Аргументы:

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

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

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

Пример

blockSerializedSize

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

Аргументы

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

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

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

Пример

Запрос:

Результат:

toColumnTypeName

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

Синтаксис

Аргументы:

• value — Любой тип значения.

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

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

Пример

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

Результат:

Запрос:

Результат:

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

dumpColumnStructure

Выводит подробное описание структур данных в ОЗУ.

Аргументы:

• value — Любой тип значения.

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

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

Пример

defaultValueOfArgumentType

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

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

Синтаксис

Аргументы:

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

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

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

Пример

Запрос:

Результат:

Запрос:

Результат:

defaultValueOfTypeName

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

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

Аргументы:

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

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

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

Пример

Запрос:

Результат:

Запрос:

Результат:

indexHint

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

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

Синтаксис

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

• 1. Uint8.

Пример

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

Таблица:

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

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

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

Результат:

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

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

Результат:

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

Запрос:

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

Результат:

replicate

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

примечание

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

revision

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

Синтаксис

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

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

Пример

Запрос:

Результат:

filesystemAvailable

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

Синтаксис

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

• Количество оставшегося свободного места в байтах. UInt64.

Пример

Запрос:

Результат:

filesystemUnreserved

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

Синтаксис

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

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

Пример

Запрос:

Результат:

filesystemCapacity

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

Синтаксис

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

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

Пример

Запрос:

Результат:

initializeAggregation

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

Синтаксис

Аргументы

• aggregate_function — Имя агрегатной функции, которую нужно инициализировать. String.
• arg — Аргументы агрегатной функции.

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

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

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

Пример

Запрос:

Результат:

Запрос:

Результат:

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

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

• arrayReduce

finalizeAggregation

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

Синтаксис

Аргументы

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

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

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

примечание

Тип возвращаемого значения равен типам всех агрегированных значений.

Примеры

Запрос:

Результат:

Запрос:

Результат:

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

Запрос:

Результат:

Объединенный пример:

Запрос:

Результат:

См. также

• arrayReduce
• initializeAggregation

runningAccumulate

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

примечание

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

Синтаксис

Аргументы

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

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

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

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

Примеры

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

Запрос:

Результат:

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

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

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

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

Запрос:

Результат:

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

joinGet

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

примечание

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

Синтаксис

Аргументы

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

примечание

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

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

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

примечание

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

Пример

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

Запрос:

Результат:

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

Запрос:

Результат:

joinGetOrNull

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

Синтаксис

Аргументы

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

примечание

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

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

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

примечание

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

Пример

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

Запрос:

Результат:

catboostEvaluate

Not supported in ClickHouse Cloud

примечание

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

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

Синтаксис

Пример

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

1. Сборка библиотеки оценки catboost

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

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

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

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

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

throwIf

Генерирует исключение, если аргумент x является истинным.

Синтаксис

Аргументы

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

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

Пример

Результат:

identity

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

Синтаксис

Пример

Запрос:

Результат:

getSetting

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

Синтаксис

Параметр

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

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

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

Пример

Результат:

См. также

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

getSettingOrDefault

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

Синтаксис

Параметр

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

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

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

Пример

Результат:

См. также

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

isDecimalOverflow

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

Синтаксис

Аргументы

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

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

• 1 — Значение Decimal имеет больше разрядов, чем допускает его точность,
• 0 — Значение Decimal удовлетворяет заданной точности.

Пример

Запрос:

Результат:

countDigits

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

Синтаксис

Аргументы

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

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

• Количество разрядов. UInt8.

примечание

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

Пример

Запрос:

Результат:

errorCodeToName

• Текстовое имя кода ошибки. LowCardinality(String).

Синтаксис

Результат:

tcpPort

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

Синтаксис

Аргументы

• Нет.

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

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

Пример

Запрос:

Результат:

См. также

• tcp_port

currentProfiles

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

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

Синтаксис

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

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

enabledProfiles

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

Синтаксис

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

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

defaultProfiles

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

Синтаксис

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

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

currentRoles

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

Синтаксис

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

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

enabledRoles

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

Синтаксис

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

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

defaultRoles

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

Синтаксис

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

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

getServerPort

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

Синтаксис

Аргументы

• port_name — Название порта сервера. Строка. Возможные значения:

  • 'tcp_port'
  • 'tcp_port_secure'
  • 'http_port'
  • 'https_port'
  • 'interserver_http_port'
  • 'interserver_https_port'
  • 'mysql_port'
  • 'postgresql_port'
  • 'grpc_port'
  • 'prometheus.port'

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

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

Пример

Запрос:

Результат:

queryID

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

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

Синтаксис

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

• Идентификатор текущего запроса. Строка

Пример

Запрос:

Результат:

initialQueryID

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

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

Синтаксис

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

• Идентификатор начального текущего запроса. Строка

Пример

Запрос:

Результат:

initialQueryStartTime

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

partitionID

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

примечание

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

shardNum

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

Синтаксис

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

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

Пример

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

Запрос:

Результат:

См. также

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

shardCount

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

Синтаксис

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

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

См. также

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

getOSKernelVersion

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

Синтаксис

Аргументы

• Нет.

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

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

Пример

Запрос:

Результат:

zookeeperSessionUptime

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

Синтаксис

Аргументы

• Нет.

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

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

Пример

Запрос:

Результат:

generateRandomStructure

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

Синтаксис

Аргументы

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

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

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

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

Примеры

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

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

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

structureToCapnProtoSchema

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

Синтаксис

Аргументы

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

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

• Схема CapnProto. String.

Примеры

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

structureToProtobufSchema

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

Синтаксис

Аргументы

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

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

• Схема Protobuf. String.

Примеры

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

formatQuery

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

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

Синтаксис

Аргументы

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

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

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

Пример

Результат:

formatQuerySingleLine

Как formatQuery(), но возвращает форматированную строку без переносов строк.

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

Синтаксис

Аргументы

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

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

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

Пример

Результат:

variantElement

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

Синтаксис

Аргументы

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

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

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

Пример

variantType

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

Синтаксис

Аргументы

• variant — Столбец Variant. Variant.

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

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

Пример

minSampleSizeConversion

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

Синтаксис

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

Аргументы

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

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

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

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

Пример

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

Результат:

minSampleSizeContinuous

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

Синтаксис

Псевдоним: minSampleSizeContinous

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

Аргументы

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

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

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

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

Пример

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

Результат:

connectionId

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

Синтаксис

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

Параметры

Нет.

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

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

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

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

Пример

Запрос:

getClientHTTPHeader

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

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

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

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

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

showCertificate

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

Синтаксис

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

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

Пример

Запрос:

Результат:

lowCardinalityIndices

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

lowCardinalityKeys

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

displayName

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

Синтаксис

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

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

Пример

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

Запрос:

Результат:

transactionID

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

примечание

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

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

Синтаксис

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

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

• start_csn: Глобальный последовательный номер, самая свежая метка времени коммита, которая была получена, когда эта транзакция начиналась. UInt64.

• local_tid: Локальный последовательный номер, уникальный для каждой транзакции, начатой этим хостом в пределах специфического start_csn. UInt64.

• host_id: UUID хоста, который начал эту транзакцию. UUID.

Пример

Запрос:

Результат:

transactionLatestSnapshot

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

примечание

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

transactionOldestSnapshot

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

примечание

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

getSubcolumn

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

getTypeSerializationStreams

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

примечание

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

Синтаксис

Аргументы

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

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

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

Примеры

Запрос:

Результат:

Запрос:

Результат:

globalVariable

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

getMaxTableNameLengthForDatabase

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат: