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

В RQL поведение функций to<type> и cast в некоторых случаях различается, например, при работе с LowCardinality: функция cast убирает признак LowCardinality, в то время как функции to<type> его не убирают. То же самое касается Nullable. Такое поведение не соответствует стандарту SQL, но его можно изменить с помощью настройки cast_keep_nullable.

Возможна потеря данных при конвертации значений из типа данных в меньший тип данных (например, с Int64 на Int32) или между несовместимыми типами данных (например, с String на Int). Убедитесь, что результат конвертации соответствует ожиданиям.

Функции преобразования типов в RQL позволяют преобразовывать значения из одного типа данных в другой.

Набор поддерживаемых функций RQL и их поведение зависят от версии установленного ClickHouse. Если функция не поддерживается в используемой версии ClickHouse, она также не будет доступна в RQL. Ознакомиться с актуальным списком функций и их поведением можно в официальном репозитории ClickHouse, выбрав нужную версию из веток. Например: список функций преобразования типов для ClickHouse 24.7.

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

Таблица 1. Функции преобразования в заданные типы
Функция	Описание
`reinterpretAs<Type>`	Преобразует значение в заданный тип без изменения битового представления значения.
`CAST(x, T)`	Явное преобразование значения `x` в тип `T`.
`accurateCast(x, T)`	Преобразует значение `x` в тип `T` с проверкой на переполнение и потерю данных.
`accurateCastOrNull(x, T)`	Преобразует значение `x` в тип `T` с проверкой на переполнение и потерю данных, возвращая NULL при неудаче.
`accurateCastOrDefault(x, T, default_value)`	Преобразует значение `x` в тип `T` с проверкой на переполнение и потерю данных, возвращая значение по умолчанию при неудаче.

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

Имена функций, преобразующих значения в численные типы, имеют следующую структуру:

to<Type><Precision>[<ErrorHandling>]

Здесь:

<Type> — численный тип;
<Precision> — битность или точность числа;
<ErrorHandling> — результат, возвращаемый при неудаче. Если поведение не указано, генерируется исключение.

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

Таблица 2. Функции преобразования в целочисленные типы
Функция	Описание
`toInt8`	Преобразует значение в тип Int8. В случае неудачи генерируется исключение.
`toInt8OrZero`	Преобразует значение в тип Int8. В случае неудачи возвращает 0.
`toInt8OrNull`	Преобразует значение в тип Int8. В случае неудачи возвращает NULL.
`toInt8OrDefault`	Преобразует значение в тип Int8. В случае неудачи возвращает значение по умолчанию.
`toInt16`	Преобразует значение в тип Int16. В случае неудачи генерируется исключение.
`toInt16OrZero`	Преобразует значение в тип Int16. В случае неудачи возвращает 0.
`toInt16OrNull`	Преобразует значение в тип Int16. В случае неудачи возвращает NULL.
`toInt16OrDefault`	Преобразует значение в тип Int16. В случае неудачи возвращает значение по умолчанию.
`toInt32`	Преобразует значение в тип Int32. В случае неудачи генерируется исключение.
`toInt32OrZero`	Преобразует значение в тип Int32. В случае неудачи возвращает 0.
`toInt32OrNull`	Преобразует значение в тип Int32. В случае неудачи возвращает NULL.
`toInt32OrDefault`	Преобразует значение в тип Int32. В случае неудачи возвращает значение по умолчанию.
`toInt64`	Преобразует значение в тип Int64. В случае неудачи генерируется исключение.
`toInt64OrZero`	Преобразует значение в тип Int64. В случае неудачи возвращает 0.
`toInt64OrNull`	Преобразует значение в тип Int64. В случае неудачи возвращает NULL.
`toInt64OrDefault`	Преобразует значение в тип Int64. В случае неудачи возвращает значение по умолчанию.
`toInt128`	Преобразует значение в тип Int128. В случае неудачи генерируется исключение.
`toInt128OrZero`	Преобразует значение в тип Int128. В случае неудачи возвращает 0.
`toInt128OrNull`	Преобразует значение в тип Int128. В случае неудачи возвращает NULL.
`toInt128OrDefault`	Преобразует значение в тип Int128. В случае неудачи возвращает значение по умолчанию.
`toInt256`	Преобразует значение в тип Int256. В случае неудачи генерируется исключение.
`toInt256OrZero`	Преобразует значение в тип Int256. В случае неудачи возвращает 0.
`toInt256OrNull`	Преобразует значение в тип Int256. В случае неудачи возвращает NULL.
`toInt256OrDefault`	Преобразует значение в тип Int256. В случае неудачи возвращает значение по умолчанию.

Таблица 3. Функции преобразования в беззнаковые целочисленные типы
Функция	Описание
`toUInt8`	Преобразует значение в тип UInt8. В случае неудачи генерируется исключение.
`toUInt8OrZero`	Преобразует значение в тип UInt8. В случае неудачи возвращает 0.
`toUInt8OrNull`	Преобразует значение в тип UInt8. В случае неудачи возвращает NULL.
`toUInt8OrDefault`	Преобразует значение в тип UInt8. В случае неудачи возвращает значение по умолчанию.
`toUInt16`	Преобразует значение в тип UInt16. В случае неудачи генерируется исключение.
`toUInt16OrZero`	Преобразует значение в тип UInt16. В случае неудачи возвращает 0.
`toUInt16OrNull`	Преобразует значение в тип UInt16. В случае неудачи возвращает NULL.
`toUInt16OrDefault`	Преобразует значение в тип UInt16. В случае неудачи возвращает значение по умолчанию.
`toUInt32`	Преобразует значение в тип UInt32. В случае неудачи генерируется исключение.
`toUInt32OrZero`	Преобразует значение в тип UInt32. В случае неудачи возвращает 0.
`toUInt32OrNull`	Преобразует значение в тип UInt32. В случае неудачи возвращает NULL.
`toUInt32OrDefault`	Преобразует значение в тип UInt32. В случае неудачи возвращает значение по умолчанию.
`toUInt64`	Преобразует значение в тип UInt64. В случае неудачи генерируется исключение.
`toUInt64OrZero`	Преобразует значение в тип UInt64. В случае неудачи возвращает 0.
`toUInt64OrNull`	Преобразует значение в тип UInt64. В случае неудачи возвращает NULL.
`toUInt64OrDefault`	Преобразует значение в тип UInt64. В случае неудачи возвращает значение по умолчанию.
`toUInt128`	Преобразует значение в тип UInt128. В случае неудачи генерируется исключение.
`toUInt128OrZero`	Преобразует значение в тип UInt128. В случае неудачи возвращает 0.
`toUInt128OrNull`	Преобразует значение в тип UInt128. В случае неудачи возвращает NULL.
`toUInt128OrDefault`	Преобразует значение в тип UInt128. В случае неудачи возвращает значение по умолчанию.
`toUInt256`	Преобразует значение в тип UInt256. В случае неудачи генерируется исключение.
`toUInt256OrZero`	Преобразует значение в тип UInt256. В случае неудачи возвращает 0.
`toUInt256OrNull`	Преобразует значение в тип UInt256. В случае неудачи возвращает NULL.
`toUInt256OrDefault`	Преобразует значение в тип UInt256. В случае неудачи возвращает значение по умолчанию.

Таблица 4. Функции преобразования в типы с плавающей запятой
Функция	Описание
`toFloat32`	Преобразует значение в тип Float32. В случае неудачи генерируется исключение.
`toFloat32OrZero`	Преобразует значение в тип Float32. В случае неудачи возвращает 0.
`toFloat32OrNull`	Преобразует значение в тип Float32. В случае неудачи возвращает NULL.
`toFloat32OrDefault`	Преобразует значение в тип Float32. В случае неудачи возвращает значение по умолчанию.
`toFloat64`	Преобразует значение в тип Float64. В случае неудачи генерируется исключение.
`toFloat64OrZero`	Преобразует значение в тип Float64. В случае неудачи возвращает 0.
`toFloat64OrNull`	Преобразует значение в тип Float64. В случае неудачи возвращает NULL.
`toFloat64OrDefault`	Преобразует значение в тип Float64. В случае неудачи возвращает значение по умолчанию.

Таблица 5. Функции преобразования в десятичные типы
toDecimal32	Преобразует значение в тип Decimal32. В случае неудачи генерируется исключение.
`toDecimal32OrZero`	Преобразует значение в тип Decimal32. В случае неудачи возвращает 0.
`toDecimal32OrNull`	Преобразует значение в тип Decimal32. В случае неудачи возвращает NULL.
`toDecimal32OrDefault`	Преобразует значение в тип Decimal32. В случае неудачи возвращает значение по умолчанию.
`toDecimal64`	Преобразует значение в тип Decimal64. В случае неудачи генерируется исключение.
`toDecimal64OrZero`	Преобразует значение в тип Decimal64. В случае неудачи возвращает 0.
`toDecimal64OrNull`	Преобразует значение в тип Decimal64. В случае неудачи возвращает NULL.
`toDecimal64OrDefault`	Преобразует значение в тип Decimal64. В случае неудачи возвращает значение по умолчанию.
`toDecimal128`	Преобразует значение в тип Decimal128. В случае неудачи генерируется исключение.
`toDecimal128OrZero`	Преобразует значение в тип Decimal128. В случае неудачи возвращает 0.
`toDecimal128OrNull`	Преобразует значение в тип Decimal128. В случае неудачи возвращает NULL.
`toDecimal128OrDefault`	Преобразует значение в тип Decimal128. В случае неудачи возвращает значение по умолчанию.
`toDecimal256`	Преобразует значение в тип Decimal256. В случае неудачи генерируется исключение.
`toDecimal256OrZero`	Преобразует значение в тип Decimal256. В случае неудачи возвращает 0.
`toDecimal256OrNull`	Преобразует значение в тип Decimal256. В случае неудачи возвращает NULL.
`toDecimal256OrDefault`	Преобразует значение в тип Decimal256. В случае неудачи возвращает значение по умолчанию.

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

