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

hostName

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

Синтаксис

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

• Имя хоста. String.

getMacro

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

Синтаксис

Аргументы

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

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

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

Пример

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

Запрос:

Результат:

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

fqdn

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

Синтаксис

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

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

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

Пример

Результат:

basename

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

Аргументы

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

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

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

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

Пример

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

visibleWidth

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

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

Синтаксис

Пример

Запрос:

Результат:

toTypeName

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

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

blockSize

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

Синтаксис

Пример

Запрос:

Результат:

byteSize

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

Синтаксис

Аргументы

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

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

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

Примеры

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

Запрос:

Результат:

Запрос:

Результат:

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

Запрос:

Результат:

materialize

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

Синтаксис

Параметры

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

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

• Колонка, содержащая единственное значение 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, где необходимо указать базу данных.

Синтаксис

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

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

Пример

Запрос:

Результат:

currentUser

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

Синтаксис

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

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

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

Пример

Результат:

currentSchemas

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

Синтаксис

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

Аргументы

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

примечание

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

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

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

Пример

Результат:

isConstant

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

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

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

Синтаксис

Аргументы

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

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

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

Примеры

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

hasColumnInTable

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

Синтаксис

Параметры

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

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

• 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 или десятичной единицы байта (String).

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

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

Пример

parseReadableSizeOrNull

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

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

Синтаксис

Аргументы

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

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

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

Пример

parseReadableSizeOrZero

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

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

Синтаксис

Аргументы

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

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

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

version

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

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

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

Синтаксис

Аргументы

Нет.

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

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

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

Нет.

Пример

Запрос:

Результат:

buildId

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

Синтаксис

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

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

подсказка

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

Синтаксис

Аргументы

• 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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

initializeAggregation

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

Синтаксис

Аргументы

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

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

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

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

Пример

Запрос:

Результат:

Запрос:

Результат:

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

См. также

• arrayReduce

finalizeAggregation

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

Синтаксис

Аргументы

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

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

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

примечание

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

Примеры

Запрос:

Результат:

Запрос:

Результат:

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

Запрос:

Результат:

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

Запрос:

Результат:

См. также

• arrayReduce
• initializeAggregation

runningAccumulate

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

примечание

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

Синтаксис

Аргументы

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

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

Запрос:

Результат:

Как вы видите, 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 — Значение, которое нужно вернуть, если custom_setting не установлена. Значение может быть любого типа данных или Null.

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

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

Пример

Результат:

См. также

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

isDecimalOverflow

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

Синтаксис

Аргументы

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

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

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

Пример

Запрос:

Результат:

countDigits

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

Синтаксис

Аргументы

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

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

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

примечание

Для значений Decimal учитывает их масштабы: рассчитывает результат для базового целочисленного типа (значение * масштаб). Например: 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

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

initialQueryID

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

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

Пример

Запрос:

getClientHTTPHeader

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

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

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

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

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

showCertificate

Показывает информацию о текущем сертификате Secure Sockets Layer (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

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

примечание

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

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

Синтаксис

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

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

Пример

Запрос:

Результат:

transactionOldestSnapshot

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

примечание

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

Для получения дополнительной информации см. на странице Поддержка транзакций (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.

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

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

Пример

Запрос:

Результат:

getServerSetting

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

Синтаксис

Параметр

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

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

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

Пример

Результат:

getMergeTreeSetting

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

Синтаксис

Параметр

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

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

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

Пример

Результат: