Редактор метрик

В версии Webim 10.6 увидела свет полная поддержка работы с пользовательскими метриками. Для этих целей в Редакторе Статистики был создан новый подраздел - Редактор метрик. Доступ к нему осуществляется переходом в меню Метрики в разделе Редактор Статистики.

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

Метрики разделены на два типа:

Системные: метрики, присутствующие в системе по умолчанию. Вы не можете их создавать, изменять или удалять, но Вы можете просмотреть и скопировать такую метрику для создания собственной на её основе.
Пользовательские: метрики, созданные пользователями системы. При наличии соответствующих прав (см. материал о системе управления доступом) Вы можете создавать, изменять и удалять такие метрики. Пользовательскую метрику можно скопировать для создания новой точно так же, как и системную.

Создание метрик

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

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

Название: наименование Вашей метрики. Обязательное для заполнения поле.
Описание: описание Вашей метрики - что она подсчитывает, каким образом и т.д. Опциональное поле.
Источник данных: выпадающий список, содержащий в себе таблицы базы данных, из которых будет браться информация для подсчёта метрики. В зависимости от выбранного источника данных список доступных полей, приведённый ниже будет изменяться. Обязательное для заполнения поле.
Выражение: SQL-выражение, по которому будет выполняться подсчёт метрики. В этом поле допустимо вводить арифметические знаки (+, -, *, /), имена доступных полей из списка ниже, а также доступные агрегатные функции. Обязательное для заполнения поле.

Раскрывающийся блок Доступные поля отображает доступные для обращения поля, определённые текущим источником данных.

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

После того как Вы закончите конфигурировать метрику, нажмите на кнопку Сохранить в правом нижнем углу экрана.

Созданную Вами метрику можно использовать в Редакторе отчётов.

Прочие действия с метриками

Копирование

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

Редактирование

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

Удаление

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

Внимание!

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

Переменные

Также вы можете добавлять в метрики собственные переменные для сокращения выражения при повторяющихся расчётах или для использования в выражении параметров account config. Сделать это можно, нажав на кнопку Добавить переменную в блоке Переменные. Всего доступно два вида переменных: Скалярное значение и Опция account config.

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

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

Опция account config используется в тех случаях, когда вам необходимо получить некоторую информацию из конфигурации системы для использования её в подсчёте метрики. На данный момент по умолчанию доступна лишь одна опция: max_chats_per_operator. Она, как и следует из названия, определяет максимальное количество чатов на оператора. В случае, если Вы хотели бы видеть в своём Редакторе метрик дополнительные опции account config, обратитесь в техническую поддержку.

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

Скалярное значение: идентификатор вида P<num>, где num - порядковый номер скалярного значения относительно времени его создания для текущей метрики. Пример: P0.
Опция account config: идентификатор вида config.<parameter>, где parameter - название опции account config. Пример: config.max_chats_per_operator.

Вы можете скопировать идентификатор переменной, кликнув по нему левой кнопкой мыши.

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

Список функций, принимаемых в выражении метрики

Ниже приведён список функций, принимаемых Редактором метрик. Для получения более подробной справки Вы можете обратиться к официальной документации ClickHouse.

Агрегатные функции

`avg(column)`

Возвращает среднее значение колонки column. Применимо только к колонкам численных типов.

`count(column)`

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

`max(column)`

Возвращает максимальное значение из колонки column.

`min(column)`

Возвращает минимальное значение из колонки column.

`sum(column)`

Вычисляет сумму. Работает только для чисел.

`uniq(x1, x2, ...)`

Приближённо вычисляет количество различных значений аргумента.

Функция принимает переменное число входных параметров. Параметры могут быть числовых типов, а также Tuple, Array, Date, DateTime, String.

Функция:

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

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

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

Арифметические функции

`abs(a)`

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

`divide(a, b), оператор a / b`

Вычисляет частное чисел. Тип результата всегда является типом с плавающей запятой. То есть, деление не целочисленное. Для целочисленного деления, используйте функцию intDiv. При делении на ноль получится inf, -inf или nan.

`divideDecimal(a, b[, result_scale])`

Совершает деление двух Decimal. Результат будет иметь тип Decimal256. Размер дробной части можно явно задать аргументом result_scale (целочисленная константа из интервала [0, 76]). Если этот аргумент не задан, то scale результата будет равен наибольшему из scale обоих аргументов.

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

`gcd(a, b)`

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

`intDiv(a, b)`

Вычисляет частное чисел. Деление целочисленное, с округлением вниз (по абсолютному значению). При делении на ноль или при делении минимального отрицательного числа на минус единицу, выбрасывается исключение.

`intDivOrZero(a, b)`

Отличается от intDiv тем, что при делении на ноль или при делении минимального отрицательного числа на минус единицу, возвращается ноль.

`max2(value1, value2)`

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

`min2(value1, value2)`

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

`minus(a, b), оператор a - b`

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

Также можно вычитать целые числа из даты и даты-с-временем. Смысл аналогичен plus.

`modulo(a, b), оператор a % b`

Вычисляет остаток от деления. Тип результата - целое число, если оба аргумента - целые числа. Если один из аргументов является числом с плавающей точкой, результатом будет число с плавающей точкой. Берётся остаток в том же смысле, как это делается в C++. По факту, для отрицательных чисел, используется truncated division. При делении на ноль или при делении минимального отрицательного числа на минус единицу, выбрасывается исключение.

`moduloOrZero(a, b)`

Аналогично modulo, но возвращает ноль при делении на ноль.

`multiply(a, b), оператор a * b`

Вычисляет произведение чисел.

`multiplyDecimal(a, b[, result_scale])`

Совершает умножение двух Decimal. Результат будет иметь тип Decimal256. Размер дробной части результата можно явно задать аргументом result_scale (целочисленная константа из интервала [0, 76]). Если этот аргумент не задан, то размер дробной части результата будет равен наибольшему из размеров обоих аргументов.

`negate(a), оператор -a`

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

`plus(a, b), оператор a + b`

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

`positiveModulo(a, b)`

Аналогично modulo, но всегда возвращает положительный остаток.

Функция в 4-5 раз медленнее modulo.

Функции округления

`floor(x[, N])`

Возвращает наибольшее круглое число, которое меньше или равно, чем x. Круглым называется число, кратное 1 / 10N или ближайшее к нему число соответствующего типа данных, если 1 / 10N не представимо точно. N - целочисленная константа, не обязательный параметр. По умолчанию - ноль, что означает - округлять до целого числа. N может быть отрицательным.

Примеры: floor(123.45, 1) = 123.4, floor(123.45, -1) = 120.

x - любой числовой тип. Результат - число того же типа. Для целочисленных аргументов имеет смысл округление с отрицательным значением N (для неотрицательных N, функция ничего не делает). В случае переполнения при округлении (например, floor(-128, -1)), возвращается implementation specific результат.

`round(x[, N])`

Округляет значение до указанного десятичного разряда.

Функция возвращает ближайшее значение указанного порядка. В случае, когда заданное число равноудалено от чисел необходимого порядка, для типов с плавающей точкой (Float32/64) функция возвращает то из них, которое имеет ближайшую чётную цифру (банковское округление), для типов с фиксированной точкой (Decimal) функция использует округление в бо́льшую по модулю сторону (математическое округление).

Аргументы:

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

N — целое значение.

Если N > 0, то функция округляет значение справа от запятой.
Если N < 0 то функция округляет значение слева от запятой.
Если N = 0, то функция округляет значение до целого. В этом случае аргумент можно опустить.

`roundAge(num)`

Принимает число. Если число меньше 18 - возвращает 0. Иначе округляет число вниз до чисел из набора: 18, 25, 35, 45, 55. Эта функция специфична для Яндекс.Метрики и предназначена для реализации отчёта по возрасту посетителей.

`roundBankers(x[, N])`

Округляет число до указанного десятичного разряда.

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

Банковское округление позволяет уменьшить влияние округления чисел на результат суммирования или вычитания этих чисел.

Пример суммирования чисел 1.5, 2.5, 3.5 и 4.5 с различным округлением:

Без округления: 1.5 + 2.5 + 3.5 + 4.5 = 12.
Банковское округление: 2 + 2 + 4 + 4 = 12.
Округление до ближайшего целого: 2 + 3 + 4 + 5 = 14.

`roundDown(num, arr)`

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

`roundDuration(num)`

Принимает число. Если число меньше 1 - возвращает 0. Иначе округляет число вниз до чисел из набора: 1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000. Эта функция специфична для Яндекс.Метрики и предназначена для реализации отчёта по длительности визита.

`roundToExp2(num)`

Принимает число. Если число меньше 1 - возвращает 0. Иначе округляет число вниз до ближайшей (целой неотрицательной) степени 2.

Функции сравнения

Функции сравнения возвращают всегда 0 или 1 (UInt8).

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

числа;
строки и фиксированные строки;
даты;
даты-с-временем;

внутри каждой группы, но не из разных групп.

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

Строки сравниваются побайтово. Более короткая строка меньше всех строк, начинающихся с неё и содержащих ещё хотя бы один символ.

`equals, оператор a = b и a == b`

Сравнивает a и b между собой. Возвращает 1 в случае равенства и 0 - в случае неравенства.

`greater, оператор >`

Сравнивает a и b между собой. Возвращает 1 в случае, если a больше b и 0 - в противном случае.

`greaterOrEquals, оператор >=`

Сравнивает a и b между собой. Возвращает 1 в случае, если a больше либо равно b и 0 - в противном случае.

`less, оператор <`

Сравнивает a и b между собой. Возвращает 1 в случае, если a меньше b и 0 - в противном случае.

`greaterOrEquals, оператор <=`

Сравнивает a и b между собой. Возвращает 1 в случае, если a меньше либо равно b и 0 - в противном случае.

`notEquals, оператор a != b и a <> b`

Сравнивает a и b между собой. Возвращает 1 в случае, если a не равно b и 0 - в противном случае.

Условные функции

`greatest(x1, x2, ...)`

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

`if(cond, then, else)`

Условное выражение. В отличие от большинства систем, ClickHouse всегда считает оба выражения then и else.

Если условие cond не равно нулю, то возвращается результат выражения then. Если условие cond равно нулю или является NULL, то результат выражения then пропускается и возвращается результат выражения else.

Чтобы вычислять функцию if по короткой схеме, используйте настройку short_circuit_function_evaluation. Если настройка включена, то выражение then вычисляется только для строк, где условие cond верно, а выражение else – для строк, где условие cond неверно.

Аргументы:

cond – проверяемое условие. Может быть UInt8 или NULL.

then – возвращается результат выражения, если условие cond истинно.

else – возвращается результат выражения, если условие cond ложно.

`least(x1, x2, ...)`

Возвращает наименьшее значение из списка переданных параметров. Все параметры должны иметь совместимые типы.

`multiIf(cond_1, then_1, cond_2, then_2, ..., else)`

Позволяет более компактно записать оператор CASE в запросе.

Чтобы вычислять функцию multiIf по короткой схеме, используйте настройку short_circuit_function_evaluation. Если настройка включена, то выражение then_i вычисляется только для строк, где условие ((NOT cond_1) AND (NOT cond_2) AND ... AND (NOT cond_{i-1}) AND cond_i) верно, cond_i вычисляется только для строк, где условие((NOT cond_1) AND (NOT cond_2) AND ... AND (NOT cond_{i-1})) верно. Например, при выполнении запроса SELECT multiIf(number = 2, intDiv(1, number), number = 5) FROM numbers(10) не будет сгенерировано исключение из-за деления на ноль.

Аргументы

cond_N — условие, при выполнении которого функция вернёт then_N.

then_N — результат функции при выполнении.

else — результат функции, если ни одно из условий не выполнено.

Функция принимает 2N+1 параметров.

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

Функции преобразования типов

`accurateCast(x, T)`

Преобразует входное значение x в указанный тип данных T.

Не допускает переполнения при преобразовании числовых типов. Например, accurateCast(-1, 'UInt8') вызовет исключение.

`accurateCastOrDefault(x, T[, default_value])`

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

`accurateCastOrNull(x, T)`

Преобразует входное значение x в указанный тип данных T.

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

`CAST(x, T)`

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

Если входное значение выходит за границы нового типа, то результат переполняется. Например, CAST(-1, 'UInt8') возвращает 255.

`dateTime64ToSnowflake(value)`

Преобразует дату-время (DateTime64) из value в уникальный ID по алгоритму Snowflake.

`dateTimeToSnowflake(value)`

Преобразует дату-время (DateTime) из value в уникальный ID по алгоритму Snowflake.

`formatRow(format, x, y, ...)`

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

Аргументы:

format — текстовый формат. Например, CSV, TSV.

x,y, ... — выражения.

Возвращает отформатированную строку (в текстовых форматах обычно с завершающим переводом строки).

Примечание: если формат содержит префикс/суффикс, то он будет записан в каждой строке.

Данная функция поддерживает только строковые форматы вывода.

`formatRowNoNewline(format, x, y, ...)`

Преобразует произвольные выражения в строку заданного формата. Отличается от функции formatRow тем, что удаляет лишний перевод строки \n в конце, если он есть.

Аргументы:

format — текстовый формат. Например, CSV, TSV.

x,y, ... — выражения.

Возвращает отформатированную строку (в текстовых форматах обычно с завершающим переводом строки).

`parseDateTime(str, format[, timezone])`

Преобразует строку в DateTime в соответствии со строкой формата MySQL.

Эта функция является операцией, противоположной функции FormatDateTime.

Аргументы

str — строка, подлежащая преобразованию.

format — формат строки.

timezone — Часовой пояс. Необязательный.

Поддерживаемые спецификаторы формата

Все спецификаторы формата, перечисленные в FormatDateTime, за исключением:

%Q: Квартал (1-4)

`parseDateTimeOrNull(str, format[, timezone])`

Работает аналогично функции parseDateTime, но возвращает NULL, если формат даты не может быть обработан.

`parseDateTimeOrZero(str, format[, timezone])`

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

`parseDateTimeBestEffort(time_string[, time_zone])`

Преобразует дату и время в строковом представлении к типу данных DateTime.

Функция распознаёт форматы ISO 8601,RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, формат даты времени ClickHouse а также некоторые другие форматы.

Аргументы:

time_string — строка, содержащая дату и время для преобразования. String.

time_zone — часовой пояс. Функция анализирует time_string в соответствии с заданным часовым поясом. String.

Поддерживаемые нестандартные форматы:

Unix timestamp в строковом представлении. 9 или 10 символов.
Строка с датой и временем: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss, etc.
Строка с датой, но без времени: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY и т.д.
Строка с временем, и с днём: DD, DD hh, DD hh:mm. В этом случае MM принимается равным 01.
Строка, содержащая дату и время вместе с информацией о часовом поясе: YYYY-MM-DD hh:mm:ss ±h:mm, и т.д. Например, 2020-12-12 17:36:00 -5:00.
Строка, содержащая дату и время в формате syslog timestamp: Mmm dd hh:mm:ss. Например, Jun 9 14:20:32.

Для всех форматов с разделителями функция распознаёт названия месяцев, выраженных в виде полного англоязычного имени месяца или в виде первых трёх символов имени месяца. Примеры: 24/DEC/18, 24-Dec-18, 01-September-2018. Если год не указан, вместо него подставляется текущий год. Если в результате получается будущее время (даже на одну секунду впереди текущего момента времени), то текущий год заменяется на прошлый.

`parseDateTimeBestEffortOrNull(time_string[, time_zone])`

Работает так же как parseDateTimeBestEffort, но возвращает NULL когда получает формат даты который не может быть обработан.

`parseDateTimeBestEffortOrZero(time_string[, time_zone])`

Работает так же как parseDateTimeBestEffort, но возвращает 0 когда получает формат даты который не может быть обработан.

`parseDateTime64BestEffort(time_string [, precision [, time_zone]])`

Работает аналогично функции parseDateTimeBestEffort, но также принимает миллисекунды и микросекунды. Возвращает тип данных DateTime.

Аргументы:

time_string — строка, содержащая дату или дату со временем, которые нужно преобразовать. String.

precision — требуемая точность: 3 — для миллисекунд, 6 — для микросекунд. По умолчанию — 3. Необязательный. UInt8.

time_zone — Часовой пояс. Разбирает значение time_string в зависимости от часового пояса. Необязательный. String.

`parseDateTime64BestEffortOrNull(time_string [, precision [, time_zone]])`

Работает аналогично функции parseDateTime64BestEffort, но возвращает NULL, если формат даты не может быть обработан.

`parseDateTime64BestEffortOrZero(time_string [, precision [, time_zone]])`

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

`parseDateTime64BestEffortUS(time_string [, precision [, time_zone]])`

Работает аналогично функции parseDateTime64BestEffort, но разница состоит в том, что в она предполагает американский формат даты (MM/DD/YYYY etc.) в случае неоднозначности.

`parseDateTime64BestEffortUSOrNull(time_string [, precision [, time_zone]])`

Работает аналогично функции parseDateTime64BestEffort, но разница состоит в том, что в она предполагает американский формат даты (MM/DD/YYYY etc.) в случае неоднозначности и возвращает NULL, если формат даты не может быть обработан.

`parseDateTime64BestEffortUSOrZero(time_string [, precision [, time_zone]])`

Работает аналогично функции parseDateTime64BestEffort, но разница состоит в том, что в она предполагает американский формат даты (MM/DD/YYYY etc.) в случае неоднозначности и возвращает нулевую дату и время, если формат даты не может быть обработан.

`parseDateTimeInJodaSyntax(str, format[, timezone])`

Работает аналогично parseDateTime, за исключением того, что строка формата используется в синтаксисе Joda вместо MySQL.

Эта функция является операцией, противоположной функции formatDateTimeInJodaSyntax.

Поддерживаемые спецификаторы формата:

Поддерживаются все спецификаторы формата, перечисленные в formatDateTimeInJoda, за исключением:

S: доли секунды
z: часовой пояс
Z: смещение/идентификатор часового пояса

`parseDateTimeInJodaSyntaxOrNull(str, format[, timezone])`

Работает аналогично функции parseDateTimeInJodaSyntax, но возвращает NULL, если формат даты не может быть обработан.

`parseDateTimeInJodaSyntaxOrZero(str, format[, timezone])`

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

`reinterpret(x, T)`

Использует ту же исходную последовательность байтов в памяти для значения x и повторно интерпретирует ее в соответствии с типом назначения.

Аргументы:

x — Любой тип.

type — Тип назначения. String.

`reinterpretAsDate(s)`

Функция принимают строку s и интерпретирует байты, расположенные в начале строки, как число в host order (little endian). Если строка имеет недостаточную длину, то функция работают так, как будто строка дополнена необходимым количеством нулевых байт. Если строка длиннее, чем нужно, то лишние байты игнорируются. Дата интерпретируется, как число дней с начала unix-эпохи

`reinterpretAsDateTime(s)`

Функция принимают строку s и интерпретирует байты, расположенные в начале строки, как число в host order (little endian). Если строка имеет недостаточную длину, то функция работают так, как будто строка дополнена необходимым количеством нулевых байт. Если строка длиннее, чем нужно, то лишние байты игнорируются. дата-с-временем интерпретируется, как число секунд с начала unix-эпохи.

`reinterpretAsFixedString(value)`

Эта функция принимает число, или дату, или дату со временем и возвращает фиксированную строку, содержащую байты, представляющие соответствующее значение в порядке следования узлов (с меньшим порядком в конце). Нулевые байты удаляются с конца. Например, значение типа UInt32, равное 255, представляет собой фиксированную строку длиной в один байт.