Таблица 6. Функции преобразования типов даты и времени
Функция	Описание
`toDate`	Преобразует значение в тип даты. В случае неудачи генерируется исключение.
`toDateOrZero`	Преобразует значение в тип даты. В случае неудачи возвращает '0000-00-00'.
`toDateOrNull`	Преобразует значение в тип даты. В случае неудачи возвращает NULL.
`toDateOrDefault`	Преобразует значение в тип даты. В случае неудачи возвращает значение по умолчанию.
`toDateTime`	Преобразует значение в тип даты со временем. В случае неудачи генерируется исключение.
`toDateTimeOrZero`	Преобразует значение в тип даты со временем. В случае неудачи возвращает '0000-00-00 00:00:00'.
`toDateTimeOrNull`	Преобразует значение в тип даты со временем. В случае неудачи возвращает NULL.
`toDateTimeOrDefault`	Преобразует значение в тип даты со временем. В случае неудачи возвращает значение по умолчанию.
`toDate32`	Преобразует значение в тип даты с расширенным диапазоном. В случае неудачи генерируется исключение.
`toDate32OrZero`	Преобразует значение в тип даты с расширенным диапазоном. В случае неудачи возвращает минимально возможную дату.
`toDate32OrNull`	Преобразует значение в тип даты с расширенным диапазоном. В случае неудачи возвращает NULL.
`toDate32OrDefault`	Преобразует значение в тип даты с расширенным диапазоном. В случае неудачи возвращает значение по умолчанию.
`toDateTime64`	Преобразует значение в тип даты со временем с высокой точностью. В случае неудачи генерируется исключение.
`toDateTime64OrZero`	Преобразует значение в тип даты со временем с высокой точностью. В случае неудачи возвращает '0000-00-00 00:00:00.000'.
`toDateTime64OrNull`	Преобразует значение в тип даты со временем с высокой точностью. В случае неудачи возвращает NULL.
`toDateTime64OrDefault`	Преобразует значение в тип даты со временем с высокой точностью. В случае неудачи возвращает значение по умолчанию.
`parseDateTimeBestEffort`	Пытается преобразовать строку в тип `DateTime`, распознавая множество форматов даты и времени, включая ISO 8601, RFC 1123, формат даты и времени ClickHouse, а также другие форматы. Поддерживает разбор строковых представлений Unix timestamp, различные строковые форматы даты и времени, а также строковые представления с указанием часового пояса.
`parseDateTime32BestEffort`	Аналогично `parseDateTimeBestEffort`, но преобразует строку в тип `DateTime32`.
`parseDateTimeBestEffortUS`	Ведет себя как `parseDateTimeBestEffort` для стандартных форматов даты, но также предпочитает американский формат даты (MM/DD/YYYY и подобные) в случае неоднозначности. Если месяц и день не могут быть однозначно идентифицированы, функция возвращается к поведению `parseDateTimeBestEffort`.
`parseDateTimeBestEffortOrNull`	Работает так же, как `parseDateTimeBestEffort`, но возвращает `NULL`, если строка не может быть преобразована в дату и время.
`parseDateTime32BestEffortOrNull`	Аналогично `parseDateTimeBestEffortOrNull`, но преобразует строку в тип `DateTime32`, возвращая `NULL` при неудаче.
`parseDateTimeBestEffortOrZero`	Работает так же, как `parseDateTimeBestEffort`, но возвращает нулевую дату и время (`1970-01-01 00:00:00`), если строка не может быть преобразована.
`parseDateTime32BestEffortOrZero`	Аналогично `parseDateTimeBestEffortOrZero`, но преобразует строку в тип `DateTime32`, возвращая нулевую дату и время при неудаче.
`parseDateTimeBestEffortUSOrNull`	Работает так же, как `parseDateTimeBestEffortUS`, но возвращает `NULL`, если строка не может быть преобразована в дату и время.
`parseDateTimeBestEffortUSOrZero`	Работает так же, как `parseDateTimeBestEffortUS`, но возвращает нулевую дату и время (`1970-01-01 00:00:00`), если строка не может быть преобразована.
`parseDateTime64BestEffort`	Работает так же, как `parseDateTimeBestEffort`, но также принимает миллисекунды и микросекунды, возвращая тип данных `DateTime64` с заданной точностью.
`parseDateTime64BestEffortUS`	Работает аналогично `parseDateTime64BestEffort`, но предполагает американский формат даты (MM/DD/YYYY и подобные) в случае неоднозначности.
`parseDateTime64BestEffortOrNull`	Работает так же, как `parseDateTime64BestEffort`, но возвращает `NULL`, если формат даты не может быть обработан.
`parseDateTime64BestEffortOrZero`	Работает так же, как `parseDateTime64BestEffort`, но возвращает нулевую дату и время (`1970-01-01 00:00:00.000`), если формат даты не может быть обработан.
`parseDateTime64BestEffortUSOrNull`	Работает аналогично `parseDateTime64BestEffortUS`, но возвращает `NULL`, если входная строка не может быть преобразована в тип данных `DateTime64`.
`parseDateTime64BestEffortUSOrZero`	Работает аналогично `parseDateTime64BestEffortUS`, но возвращает нулевую дату и время (`1970-01-01 00:00:00.000`), если входная строка не может быть преобразована.
`toLowCardinality(expr)`	Преобразует входные данные в версию `LowCardinality` того же типа данных, оптимизируя обработку и хранение данных за счет снижения количества уникальных значений.
`toUnixTimestamp64Milli(value)`	Преобразует значение `DateTime64` в значение `Int64`, представляющее количество миллисекунд с начала эпохи Unix (1970-01-01 00:00:00 UTC). Входное значение округляется соответствующим образом.
`toUnixTimestamp64Micro(value)`	Преобразует значение `DateTime64` в значение `Int64`, представляющее количество микросекунд с начала эпохи Unix. Входное значение округляется соответствующим образом.
`toUnixTimestamp64Nano(value)`	Преобразует значение `DateTime64` в значение `Int64`, представляющее количество наносекунд с начала эпохи Unix. Входное значение округляется соответствующим образом.
`fromUnixTimestamp64Milli(value [, timezone])`	Преобразует значение `Int64`, представляющее количество миллисекунд с начала эпохи Unix, в значение `DateTime64` с точностью до миллисекунд и опционально применяет часовой пояс.
`fromUnixTimestamp64Micro(value [, timezone])`	Преобразует значение `Int64`, представляющее количество микросекунд с начала эпохи Unix, в значение `DateTime64` с точностью до микросекунд и опционально применяет часовой пояс.
`fromUnixTimestamp64Nano(value [, timezone])`	Преобразует значение `Int64`, представляющее количество наносекунд с начала эпохи Unix, в значение `DateTime64` с точностью до наносекунд и опционально применяет часовой пояс.
`dateTimeToSnowflake(value)`	Преобразует значение `DateTime` в первый идентификатор Snowflake ID на текущий момент.
`dateTime64ToSnowflake(value)`	Преобразует значение `DateTime64` в первый идентификатор Snowflake ID на текущий момент.
`snowflakeToDateTime(value [, timezone])`	Извлекает время из Snowflake ID и преобразует его в формат `DateTime`, принимая во внимание часовой пояс, если он указан.
`snowflakeToDateTime64(value [, timezone])`	Извлекает время из Snowflake ID и преобразует его в формат `DateTime64`, принимая во внимание часовой пояс, если он указан.

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