`reinterpretAsFloat(s)`

Функция принимают строку s и интерпретирует байты, расположенные в начале строки, как Float в host order (little endian). Если строка имеет недостаточную длину, то функция работают так, как будто строка дополнена необходимым количеством нулевых байт. Если строка длиннее, чем нужно, то лишние байты игнорируются.

`reinterpretAsInt(s)`

Функция принимают строку s и интерпретирует байты, расположенные в начале строки, как Integer в host order (little endian). Если строка имеет недостаточную длину, то функция работают так, как будто строка дополнена необходимым количеством нулевых байт. Если строка длиннее, чем нужно, то лишние байты игнорируются.

`reinterpretAsString(value)`

Функция принимает число или дату или дату-с-временем и возвращает строку, содержащую байты, представляющие соответствующее значение в host order (little endian). При этом, отбрасываются нулевые байты с конца. Например, значение 255 типа UInt32 будет строкой длины 1 байт.

`reinterpretAsUInt(s)`

Функция принимают строку s и интерпретирует байты, расположенные в начале строки, как UInt в host order (little endian). Если строка имеет недостаточную длину, то функция работают так, как будто строка дополнена необходимым количеством нулевых байт. Если строка длиннее, чем нужно, то лишние байты игнорируются.

`reinterpretAsUUID(fixed_string)`

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

`second()`

То же, что и toSecond.

`snowflakeToDateTime(value [, time_zone])`

Извлекает время из Snowflake ID в формате DateTime.

Аргументы:

value — Snowflake ID. Int64.

time_zone — временная зона сервера. Функция распознает time_string в соответствии с часовым поясом. Необязательный. String.

`snowflakeToDateTime64(value [, time_zone])`

Извлекает время из Snowflake ID в формате DateTime64.

`toDate(value)`

Конвертирует аргумент в значение Date.

Аргументы:

value — Значение для преобразования. String, Int, Date или DateTime.

Если value является числом выглядит как UNIX timestamp (больше чем 65535), оно интерпретируется как DateTime, затем обрезается до Date учитывавая текущий часовой пояс. Если value является числом и меньше чем 65536, оно интерпретируется как количество дней с 1970-01-01.

`toDateOrDefault(value, [default_value])`

Как toDate, но в случае неудачи возвращает значение по умолчанию (или второй аргумент (если указан), или нижняя граница Date).

`toDateOrNull(value)`

Как toDate, но в случае неудачи возвращает NULL. Поддерживается только аргумент типа String.

`toDateOrZero(value)`

Как toDate, но в случае неудачи возвращает нижнюю границу Date. Поддерживается только аргумент типа String.

`toDate32(value)`

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

`toDate32OrDefault(value, [default_value])`

Конвертирует аргумент в значение типа Date32. Если значение выходит за границы диапазона, возвращается нижнее пограничное значение Date32. Если аргумент имеет тип Date, учитываются границы типа Date. Возвращает значение по умолчанию, если получен недопустимый аргумент.

`toDate32OrNull(value)`

То же самое, что и toDate32, но возвращает NULL, если получен недопустимый аргумент.

`toDate32OrZero(value)`

То же самое, что и toDate32, но возвращает минимальное значение типа Date32, если получен недопустимый аргумент.

`toDateTime(value, [time_zone])`

Конвертирует аргумент в значение DateTime.

Аргументы:

value — Значение для преобразования. String, Int, Date или DateTime.

time_zone — Часовой пояс. String.

Если value является числом, то оно интерпретируется как число секунд с начала Unix-эпохи (Unix Timestamp).

Если же value - строка (String), то оно может быть интерпретировано и как Unix Timestamp, и как строковое представление даты / даты со временем.

Ввиду неоднозначности запрещён парсинг строк длиной 4 и меньше. Так, строка '1999' могла бы представлять собой как год (неполное строковое представление даты или даты со временем), так и Unix Timestamp. Строки длиной 5 символов и более не несут неоднозначности, а следовательно, их парсинг разрешён.