Таблица 7. Функции преобразования в интервалы времени
Функция	Описание
`toIntervalYear`	Преобразует числовое значение в тип IntervalYear.
`toIntervalQuarter`	Преобразует числовое значение в тип IntervalQuarter.
`toIntervalMonth`	Преобразует числовое значение в тип IntervalMonth.
`toIntervalWeek`	Преобразует числовое значение в тип IntervalWeek.
`toIntervalDay`	Преобразует числовое значение в тип IntervalDay.
`toIntervalHour`	Преобразует числовое значение в тип IntervalHour.
`toIntervalMinute`	Преобразует числовое значение в тип IntervalMinute.
`toIntervalSecond`	Преобразует числовое значение в тип IntervalSecond.

Таблица 8. Функции преобразования в строковые типы
Функция	Описание
`toString`	Преобразует значение в строковый тип. В случае неудачи генерируется исключение.
`toFixedString(s, N)`	Преобразует строку в фиксированную строку заданной длины N. Если строка короче, она дополняется нулевыми байтами.
`toStringCutToZero(s)`	Обрезает строку до первого нулевого байта.
`toDecimalString(number, scale)`	Преобразует числовое значение в строку с указанным числом знаков после десятичной точки.
`formatRow(format, x, y, …)`	Преобразует произвольные выражения в строку заданного формата, например, `CSV` или `TSV`, и может включать префикс/суффикс в каждой строке в зависимости от настроек.
`formatRowNoNewline(format, x, y, …)`	Аналогично функции `formatRow`, но удаляет завершающий перевод строки в конце отформатированной строки, если он есть.