`toDateTimeOrDefault(value, [time_zone], [default_value])`

Как toDateTime, но в случае неудачи возвращает значение по умолчанию (или третий аргумент (если указан), или нижняя граница DateTime).

`toDateTimeOrNull(value, [time_zone])`

Как toDateTime, но в случае неудачи возвращает NULL. Поддерживается только аргумент типа String.

`toDateTimeOrZero(value, [time_zone])`

Как toDateTime, но в случае неудачи возвращает нижнюю границу DateTime. Поддерживается только аргумент типа String.

`toDateTime64(value, [time_zone])`

То же самое, что и toDateTime, но возвращаемое значение имеет тип DateTime64.

`toDateTime64OrDefault(value, [time_zone], [default_value])`

То же самое, что и toDateTime64, но возвращает значение DateTime64 по умолчанию или default_value (если задано), если получен недопустимый аргумент.

`toDateTime64OrNull(value, [time_zone])`

То же самое, что и toDateTime64, но возвращает NULL, если получен недопустимый аргумент.

`toDateTime64OrZero(value, [time_zone])`

То же самое, что и toDateTime64, но возвращает минимальное значение типа DateTime64, если получен недопустимый аргумент.

`toDecimal(value, S)`

Преобразует value к типу данных Decimal с точностью S. value может быть числом или строкой. Параметр S (scale) задаёт число десятичных знаков.

Аргументы:

value — выражение, возвращающее значение типа String. ClickHouse ожидает текстовое представление десятичного числа. Например, '1.111'.

S — количество десятичных знаков в результирующем значении.

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

Значение типа Nullable(Decimal(P,S)). Значение содержит:

Число с S десятичными знаками, если ClickHouse распознал число во входной строке.
NULL, если ClickHouse не смог распознать число во входной строке или входное число содержит больше чем S десятичных знаков.

`toDecimalString(number, scale)`

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

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

Аргументы:

number — Значение любого числового типа: Int, UInt, Float, Decimal.

scale — Требуемое количество десятичных знаков после запятой, UInt8.

Значение scale для типов Decimal и Int, UInt должно не превышать 77 (так как это наибольшее количество значимых символов для этих типов).
Значение scale для типа Float не должно превышать 60.

`toFixedString(s, N)`

Преобразует аргумент типа String в тип FixedString(N) (строку фиксированной длины N). N должно быть константой. Если строка имеет меньше байт, чем N, то она дополняется нулевыми байтами справа. Если строка имеет больше байт, чем N - выбрасывается исключение.

`toFloat(value)`

Преобраует входное значение к типу Float.

Аргументы:

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

Функции используют округление к нулю, т.е. обрезают дробную часть числа.

Поведение функции для аргументов NaN и Inf не определено. Если передать строку, содержащую отрицательное число, например '-32', ClickHouse генерирует исключение. При использовании функции помните о возможных проблемах при преобразовании чисел.

`toInt(value)`

Преобразует входное значение к типу Int.

Аргументы:

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

Функции используют округление к нулю, т.е. обрезают дробную часть числа.

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

`toInterval(number)`

Приводит аргумент из числового типа данных к типу данных IntervalType.

Аргументы:

number — длительность интервала. Положительное целое число.

`toLowCardinality(value)`

Преобразует входные данные в версию LowCardinality того же типа данных.

Чтобы преобразовать данные из типа LowCardinality, используйте функцию CAST. Например,CAST(x as String).

`toString(value)`

Функции преобразования между числами, строками (но не фиксированными строками), датами и датами-с-временем. Все эти функции принимают один аргумент.

При преобразовании в строку или из строки, производится форматирование или парсинг значения по тем же правилам, что и для формата TabSeparated (и почти всех остальных текстовых форматов). Если распарсить строку не удаётся - выбрасывается исключение и выполнение запроса прерывается.

При преобразовании даты в число или наоборот, дате соответствует число дней от начала unix эпохи. При преобразовании даты-с-временем в число или наоборот, дате-с-временем соответствует число секунд от начала unix эпохи.

Форматы даты и даты-с-временем для функций toDate/toDateTime определены следующим образом:

YYYY-MM-DD
YYYY-MM-DD hh:mm:ss

В качестве исключения, если делается преобразование из числа типа UInt32, Int32, UInt64, Int64 в Date, и если число больше или равно 65536, то число рассматривается как unix timestamp (а не как число дней) и округляется до даты. Это позволяет поддержать распространённый случай, когда пишут toDate(unix_timestamp), что иначе было бы ошибкой и требовало бы написания более громоздкого toDate(toDateTime(unix_timestamp)).

Преобразование между датой и датой-с-временем производится естественным образом: добавлением нулевого времени или отбрасыванием времени.

Преобразование между числовыми типами производится по тем же правилам, что и присваивание между разными числовыми типами в C++.

Дополнительно, функция toString от аргумента типа DateTime может принимать второй аргумент String - имя тайм-зоны. Пример: Asia/Yekaterinburg В этом случае, форматирование времени производится согласно указанной тайм-зоне.

`toStringCutToZero(s)`

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

`toUInt(value)`

Преобраует входное значение к типу UInt.

Аргументы:

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

Функция использует округление к нулю, т.е. обрезает дробную часть числа.

Поведение функции для аргументов NaN и Inf не определено. Если передать строку, содержащую отрицательное число, например '-32', ClickHouse генерирует исключение. При использовании функции помните о возможных проблемах при преобразовании чисел.

`toUnixTimestamp64Micro(value)`

Преобразует значение DateTime64 в значение Int64 с фиксированной точностью менее одной секунды. Входное значение округляется соответствующим образом вверх или вниз в зависимости от его точности.

Возвращаемое значение — это временная метка в UTC, а не в часовом поясе DateTime64.

`toUnixTimestamp64Milli(value)`

Преобразует значение DateTime64 в значение Int64 с фиксированной точностью менее одной секунды. Входное значение округляется соответствующим образом вверх или вниз в зависимости от его точности.

Возвращаемое значение — это временная метка в UTC, а не в часовом поясе DateTime64.

`toUnixTimestamp64Nano(value)`

Преобразует значение DateTime64 в значение Int64 с фиксированной точностью менее одной секунды. Входное значение округляется соответствующим образом вверх или вниз в зависимости от его точности.

Возвращаемое значение — это временная метка в UTC, а не в часовом поясе DateTime64.

Функции для работы с Nullable-аргументами

`assumeNotNull(x)`

Приводит значение типа Nullable к не Nullable, если значение не NULL.

`coalesce(x, ...)`

Последовательно слева-направо проверяет являются ли переданные аргументы NULL и возвращает первый не NULL.

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

Если все аргументы NULL, функция возвращает NULL.

`ifNull(x,alt)`

Возвращает альтернативное alt значение, если основной аргумент x — NULL.

Аргументы:

x — значение для проверки на NULL.

alt — значение, которое функция вернёт, если x — NULL.

`isNotNull(x)`

Проверяет не является ли аргумент NULL. Возвращает 1, если аргумент не является NULL, возвращает 0 в противном случае.

Аргументы:

x — значение с не составным типом данных.

`isNull(x)`

Проверяет является ли аргумент NULL. Возвращает 1, если аргумент является NULL, возвращает 0 в противном случае.

Аргументы:

x — значение с не составным типом данных.

`isZeroOrNull(x)`

Проверяет, равен ли аргумент 0 или NULL. Возвращает 1, если аргумент является 0 или NULL, возвращает 0 в противном случае.

Аргументы:

x — значение с не составным типом данных.

`nullIf(x, y)`

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

Аргументы:

x, y — значения для сравнивания. Они должны быть совместимых типов, иначе ClickHouse сгенерирует исключение.

`toNullable(x)`

Преобразует тип аргумента к Nullable.

Аргументы:

x — значение произвольного не составного типа.