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

ClickHouse в целом использует те же правила, что и программы на C++.

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

Пример:

SELECT
    toTypeName(toLowCardinality('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type

┌

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

• При преобразовании в строку или из строки значение форматируется или разбирается по тем же правилам, что и для формата TabSeparated (и почти всех остальных текстовых форматов). Если строку не удаётся разобрать, генерируется исключение, и запрос отменяется.
• При преобразовании дат в числа или наоборот дата соответствует количеству дней с начала эпохи Unix.
• При преобразовании значений даты и времени в числа или наоборот дата и время соответствуют количеству секунд с начала эпохи Unix.
• Функция toString для аргумента DateTime может принимать второй аргумент типа String, содержащий имя часового пояса, например: Europe/Amsterdam. В этом случае время форматируется в соответствии с указанным часовым поясом.

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

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

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

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

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

Пример

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belgrade   │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Berlin     │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bratislava │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Brussels   │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bucharest  │ 2023-09-08 22:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘

См. также функцию toUnixTimestamp.

Добавленный в: v1.1.0

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

Синтаксис

CAST(x, T)
or CAST(x AS T)
or x::T

Аргументы

• x — Значение любого типа. Any
• T — Целевой тип данных. String

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

Возвращает значение, преобразованное в целевой тип данных. Any

Примеры

Базовое использование

SELECT CAST(42, 'String')

┌─CAST(42, 'String')─┐
│ 42                 │
└────────────────────┘

Использование ключевого слова AS

SELECT CAST('2025-01-01' AS Date)

┌─CAST('2025-01-01', 'Date')─┐
│                 2025-01-01 │
└────────────────────────────┘

Использование синтаксиса ::

SELECT '123'::UInt32

┌─CAST('123', 'UInt32')─┐
│                   123 │
└───────────────────────┘

Добавленный в: v21.2.0

Преобразует аргумент в тип данных Date. Это псевдоним toDate для совместимости с MySQL. Работает так же, как toDate.

Синтаксис

DATE(expr)

Аргументы

• expr — Значение, которое необходимо преобразовать. String или UInt32 или Date или DateTime

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

Возвращает значение типа Date. Date

Примеры

Базовое использование

SELECT DATE('2023-01-01')

2023-01-01

Добавленный в: v1.1.0

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

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

Синтаксис

accurateCast(x, T)

Аргументы

• x — Значение для преобразования. Any
• T — Имя целевого типа данных. String

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

Возвращает преобразованное значение целевого типа данных. Any

Примеры

Успешное преобразование

SELECT accurateCast(42, 'UInt16')

┌─accurateCast(42, 'UInt16')─┐
│                         42 │
└────────────────────────────┘

String в число

SELECT accurateCast('123.45', 'Float64')

┌─accurateCast('123.45', 'Float64')─┐
│                            123.45 │
└───────────────────────────────────┘

Добавленный в: v21.1.0

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

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

Синтаксис

accurateCastOrDefault(x, T[, default_value])

Аргументы

• x — Значение для преобразования. Any
• T — Имя целевого типа данных. const String
• default_value — Необязательный параметр. Значение по умолчанию, которое возвращается, если преобразование не удалось. Any

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

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

Примеры

Успешное преобразование

SELECT accurateCastOrDefault(42, 'String')

┌─accurateCastOrDefault(42, 'String')─┐
│ 42                                  │
└─────────────────────────────────────┘

Неудачное преобразование с явно заданным значением по умолчанию

SELECT accurateCastOrDefault('abc', 'UInt32', 999::UInt32)

┌─accurateCastOrDefault('abc', 'UInt32', CAST('999', 'UInt32'))─┐
│                                                           999 │
└───────────────────────────────────────────────────────────────┘

Сбой преобразования с неявным значением по умолчанию

SELECT accurateCastOrDefault('abc', 'UInt32')

┌─accurateCastOrDefault('abc', 'UInt32')─┐
│                                      0 │
└────────────────────────────────────────┘

Добавленный в: v1.1.0

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

Эта функция сочетает безопасность accurateCast с удобной обработкой ошибок.

Синтаксис

accurateCastOrNull(x, T)

Аргументы

• x — Значение, которое нужно преобразовать. Any
• T — Имя целевого типа данных. String

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

Возвращает преобразованное значение целевого типа данных или NULL, если преобразование невозможно. Any

Примеры

Успешное преобразование

SELECT accurateCastOrNull(42, 'String')

┌─accurateCastOrNull(42, 'String')─┐
│ 42                               │
└──────────────────────────────────┘

При ошибке преобразования возвращается NULL

SELECT accurateCastOrNull('abc', 'UInt32')

┌─accurateCastOrNull('abc', 'UInt32')─┐
│                                ᴺᵁᴸᴸ │
└─────────────────────────────────────┘

Добавленный в: v20.7.0

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

Синтаксис

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

Аргументы

• format — Текстовый формат. Например, CSV, TSV. String
• x, y, ... — Выражения. Any

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

Отформатированная строка. (для текстовых форматов она обычно заканчивается символом новой строки). String

Примеры

Базовое использование

SELECT formatRow('CSV', number, 'good')
FROM numbers(3)

┌─formatRow('CSV', number, 'good')─┐
│ 0,"good"                        ↴│
│ 1,"good"                        ↴│
│ 2,"good"                        ↴│
└──────────────────────────────────┘

В пользовательском формате

SELECT formatRow('CustomSeparated', number, 'good')
FROM numbers(3)
SETTINGS format_custom_result_before_delimiter='<prefix>\n', format_custom_result_after_delimiter='<suffix>'

┌─formatRow('CustomSeparated', number, 'good')─┐
│ <prefix>                                    ↴│
│↳0	good                                     ↴│
│↳<suffix>                                     │
│ <prefix>                                    ↴│
│↳1	good                                     ↴│
│↳<suffix>                                     │
│ <prefix>                                    ↴│
│↳2	good                                     ↴│
│↳<suffix>                                     │
└──────────────────────────────────────────────┘

Добавленный в: v20.7.0

То же, что и formatRow, но без символа новой строки в конце каждой строки.

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

Синтаксис

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

Аргументы

• format — Текстовый формат, например CSV или TSV. String
• x, y, ... — Выражения. Any

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

Возвращает отформатированную строку без символов новой строки. String

Примеры

Базовое использование

SELECT formatRowNoNewline('CSV', number, 'good')
FROM numbers(3)

┌─formatRowNoNewline('CSV', number, 'good')─┐
│ 0,"good"                                  │
│ 1,"good"                                  │
│ 2,"good"                                  │
└───────────────────────────────────────────┘

Добавленный в: v20.5.0

Преобразует Unix-временную метку в микросекундах в значение DateTime64 с точностью до микросекунд.

Входное значение интерпретируется как Unix-временная метка с микросекундной точностью (число микросекунд с 1970-01-01 00:00:00 UTC).

Синтаксис

fromUnixTimestamp64Micro(value[, timezone])

Аргументы

• value — Unix-временная метка в микросекундах. Int64
• timezone — Необязательно. Часовой пояс возвращаемого значения. String

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

Возвращает значение DateTime64 с точностью до микросекунд. DateTime64(6)

Примеры

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

SELECT fromUnixTimestamp64Micro(1640995200123456)

┌─fromUnixTimestamp64Micro(1640995200123456)─┐
│                 2022-01-01 00:00:00.123456 │
└────────────────────────────────────────────┘

Добавленный в: v20.5.0

Преобразует Unix-временную метку в миллисекундах в значение DateTime64 с миллисекундной точностью.

Входное значение интерпретируется как Unix-временная метка с миллисекундной точностью (количество миллисекунд, прошедших с 1970-01-01 00:00:00 UTC).

Синтаксис

fromUnixTimestamp64Milli(value[, timezone])

Аргументы

• value — Unix-временная метка в миллисекундах. Int64
• timezone — Необязательный параметр. Часовой пояс возвращаемого значения. String

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

Значение DateTime64 с точностью до миллисекунд. DateTime64(3)

Примеры

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

SELECT fromUnixTimestamp64Milli(1640995200123)

┌─fromUnixTimestamp64Milli(1640995200123)─┐
│                 2022-01-01 00:00:00.123 │
└─────────────────────────────────────────┘

Добавленный в: v20.5.0

Преобразует Unix-временную метку в наносекундах в значение DateTime64 с точностью до наносекунд.

Входное значение интерпретируется как Unix-временная метка с точностью до наносекунд (количество наносекунд, прошедших с 1970-01-01 00:00:00 UTC).

Синтаксис

fromUnixTimestamp64Nano(value[, timezone])

Аргументы

• value — Unix-временная метка в наносекундах. Int64
• timezone — Необязательно. Часовой пояс возвращаемого значения. String

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

Возвращает значение DateTime64 с точностью до наносекунд. DateTime64(9)

Примеры

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

SELECT fromUnixTimestamp64Nano(1640995200123456789)

┌─fromUnixTimestamp64Nano(1640995200123456789)─┐
│                2022-01-01 00:00:00.123456789 │
└──────────────────────────────────────────────┘

Добавленный в: v24.12.0

Преобразует Unix-временную метку в секундах в значение DateTime64 с точностью до секунд.

Входное значение интерпретируется как Unix-временная метка с точностью до секунд (количество секунд с 1970-01-01 00:00:00 UTC).

Синтаксис

fromUnixTimestamp64Second(value[, timezone])

Аргументы

• value — Unix-временная метка в секундах. Int64
• timezone — Необязательный. Часовой пояс для возвращаемого значения. String

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

Возвращает значение DateTime64 с точностью до секунды. DateTime64(0)

Примеры

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

SELECT fromUnixTimestamp64Second(1640995200)

┌─fromUnixTimestamp64Second(1640995200)─┐
│                   2022-01-01 00:00:00 │
└───────────────────────────────────────┘

Добавленный в: v23.3.0

Разбирает строку с датой и временем в соответствии со строкой формата даты MySQL.

Эта функция обратна formatDateTime. Она разбирает аргумент типа String, используя строку формата String. Возвращает значение типа DateTime.

Синтаксис

parseDateTime(time_string, format[, timezone])

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

Аргументы

• time_string — Строка, которую нужно разобрать в DateTime. String
• format — Строка формата, определяющая, как разбирать time_string. String
• timezone — Необязательно. Часовой пояс. String

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

Возвращает значение DateTime, разобранное из входной строки в соответствии со строкой формата в стиле MySQL. DateTime

Примеры

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

SELECT parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                       2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────┘

Добавленный в: v20.9.0

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

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

Синтаксис

parseDateTime32BestEffort(time_string[, time_zone])

Аргументы

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

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

Возвращает time_string в формате DateTime. DateTime

Примеры

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

SELECT parseDateTime32BestEffort('23/10/2025 12:12:57')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-10-23 12:12:57 │
└───────────────────────────┘

С часовым поясом

SELECT parseDateTime32BestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-08-18 10:22:16 │
└───────────────────────────┘

Unix-временная метка

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2010-09-10 06:51:25 │
└───────────────────────────┘

Добавленный в: v20.9.0

То же, что и parseDateTime32BestEffort, но при обнаружении формата даты, который невозможно обработать, функция возвращает NULL.

Синтаксис

parseDateTime32BestEffortOrNull(time_string[, time_zone])

Аргументы

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

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

Возвращает объект DateTime, разобранный из строки, или NULL, если разобрать строку не удалось. DateTime

Примеры

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

SELECT
    parseDateTime32BestEffortOrNull('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrNull('invalid date') AS invalid

┌───────────────valid─┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

Добавленный в: v20.9.0

То же, что и parseDateTime32BestEffort, но при встрече с неподдерживаемым форматом даты функция возвращает нулевую дату или нулевое значение дата-время.

Синтаксис

parseDateTime32BestEffortOrZero(time_string[, time_zone])

Аргументы

• time_string — Строка с датой и временем для преобразования. String
• time_zone — Необязательно. Часовой пояс, в соответствии с которым разбирается time_string. String

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

Возвращает объект DateTime, полученный при разборе строки, или нулевую дату (1970-01-01 00:00:00), если разбор не удался. DateTime

Примеры

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

SELECT
    parseDateTime32BestEffortOrZero('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrZero('invalid date') AS invalid

┌───────────────valid─┬─────────────invalid─┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

Добавленный в: v24.11.0

Разбирает строку даты и времени с точностью до долей секунды в соответствии со строкой формата даты MySQL.

Эта функция является обратной к formatDateTime для DateTime64. Она разбирает аргумент типа String с помощью строки формата String. Возвращает тип DateTime64, который может представлять даты с 0000 по 9999 год с точностью до долей секунды (при более высокой точности диапазон становится уже, поскольку значение хранится как число тиков Int64: точность 8 охватывает примерно до 4892 года, а точность 9 — диапазон с 1677 по 2262 год).

Синтаксис

parseDateTime64(time_string, format[, timezone])

Аргументы

• time_string — Строка, которую нужно разобрать как DateTime64. String
• format — Строка формата, задающая способ разбора time_string. String
• timezone — Необязательно. Часовой пояс. String

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

Возвращает значение DateTime64, разобранное из входной строки в соответствии со строкой формата в стиле MySQL. DateTime64

Примеры

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

SELECT parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                         2025-01-04 23:00:00.123000 │
└────────────────────────────────────────────────────────────────────┘

Добавленный в: v20.1.0

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

Синтаксис

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

Аргументы

• time_string — Строка, содержащая дату или дату и время для преобразования. String
• precision — Необязательно. Требуемая точность. 3 для миллисекунд, 6 для микросекунд. По умолчанию: 3. UInt8
• time_zone — Необязательно. Часовой пояс. Функция разбирает time_string с учетом часового пояса. String

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

Возвращает time_string, преобразованную в тип данных DateTime64. DateTime64

Примеры

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

SELECT parseDateTime64BestEffort('2025-01-01') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',3,'Asia/Istanbul') AS a, toTypeName(a) AS t
FORMAT PrettyCompactMonoBlock

┌──────────────────────────a─┬─t──────────────────────────────┐
│ 2025-01-01 01:01:00.123000 │ DateTime64(3)                  │
│ 2025-01-01 00:00:00.000000 │ DateTime64(3)                  │
│ 2025-01-01 01:01:00.123460 │ DateTime64(6)                  │
│ 2025-12-31 22:01:00.123000 │ DateTime64(3, 'Asia/Istanbul') │
└────────────────────────────┴────────────────────────────────┘

Добавленный в: v20.1.0

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

Синтаксис

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

Аргументы

• time_string — Строка, содержащая дату или дату и время для преобразования. String
• precision — Необязательно. Требуемая точность. 3 для миллисекунд, 6 для микросекунд. По умолчанию: 3. UInt8
• time_zone — Необязательно. Часовой пояс. Функция разбирает time_string в соответствии с часовым поясом. String

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

Возвращает time_string, преобразованную в DateTime64, или NULL, если входное значение не удаётся разобрать. DateTime64 или NULL

Примеры

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

SELECT parseDateTime64BestEffortOrNull('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrNull('invalid') AS invalid

┌───────────────────valid─┬─invalid─┐
│ 2025-01-01 01:01:00.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

Добавленный в: v20.1.0

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

Синтаксис

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

Аргументы

• time_string — Строка, содержащая дату или дату и время для преобразования. String
• precision — Необязательно. Требуемая точность. 3 для миллисекунд, 6 для микросекунд. По умолчанию: 3. UInt8
• time_zone — Необязательно. Часовой пояс. Функция разбирает time_string с учетом этого часового пояса. String

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

Возвращает значение time_string, преобразованное в DateTime64, или нулевую дату/дату и время (1970-01-01 00:00:00.000), если входное значение не удается разобрать. DateTime64

Примеры

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

SELECT parseDateTime64BestEffortOrZero('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrZero('invalid') AS invalid

┌───────────────────valid─┬─────────────────invalid─┐
│ 2025-01-01 01:01:00.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

Добавленный в: v22.8.0

То же, что и parseDateTime64BestEffort, но в неоднозначных случаях эта функция отдает предпочтение американскому формату даты (MM/DD/YYYY и т. д.).

Синтаксис

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

Аргументы

• time_string — Строка String, содержащая дату или дату и время для преобразования. String
• precision — Необязательно. Требуемая точность. 3 для миллисекунд, 6 для микросекунд. По умолчанию: 3. UInt8
• time_zone — Необязательно. Часовой пояс. Функция разбирает time_string в соответствии с указанным часовым поясом. String

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

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

Примеры

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

SELECT parseDateTime64BestEffortUS('02/10/2025 12:30:45.123') AS us_format,
       parseDateTime64BestEffortUS('15/08/2025 10:15:30.456') AS fallback_to_standard

┌───────────────us_format─┬────fallback_to_standard─┐
│ 2025-02-10 12:30:45.123 │ 2025-08-15 10:15:30.456 │
└─────────────────────────┴─────────────────────────┘

Добавленный в: v22.8.0

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

Синтаксис

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

Аргументы

• time_string — Строка, содержащая дату или дата и время для преобразования. String
• precision — Необязательный параметр. Требуемая точность. 3 для миллисекунд, 6 для микросекунд. По умолчанию: 3. UInt8
• time_zone — Необязательный параметр. Часовой пояс. Функция разбирает time_string в соответствии с этим часовым поясом. String

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

Возвращает time_string, преобразованную в DateTime64 с приоритетом американского формата даты, или NULL, если входное значение не удаётся разобрать. DateTime64 или NULL

Примеры

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

SELECT parseDateTime64BestEffortUSOrNull('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrNull('invalid') AS invalid

┌────────────────valid_us─┬─invalid─┐
│ 2025-02-10 12:30:45.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

Добавленный в: v22.8.0

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

Синтаксис

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

Аргументы

• time_string — Строка, содержащая дату или дату и время для преобразования. String
• precision — Необязательно. Требуемая точность: 3 для миллисекунд, 6 для микросекунд. По умолчанию: 3. UInt8
• time_zone — Необязательно. Часовой пояс. Функция разбирает time_string в соответствии с этим часовым поясом. String

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

Возвращает time_string, преобразованную в DateTime64 с предпочтением американского формата даты, или нулевую дату/дату и время (1970-01-01 00:00:00.000), если входное значение не удаётся разобрать. DateTime64

Примеры

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

SELECT parseDateTime64BestEffortUSOrZero('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrZero('invalid') AS invalid

┌────────────────valid_us─┬─────────────────invalid─┐
│ 2025-02-10 12:30:45.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

Добавленный в: v24.10.0

Разбирает строку даты и времени с точностью до долей секунды в соответствии со строкой формата даты и времени Joda.

Эта функция является обратной к formatDateTimeInJodaSyntax для DateTime64. Она разбирает аргумент типа String, используя строку формата в стиле Joda. Возвращает значение типа DateTime64, которое может представлять даты с 0000 по 9999 год с точностью до долей секунды (при высокой точности охватывается более узкий диапазон, поскольку значение хранится как количество ticks в Int64: точность 8 достигает примерно 4892 года, а точность 9 охватывает диапазон с 1677 по 2262 год).

Описание шаблонов формата см. в документации Joda Time.

Синтаксис

parseDateTime64InJodaSyntax(time_string, format[, timezone])

Аргументы

• time_string — Строка String, которую нужно разобрать в DateTime64. String
• format — Строка формата в синтаксисе Joda, задающая способ разбора time_string. String
• timezone — Необязательно. Часовой пояс. String

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

Возвращает значение DateTime64, разобранное из входной строки в соответствии со строкой формата в стиле Joda. DateTime64

Примеры

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

SELECT parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                           2025-01-04 23:00:00.123 │
└───────────────────────────────────────────────────────────────────────────────────┘

Добавленный в: v24.10.0

То же, что и parseDateTime64InJodaSyntax, но возвращает NULL, если указан неподдающийся разбору формат даты.

Синтаксис

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

Аргументы

• time_string — строка, которую нужно разобрать как DateTime64. String
• format — строка формата в синтаксисе Joda, задающая способ разбора time_string. String
• timezone — необязательный параметр. Часовой пояс. String

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

Возвращает значение DateTime64, разобранное из входной строки, или NULL, если разбор не удался. Nullable(DateTime64)

Примеры

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

SELECT parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                                 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────────────────────────┘

Добавленный в: v24.10.0

То же, что и parseDateTime64InJodaSyntax, но при неподдающемся разбору формате даты возвращает нулевую дату.

Синтаксис

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

Аргументы

• time_string — Строка String, которую нужно преобразовать в DateTime64. String
• format — Строка формата в синтаксисе Joda, задающая способ разбора time_string. String
• timezone — Необязательный параметр. Часовой пояс. String

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

Возвращает значение DateTime64, разобранное из входной строки, или нулевое значение DateTime64, если разбор завершился неудачно. DateTime64

Примеры

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

SELECT parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                                 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────────────────────────┘

Добавленный в: v24.11.0

То же, что и parseDateTime64, но возвращает NULL, если встречается неподдающийся разбору формат даты.

Синтаксис

parseDateTime64OrNull(time_string, format[, timezone])

Аргументы

• time_string — Строка, которую нужно разобрать как DateTime64. String
• format — Строка формата, задающая способ разбора time_string. String
• timezone — Необязательный параметр. Часовой пояс. String

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

Возвращает DateTime64, разобранный из входной строки, или NULL, если разбор не удался. Nullable(DateTime64)

Примеры

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

SELECT parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                               2025-01-04 23:00:00.123000 │
└──────────────────────────────────────────────────────────────────────────┘

Добавленный в: v24.11.0

То же, что и parseDateTime64, но возвращает нулевую дату, если встречает неподдающийся разбору формат даты.

Синтаксис

parseDateTime64OrZero(time_string, format[, timezone])

Аргументы

• time_string — Строка, которую нужно разобрать в DateTime64. String
• format — Строка формата, задающая, как разобрать time_string. String
• timezone — Необязательный параметр. Часовой пояс. String

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

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

Примеры

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

SELECT parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                               2025-01-04 23:00:00.123000 │
└──────────────────────────────────────────────────────────────────────────┘

Добавленный в: v1.1.0

Преобразует дату и время из строкового представления String в тип данных DateTime. Функция разбирает форматы даты и времени ISO 8601, RFC 1123 - 5.2.14 RFC-822, формат ClickHouse, а также некоторые другие.

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

• Строка, содержащая 9–10-значную Unix-временную метку.
• Строка с датой и компонентом времени: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss и т. д.
• Строка с датой, но без компонента времени: 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 и т. д.
• Временная метка syslog: Mmm dd hh:mm:ss. Например, Jun 9 14:20:32.

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

Синтаксис

parseDateTimeBestEffort(time_string[, time_zone])

Аргументы

• time_string — Строка с датой и временем для преобразования. String
• time_zone — Необязательный параметр. Часовой пояс, в соответствии с которым разбирается time_string. String

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

Возвращает time_string в формате DateTime. DateTime

Примеры

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

SELECT parseDateTimeBestEffort('23/10/2025 12:12:57') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-10-23 12:12:57 │
└─────────────────────────┘

С указанием часового пояса

SELECT parseDateTimeBestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-08-18 10:22:16 │
└─────────────────────────┘

Unix-временная метка

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-01-01 00:00:00 │
└─────────────────────────┘

Добавленный в: v1.1.0

То же, что и parseDateTimeBestEffort, за исключением того, что функция возвращает NULL, если встречает формат даты, который не может обработать. Функция разбирает ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, форматы даты и времени ClickHouse, а также некоторые другие форматы.

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

• Строка, содержащая 9..10-значную Unix-временную метку.
• Строка с датой и компонентом времени: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss и т. д.
• Строка с датой, но без компонента времени: 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 и т. д.
• Временная метка syslog: Mmm dd hh:mm:ss. Например, Jun 9 14:20:32.

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

Синтаксис

parseDateTimeBestEffortOrNull(time_string[, time_zone])

Аргументы

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

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

Возвращает time_string в виде DateTime или NULL, если входное значение не удаётся разобрать. DateTime или NULL

Примеры

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

SELECT parseDateTimeBestEffortOrNull('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrNull('invalid') AS invalid

┌───────────────valid─┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

Добавленный в: v1.1.0

То же, что и parseDateTimeBestEffort, за исключением того, что функция возвращает нулевую дату или нулевое значение дата-времени, если встречает формат даты, который не может быть обработан. Функция разбирает ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, а также форматы даты и времени ClickHouse и некоторые другие форматы.

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

• Строка, содержащая 9..10-значную Unix-временную метку.
• Строка с датой и временем: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss и т. д.
• Строка с датой, но без времени: 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 и т. д.
• Временная метка syslog: Mmm dd hh:mm:ss. Например, Jun 9 14:20:32.

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

Синтаксис

parseDateTimeBestEffortOrZero(time_string[, time_zone])

Аргументы

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

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

Возвращает time_string в формате DateTime или нулевую дату/дату-время (1970-01-01 или 1970-01-01 00:00:00), если входное значение не удаётся разобрать. DateTime

Примеры

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

SELECT parseDateTimeBestEffortOrZero('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrZero('invalid') AS invalid

┌───────────────valid─┬─────────────invalid─┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

Добавленный в: v1.1.0

Эта функция ведёт себя как parseDateTimeBestEffort для дат в формате ISO, например YYYY-MM-DD hh:mm:ss, а также для других форматов даты, где месяц и день можно определить однозначно, например YYYYMMDDhhmmss, YYYY-MM, DD hh или YYYY-MM-DD hh:mm:ss ±h:mm. Если месяц и день нельзя определить однозначно, например в MM/DD/YYYY, MM-DD-YYYY или MM-DD-YY, функция отдаёт предпочтение американскому формату даты, а не DD/MM/YYYY, DD-MM-YYYY или DD-MM-YY. Исключение из этого правила: если значение месяца больше 12 и меньше либо равно 31, функция возвращается к поведению parseDateTimeBestEffort; например, 15/08/2020 разбирается как 2020-08-15.

Синтаксис

parseDateTimeBestEffortUS(time_string[, time_zone])

Аргументы

• time_string — String с датой и временем для преобразования. String
• time_zone — Необязательно. Часовой пояс, в соответствии с которым разбирается time_string. String

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

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

Примеры

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

SELECT parseDateTimeBestEffortUS('02/10/2025') AS us_format,
       parseDateTimeBestEffortUS('15/08/2025') AS fallback_to_standard

┌───────────us_format─┬─fallback_to_standard─┐
│ 2025-02-10 00:00:00 │  2025-08-15 00:00:00 │
└─────────────────────┴──────────────────────┘

Добавленный в: v1.1.0

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

Для форматов дат ISO эта функция ведет себя как parseDateTimeBestEffort, но в неоднозначных случаях предпочитает американский формат даты и при ошибках разбора возвращает NULL.

Синтаксис

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

Аргументы

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

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

Возвращает time_string как DateTime с приоритетом американского формата даты или NULL, если входное значение не удаётся разобрать. DateTime или NULL

Примеры

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

SELECT parseDateTimeBestEffortUSOrNull('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrNull('invalid') AS invalid

┌────────────valid_us─┬─invalid─┐
│ 2025-02-10 00:00:00 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

Добавленный в: v1.1.0

То же, что и функция parseDateTimeBestEffortUS, за исключением того, что при обнаружении формата даты, который не удаётся обработать, она возвращает нулевую дату (1970-01-01) или нулевую дату и время (1970-01-01 00:00:00).

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

Синтаксис

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

Аргументы

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

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

Возвращает time_string в виде DateTime с предпочтением американского формата или нулевую дату/дату-время (1970-01-01 или 1970-01-01 00:00:00), если входное значение не удаётся разобрать. DateTime

Примеры

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

SELECT parseDateTimeBestEffortUSOrZero('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrZero('invalid') AS invalid

┌────────────valid_us─┬─────────────invalid─┐
│ 2025-02-10 00:00:00 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

Добавленный в: v23.3.0

Разбирает строку с датой и временем в соответствии со строкой формата даты Joda.

Эта функция является обратной к formatDateTimeInJodaSyntax. Она разбирает аргумент типа String, используя строку формата в стиле Joda. Возвращает значение типа DateTime.

Описание шаблонов формата см. в документации Joda Time.

Синтаксис

parseDateTimeInJodaSyntax(time_string, format[, timezone])

Аргументы

• time_string — Строка для разбора в DateTime. String
• format — Строка формата в синтаксисе Joda, задающая способ разбора time_string. String
• timezone — Необязательно. Часовой пояс. String

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

Возвращает значение DateTime, полученное путём разбора входной строки в соответствии со строкой формата в стиле Joda. DateTime

Примеры

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

SELECT parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                     2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────────────┘

Добавленный в: v23.3.0

То же, что и parseDateTimeInJodaSyntax, но при неподдающемся разбору формате даты возвращает NULL.

Синтаксис

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

Аргументы

• time_string — Строка, которую нужно разобрать как DateTime. String
• format — Строка формата в синтаксисе Joda, задающая способ разбора time_string. String
• timezone — Необязательно. Часовой пояс. String

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

Возвращает DateTime, разобранный из входной строки, или NULL, если разбор завершился неудачно. Nullable(DateTime)

Примеры

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

SELECT parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                           2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────────────────────────┘

Добавленный в: v23.3.0

То же, что и parseDateTimeInJodaSyntax, но возвращает нулевую дату, если встречается неподдающийся разбору формат даты.

Синтаксис

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

Аргументы

• time_string — строка, которую нужно разобрать как DateTime. String
• format — строка формата в синтаксисе Joda, задающая, как разбирать time_string. String
• timezone — Необязательно. Часовой пояс. String

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

Возвращает значение DateTime, разобранное из входной строки, или нулевой DateTime, если разобрать строку не удалось. DateTime

Примеры

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

SELECT parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                           2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────────────────────────┘

Добавленный в: v23.3.0

То же, что и parseDateTime, но возвращает NULL, если встречает неподдающийся разбору формат даты.

Синтаксис

parseDateTimeOrNull(time_string, format[, timezone])

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

Аргументы

• time_string — Строка, преобразуемая в DateTime. String
• format — Строка формата, задающая способ разбора time_string. String
• timezone — Необязательный параметр. Часовой пояс. String

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

Возвращает DateTime, разобранный из входной строки, или NULL, если разбор не удался. Nullable(DateTime)

Примеры

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

SELECT parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                             2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘

Добавленный в: v23.3.0

То же, что и parseDateTime, но при неподдающемся разбору формате даты возвращает нулевую дату.

Синтаксис

parseDateTimeOrZero(time_string, format[, timezone])

Аргументы

• time_string — Строка для разбора в DateTime. String
• format — Строка формата, задающая способ разбора time_string. String
• timezone — Необязательно. Часовой пояс. String

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

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

Примеры

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

SELECT parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                             2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘

Добавленный в: v1.1.0

Использует ту же последовательность байтов в памяти исходного значения для значения x и переинтерпретирует её как целевой тип. Если целевой тип — String, исходный Array поддерживается только в том случае, если тип его элементов имеет фиксированный размер и они расположены в памяти непрерывно (например, Array(UInt8) или Array(FixedString(2))); байты элементов копируются как есть в их естественном порядке в памяти, поэтому результат можно переинтерпретировать обратно в исходный тип Array на любой архитектуре. Массивы, элементы которых имеют переменную длину (например, Array(String)) или допускают значение NULL (например, Array(Nullable(Int32))), не поддерживаются.

Синтаксис

reinterpret(x, type)

Аргументы

• x — Значение для переинтерпретации. При переинтерпретации в String исходный Array должен состоять из непрерывно расположенных элементов фиксированного размера. Any
• type — Целевой тип. Если это массив, тип его элементов должен иметь фиксированную длину. String

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

Значение целевого типа. Any

Примеры

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

SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
    reinterpret(toInt8(1), 'Float32') AS int_to_float,
    reinterpret('1', 'UInt32') AS string_to_int

┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│         255 │        1e-45 │            49 │
└─────────────┴──────────────┴───────────────┘

Пример типа Array

SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32

┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626]  │
└────────────────────────────┘

Пример преобразования Array в String

SELECT hex(reinterpret([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8), 'String')) AS array_of_UInt8_to_string

┌─array_of_UInt8_to_string─┐
│ 0102FF                   │
└──────────────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Date (предполагая порядок little endian), то есть как количество дней с начала эпохи Unix — 1970-01-01

Синтаксис

reinterpretAsDate(x)

Аргументы

• x — Количество дней с начала эпохи Unix. (U)Int* или Float*, или Date, или DateTime, или UUID, или String, или FixedString

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

Дата. Date

Примеры

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

SELECT reinterpretAsDate(65), reinterpretAsDate('A')

┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│            1970-03-07 │             1970-03-07 │
└───────────────────────┴────────────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение DateTime (предполагая порядок little endian), представляющее собой количество дней с начала эпохи Unix 1970-01-01

Синтаксис

reinterpretAsDateTime(x)

Аргументы

• x — Число секунд с начала эпохи Unix. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Дата и время. DateTime

Примеры

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

SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')

┌─reinterpretAsDateTime(65)─┬─reinterpretAsDateTime('A')─┐
│       1970-01-01 00:01:05 │        1970-01-01 00:01:05 │
└───────────────────────────┴────────────────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как строку фиксированной длины (предполагается порядок little endian). Null-байты в конце игнорируются; например, для значения UInt32 255 функция возвращает строку из одного символа.

Синтаксис

reinterpretAsFixedString(x)

Аргументы

• x — значение, которое нужно переинтерпретировать в строку. (U)Int* или Float* или Date или DateTime

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

Строка фиксированной длины, содержащая байты, представляющие x. FixedString

Примеры

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

-- The result is a sequence of bytes, so it is shown with `hex`.
SELECT
    hex(reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))),
    hex(reinterpretAsFixedString(toDate('1970-03-07')))

┌─hex(reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05')))─┬─hex(reinterpretAsFixedString(toDate('1970-03-07')))─┐
│ 510E0000                                                         │ 4100                                                │
└──────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

Добавленный в: v1.1.0

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

Синтаксис

reinterpretAsFloat32(x)

Аргументы

• x — Значение, переинтерпретируемое как Float32. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. Float32

Примеры

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

SELECT reinterpretAsUInt32(toFloat32(0.2)) AS x, reinterpretAsFloat32(x)

┌──────────x─┬─reinterpretAsFloat32(x)─┐
│ 1045220557 │                     0.2 │
└────────────┴─────────────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Float64. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не способен представить входной тип, результат не определён.

Синтаксис

reinterpretAsFloat64(x)

Аргументы

• x — Значение, переинтерпретируемое как Float64. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. Float64

Примеры

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

SELECT reinterpretAsUInt64(toFloat64(0.2)) AS x, reinterpretAsFloat64(x)

┌───────────────────x─┬─reinterpretAsFloat64(x)─┐
│ 4596373779694328218 │                     0.2 │
└─────────────────────┴─────────────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Int128. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsInt128(x)

Аргументы

• x — Значение, переинтерпретируемое как Int128. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает значение x, переинтерпретированное как Int128

Примеры

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

SELECT
    toInt64(257) AS x,
    toTypeName(x),
    reinterpretAsInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int64         │ 257 │ Int128          │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Int16. В отличие от CAST, эта функция не пытается сохранить исходное значение: если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsInt16(x)

Аргументы

• x — Значение, переинтерпретируемое как Int16. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. Int16

Примеры

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

SELECT
    toInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ Int8          │   1 │ Int16           │
└───┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Int256. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsInt256(x)

Аргументы

• x — Значение для переинтерпретации в Int256. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. Int256

Примеры

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

SELECT
    toInt128(257) AS x,
    toTypeName(x),
    reinterpretAsInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int128        │ 257 │ Int256          │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Int32. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsInt32(x)

Аргументы

• x — Значение, которое нужно реинтерпретировать как Int32. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает значение x, реинтерпретированное как Int32.

Примеры

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

SELECT
    toInt16(257) AS x,
    toTypeName(x),
    reinterpretAsInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int16         │ 257 │ Int32           │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа Int64. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsInt64(x)

Аргументы

• x — значение, которое нужно переинтерпретировать как Int64. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Переинтерпретированное значение x. Int64

Примеры

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

SELECT
    toInt32(257) AS x,
    toTypeName(x),
    reinterpretAsInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int32         │ 257 │ Int64           │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

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

Синтаксис

reinterpretAsInt8(x)

Аргументы

• x — значение для переинтерпретации как Int8. (U)Int* or Float* or Date or DateTime or UUID or String or FixedString

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

Возвращает переинтерпретированное значение x. Int8

Примеры

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

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt8(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ Int8            │
└───┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как строку. Для скалярных значений порядок байтов нормализуется к little endian, а null-байты в конце игнорируются; например, для значения UInt32 255 функция возвращает строку из одного символа. Для Array из элементов фиксированного размера байты элементов копируются как есть в их исходном порядке в памяти, без обрезки завершающих нулевых байтов и без нормализации к little endian, поэтому результат можно переинтерпретировать обратно в исходный тип Array на любой архитектуре.

Синтаксис

reinterpretAsString(x)

Аргументы

• x — Значение, которое нужно переинтерпретировать в строку. (U)Int* или Float* или Date или DateTime или Array

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

Строка, содержащая байты, представляющие x. String

Примеры

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

-- The result is a sequence of bytes, so it is shown with `hex`.
SELECT
    hex(reinterpretAsString(toDateTime('1970-01-01 01:01:05'))),
    hex(reinterpretAsString(toDate('1970-03-07')))

┌─hex(reinterpretAsString(toDateTime('1970-01-01 01:01:05')))─┬─hex(reinterpretAsString(toDate('1970-03-07')))─┐
│ 510E                                                        │ 41                                             │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘

Пример преобразования из Array в String

SELECT hex(reinterpretAsString([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8))) AS array_of_UInt8_to_string

┌─array_of_UInt8_to_string─┐
│ 0102FF                   │
└──────────────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа UInt128. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsUInt128(x)

Аргументы

• x — Значение, которое нужно переинтерпретировать как UInt128. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. UInt128

Примеры

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

SELECT
    toUInt64(257) AS x,
    toTypeName(x),
    reinterpretAsUInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt64        │ 257 │ UInt128         │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

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

Синтаксис

reinterpretAsUInt16(x)

Аргументы

• x — Значение, которое нужно переинтерпретировать как UInt16. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. UInt16

Примеры

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

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsUInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ UInt16          │
└───┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа UInt256. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsUInt256(x)

Аргументы

• x — значение, которое нужно переинтерпретировать как UInt256. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает переинтерпретированное значение x. UInt256

Примеры

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

SELECT
    toUInt128(257) AS x,
    toTypeName(x),
    reinterpretAsUInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt128       │ 257 │ UInt256         │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа UInt32. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsUInt32(x)

Аргументы

• x — Значение, которое нужно реинтерпретировать как UInt32. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Возвращает значение x, реинтерпретированное как UInt32.

Примеры

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

SELECT
    toUInt16(257) AS x,
    toTypeName(x),
    reinterpretAsUInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt16        │ 257 │ UInt32          │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа UInt64. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsUInt64(x)

Аргументы

• x — Значение, которое нужно переинтерпретировать как UInt64. Int* или UInt* или Float* или Date или DateTime или UUID или String или FixedString

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

Переинтерпретированное значение x. UInt64

Примеры

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

SELECT
    toUInt32(257) AS x,
    toTypeName(x),
    reinterpretAsUInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt32        │ 257 │ UInt64          │
└─────┴───────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Переинтерпретирует входное значение как значение типа UInt8. В отличие от CAST, функция не пытается сохранить исходное значение — если целевой тип не может представить входной тип, результат не определён.

Синтаксис

reinterpretAsUInt8(x)

Аргументы

• x — Значение, которое нужно переинтерпретировать как UInt8. (U)Int* или Float* или Date или DateTime или UUID или String или FixedString

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

Переинтерпретированное значение x. UInt8

Примеры

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

SELECT
    toInt8(-1) AS val,
    toTypeName(val),
    reinterpretAsUInt8(val) AS res,
    toTypeName(res);

┌─val─┬─toTypeName(val)─┬─res─┬─toTypeName(res)─┐
│  -1 │ Int8            │ 255 │ UInt8           │
└─────┴─────────────────┴─────┴─────────────────┘

Добавленный в: v1.1.0

Принимает строку длиной 16 байт и возвращает UUID, интерпретируя каждую 8-байтную половину в порядке little-endian. Если строка короче, чем нужно, функция работает так, как будто в конец строки дописано необходимое количество null-байтов. Если строка длиннее 16 байт, лишние байты в конце игнорируются.

Синтаксис

reinterpretAsUUID(fixed_string)

Аргументы

• fixed_string — Байтовая строка в формате big-endian. FixedString

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

Значение типа UUID. UUID

Примеры

Преобразование строки в UUID

SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))

┌─reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))─┐
│ 08090a0b-0c0d-0e0f-0001-020304050607                                  │
└───────────────────────────────────────────────────────────────────────┘

Добавленный в: v1.1.0

Преобразует входное значение в значение типа BFloat16. В случае ошибки генерирует исключение.

См. также:

• toBFloat16OrZero.
• toBFloat16OrNull.

Синтаксис

toBFloat16(expr)

Аргументы

• expr — выражение, возвращающее число или строковое представление числа. Expression

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

Возвращает 16-битное значение формата brain floating point. BFloat16

Примеры

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

SELECT
toBFloat16(toFloat32(42.7)),
toBFloat16(toFloat32('42.7')),
toBFloat16('42.7')
FORMAT Vertical;

Row 1:
──────
toBFloat16(toFloat32(42.7)):   42.5
toBFloat16(toFloat32('42.7')): 42.5
toBFloat16('42.7'):            42.5

Добавленный в: v1.1.0

Преобразует входное значение String в значение типа BFloat16. Если строка не представляет значение с плавающей запятой, функция возвращает NULL.

Поддерживаемые аргументы:

• Строковые представления числовых значений.

Неподдерживаемые аргументы (возвращают NULL):

• Строковые представления двоичных и шестнадцатеричных значений.
• Числовые значения.

См. также:

• toBFloat16.
• toBFloat16OrZero.

Синтаксис

toBFloat16OrNull(x)

Аргументы

• x — Строковое представление числа. String

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

Возвращает 16-битное значение в формате brain floating point, иначе — NULL. BFloat16 или NULL

Примеры

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

SELECT toBFloat16OrNull('0x5E'), -- unsupported arguments
       toBFloat16OrNull('12.3'), -- typical use
       toBFloat16OrNull('12.3456789') -- silent loss of precision

\N	12.25	12.3125

Добавленный в: v1.1.0

Преобразует входное значение String в значение типа BFloat16. Если строка не представляет собой значение с плавающей запятой, функция возвращает ноль.

Поддерживаемые аргументы:

• Строковые представления числовых значений.

Неподдерживаемые аргументы (возвращают 0):

• Строковые представления двоичных и шестнадцатеричных значений.
• Числовые значения.

См. также:

• toBFloat16.
• toBFloat16OrNull.

Синтаксис

toBFloat16OrZero(x)

Аргументы

• x — Строковое представление числа. String

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

Возвращает 16-битное значение формата brain floating point, иначе — 0. BFloat16

Примеры

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

SELECT toBFloat16OrZero('0x5E'), -- unsupported arguments
       toBFloat16OrZero('12.3'), -- typical use
       toBFloat16OrZero('12.3456789') -- silent loss of precision

0	12.25	12.3125

Добавленный в: v22.2.0

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

Синтаксис

toBool(expr)

Аргументы

• expr — выражение, возвращающее число или строку. Для строк принимает значения 'true' или 'false' (регистронезависимо). (U)Int* или Float* или String или Expression

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

Возвращает true или false в зависимости от результата вычисления аргумента. Bool

Примеры

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

SELECT
    toBool(toUInt8(1)),
    toBool(toInt8(-1)),
    toBool(toFloat32(1.01)),
    toBool('true'),
    toBool('false'),
    toBool('FALSE')
FORMAT Vertical

Row 1:
──────
toBool(toUInt8(1)):      true
toBool(toInt8(-1)):      true
toBool(toFloat32(1.01)): true
toBool('true'):          true
toBool('false'):         false
toBool('FALSE'):         false

Добавленный в: v1.1.0

Преобразует входное значение в тип Date. Поддерживает преобразование из типов String, FixedString, DateTime и числовых типов.

Синтаксис

toDate(x)

Аргументы

• x — Входное значение для преобразования. String или FixedString или DateTime или (U)Int* или Float*

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

Преобразованное входное значение. Date

Примеры

Преобразование String в Date

SELECT toDate('2025-04-15')

2025-04-15

Преобразование DateTime в Date

SELECT toDate(toDateTime('2025-04-15 10:30:00'))

2025-04-15

Преобразование целого числа в тип Date

SELECT toDate(20297)

2025-07-28

Добавленный в: v21.9.0

Преобразует аргумент в тип данных Date32. Если значение выходит за пределы диапазона [0000-01-01, 9999-12-31], toDate32 возвращает граничные значения, поддерживаемые Date32. Если аргумент имеет тип Date, учитываются его границы.

Синтаксис

toDate32(expr)

Аргументы

• expr — значение для преобразования. String, UInt32 или Date

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

Возвращает календарную дату. Date32

Примеры

В допустимом диапазоне

SELECT toDate32('2025-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:             2025-01-01
toTypeName(value): Date32

До 1900 года

SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:             1899-01-01
toTypeName(value): Date32

Добавленный в: v21.11.0

Преобразует аргумент в тип данных Date32. Если аргумент невозможно преобразовать, в том числе если числовое значение выходит за пределы диапазона Date32, функция возвращает значение по умолчанию: второй аргумент (если указан) или, в противном случае, 1900-01-01 — историческое значение по умолчанию для Date32 (а не его нижнюю границу, которой является 0000-01-01). Если аргумент имеет тип Date, учитываются его границы.

Обратите внимание: в отличие от toDate32, эта функция не ограничивает числовой аргумент, выходящий за пределы диапазона, границами Date32; такой аргумент считается непреобразуемым.

Синтаксис

toDate32OrDefault(expr[, default])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. String или (U)Int* или Float*
• default — Необязательно. Значение по умолчанию, возвращаемое, если преобразование не удалось. Date32

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

Значение типа Date32 в случае успешного выполнения; в противном случае возвращается значение по умолчанию, если оно передано, или 1900-01-01, если нет. Date32

Примеры

Успешное преобразование

SELECT toDate32OrDefault('1930-01-01', toDate32('2020-01-01'))

1930-01-01

ошибка преобразования

SELECT toDate32OrDefault('xx1930-01-01', toDate32('2020-01-01'))

2020-01-01

Число вне диапазона

SELECT toDate32OrDefault(toUInt64(18446744073709551615), toDate32('2020-01-01'))

2020-01-01

Добавленный в: v21.9.0

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

Синтаксис

toDate32OrNull(x)

Аргументы

• x — строковое представление даты. String

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

Возвращает значение Date32 в случае успеха, в противном случае — NULL. Date32 или NULL

Примеры

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

SELECT toDate32OrNull('2025-01-01'), toDate32OrNull('invalid')

┌─toDate32OrNull('2025-01-01')─┬─toDate32OrNull('invalid')─┐
│                   2025-01-01 │                      ᴺᵁᴸᴸ │
└──────────────────────────────┴───────────────────────────┘

Добавленный в: v21.9.0

Преобразует входное значение в значение типа Date32, но при получении некорректного аргумента возвращает значение по умолчанию 1900-01-01. То же, что и toDate32, но при получении некорректного аргумента возвращает 1900-01-01. Обратите внимание, что 1900-01-01 — это историческое значение по умолчанию для некорректного входного значения, а не нижняя граница Date32, которой является 0000-01-01.

См. также:

• toDate32
• toDate32OrNull
• toDate32OrDefault

Синтаксис

toDate32OrZero(x)

Аргументы

• x — строковое представление даты. String

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

Возвращает значение Date32 в случае успеха, в противном случае — историческое значение по умолчанию для некорректного ввода (1900-01-01). Date32

Примеры

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

SELECT toDate32OrZero('2025-01-01'), toDate32OrZero('')

┌─toDate32OrZero('2025-01-01')─┬─toDate32OrZero('')─┐
│                   2025-01-01 │         1900-01-01 │
└──────────────────────────────┴────────────────────┘

Добавленный в: v21.11.0

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

Синтаксис

toDateOrDefault(expr[, default])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. String или (U)Int* или Float*
• default — Необязательно. Значение по умолчанию, которое возвращается, если разбор завершился неуспешно. Date

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

Значение типа Date в случае успешного выполнения; в противном случае возвращается значение по умолчанию, если оно передано, или 1970-01-01, если нет. Date

Примеры

Успешное преобразование

SELECT toDateOrDefault('2022-12-30')

2022-12-30

Ошибка преобразования

SELECT toDateOrDefault('', CAST('2023-01-01', 'Date'))

2023-01-01

Добавленный в: v1.1.0

Преобразует входное значение в значение типа Date, но возвращает NULL, если получает некорректный аргумент. То же, что и toDate, но возвращает NULL, если получает некорректный аргумент. Целочисленный аргумент интерпретируется так же, как и в toDate (как количество дней с 1970-01-01, если он не превышает 65535, в противном случае — как Unix-временная метка), и функция возвращает NULL, если значение выходит за диапазон типа Date.

Синтаксис

toDateOrNull(x)

Аргументы

• x — Строковое представление даты, либо целое число дней, либо Unix-временная метка. String или (U)Int8/16/32/64

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

Возвращает значение типа Date в случае успеха, в противном случае — NULL. Date или NULL

Примеры

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

SELECT toDateOrNull('2025-12-30'), toDateOrNull('invalid')

┌─toDateOrNull('2025-12-30')─┬─toDateOrNull('invalid')─┐
│                 2025-12-30 │                    ᴺᵁᴸᴸ │
└────────────────────────────┴─────────────────────────┘

Добавленный в: v1.1.0

Преобразует входное значение в значение типа Date, но возвращает нижнюю границу Date, если передан некорректный аргумент. То же, что и toDate, но при передаче некорректного аргумента возвращает нижнюю границу Date.

См. также:

• toDate
• toDateOrNull
• toDateOrDefault

Синтаксис

toDateOrZero(x)

Аргументы

• x — строковое представление даты. String

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

Возвращает значение типа Date в случае успешного преобразования, в противном случае — нижнюю границу типа Date (1970-01-01). Date

Примеры

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

SELECT toDateOrZero('2025-12-30'), toDateOrZero('')

┌─toDateOrZero('2025-12-30')─┬─toDateOrZero('')─┐
│                 2025-12-30 │       1970-01-01 │
└────────────────────────────┴──────────────────┘

Добавленный в: v1.1.0

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

Синтаксис

toDateTime(expr[, time_zone])

Аргументы

• expr — Значение. String или Int или Date или DateTime
• time_zone — Часовой пояс. String

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

Возвращает значение типа дата-время. DateTime

Примеры

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

SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT Vertical

Row 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'):     2025-01-01 00:00:00

Добавленный в: v20.9.0

Преобразует входное значение в тип DateTime. Поддерживает преобразование из String, FixedString, Date, Date32, Time, DateTime, DateTime64 или числовых типов ((U)Int8, (U)Int16, (U)Int32, (U)Int64, BFloat16, Float32, Float64). Значения Decimal и Time64 не поддерживаются и приводят к исключению; тип Time и широкие целочисленные типы, такие как (U)Int128/(U)Int256, выполняют циклическое переполнение вместо насыщения. DateTime32 — псевдоним DateTime; он поддерживает даты от 1970-01-01 00:00:00 до 2106-02-07 06:28:15. При преобразовании из строки или одного из перечисленных выше числовых типов с насыщением значения за пределами этого диапазона насыщаются до его границ. Неконечные значения с плавающей точкой (NaN, inf, -inf) нельзя преобразовать — они приводят к исключению. Преобразования из других типов даты и времени, таких как Date32 или DateTime64, выполняются в соответствии с настройкой date_time_overflow_behavior: режим ignore по умолчанию может приводить к циклическому переполнению, saturate ограничивает значения границами диапазона, а throw генерирует исключение.

Синтаксис

toDateTime32(x[, timezone])

Аргументы

• x — Входное значение для преобразования. String, FixedString, (U)Int*, Float*, BFloat16, Date, Date32, Time, DateTime или DateTime64
• timezone — Необязательный часовой пояс для возвращаемого значения DateTime. String

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

Возвращает преобразованное входное значение. DateTime

Примеры

Из строки

SELECT toDateTime32('2025-01-01 00:00:00') AS value, toTypeName(value);

┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime          │
└─────────────────────┴───────────────────┘

Из Unix-временной метки

SELECT toDateTime32(1735689600, 'UTC') AS value, toTypeName(value);

┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime('UTC')   │
└─────────────────────┴───────────────────┘

С указанием часового пояса

SELECT toDateTime32('2025-01-01 00:00:00', 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────value─┬─toTypeName(value)─────────┐
│ 2025-01-01 00:00:00 │ DateTime('Asia/Istanbul') │
└─────────────────────┴───────────────────────────┘

Добавленный в: v20.1.0

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

Синтаксис

toDateTime64(expr, scale[, timezone])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Выражение
• scale — Размер тика (точность): 10^(-scale) секунд. UInt8
• timezone — Необязательно. Часовой пояс для указанного объекта DateTime64. String

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

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

Примеры

Значение находится в диапазоне

SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘

В формате десятичного числа с точностью

SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- Without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(value)─┐
│ 2019-01-01 00:00:00.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘
┌───────────────────value─┬─toTypeName(value)─┐
│ 9999-12-31 23:59:59.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘

С указанием часового пояса

SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(value)──────────────┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul') │
└─────────────────────────┴────────────────────────────────┘

Добавленный в: v21.11.0

Как и toDateTime64, эта функция преобразует входное значение в значение типа DateTime64, но при получении некорректного аргумента возвращает либо значение DateTime64 по умолчанию, либо указанное значение по умолчанию.

Синтаксис

toDateTime64OrDefault(expr, scale[, timezone, default])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. String или (U)Int* или Float*
• scale — Размер тика (точность): 10^-точность секунд. UInt8
• timezone — Необязательно. Часовой пояс. String
• default — Необязательно. Значение по умолчанию, которое возвращается, если разбор неуспешен. DateTime64

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

Значение типа DateTime64 в случае успешного выполнения; в противном случае возвращается значение по умолчанию, если оно передано, или 1970-01-01 00:00:00.000, если нет. DateTime64

Примеры

Успешное преобразование

SELECT toDateTime64OrDefault('1976-10-18 00:00:00.30', 3)

1976-10-18 00:00:00.300

Ошибка преобразования

SELECT toDateTime64OrDefault('1976-10-18 00:00:00 30', 3, 'UTC', toDateTime64('2001-01-01 00:00:00.00',3))

2001-01-01 00:00:00.000

Добавленный в: v20.1.0

Преобразует входное значение в значение типа DateTime64, но возвращает NULL, если передан некорректный аргумент. То же, что и toDateTime64, но возвращает NULL, если передан некорректный аргумент. Целочисленный аргумент интерпретируется как Unix-временная метка в целых секундах и возвращает NULL, если выходит за пределы диапазона типа DateTime64.

Синтаксис

toDateTime64OrNull(x[, precision[, timezone]])

Аргументы

• x — строковое представление даты и времени с субсекундной точностью или целочисленная Unix-временная метка. String или (U)Int8/16/32/64
• precision — необязательно. Субсекундная точность возвращаемого значения. UInt8
• timezone — необязательно. Часовой пояс возвращаемого значения. String

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

Возвращает значение DateTime64 в случае успеха, иначе — NULL. DateTime64 или NULL

Примеры

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

SELECT toDateTime64OrNull('2025-12-30 13:44:17.123'), toDateTime64OrNull('invalid')

┌─toDateTime64OrNull('2025-12-30 13:44:17.123')─┬─toDateTime64OrNull('invalid')─┐
│                       2025-12-30 13:44:17.123 │                          ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴───────────────────────────────┘

Добавленный в: v20.1.0

Преобразует входное значение в значение типа DateTime64, но при получении некорректного аргумента возвращает нижнюю границу DateTime64. То же, что и toDateTime64, но при получении некорректного аргумента возвращает нижнюю границу DateTime64.

См. также:

• toDateTime64.
• toDateTime64OrNull.
• toDateTime64OrDefault.

Синтаксис

toDateTime64OrZero(x)

Аргументы

• x — Строковое представление даты и времени с субсекундной точностью. String

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

Если преобразование успешно, возвращает значение DateTime64, в противном случае — нижнюю границу типа DateTime64 (1970-01-01 00:00:00.000). DateTime64

Примеры

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

SELECT toDateTime64OrZero('2025-12-30 13:44:17.123'), toDateTime64OrZero('invalid')

┌─toDateTime64OrZero('2025-12-30 13:44:17.123')─┬─toDateTime64OrZero('invalid')─┐
│                       2025-12-30 13:44:17.123 │       1970-01-01 00:00:00.000 │
└───────────────────────────────────────────────┴───────────────────────────────┘

Добавленный в: v21.11.0

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

Синтаксис

toDateTimeOrDefault(expr[, timezone, default])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. String или (U)Int*, или Float*
• timezone — Необязательно. Часовой пояс. String
• default — Необязательно. Значение по умолчанию, которое возвращается, если разбор завершился неуспешно. DateTime

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

Значение типа DateTime в случае успешного выполнения; в противном случае возвращается значение по умолчанию, если оно передано, или 1970-01-01 00:00:00, если нет. DateTime

Примеры

Успешное преобразование

SELECT toDateTimeOrDefault('2022-12-30 13:44:17')

2022-12-30 13:44:17

Ошибка преобразования

SELECT toDateTimeOrDefault('', 'UTC', CAST('2023-01-01', 'DateTime(\'UTC\')'))

2023-01-01 00:00:00

Добавленный в: v1.1.0

Преобразует входное значение в значение типа DateTime, но возвращает NULL, если получает некорректный аргумент. То же, что и toDateTime, но возвращает NULL, если получает некорректный аргумент. Целочисленный аргумент интерпретируется как Unix-временная метка и возвращает NULL, если выходит за пределы диапазона значений типа DateTime.

Синтаксис

toDateTimeOrNull(x[, timezone])

Аргументы

• x — Строковое представление даты и времени или целочисленная Unix-временная метка. String или (U)Int8/16/32/64
• timezone — Необязательно. Часовой пояс возвращаемого значения. String

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

Возвращает значение DateTime в случае успеха, в противном случае — NULL. DateTime или NULL

Примеры

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

SELECT toDateTimeOrNull('2025-12-30 13:44:17'), toDateTimeOrNull('invalid')

┌─toDateTimeOrNull('2025-12-30 13:44:17')─┬─toDateTimeOrNull('invalid')─┐
│                     2025-12-30 13:44:17 │                        ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘

Целочисленный аргумент с указанием часового пояса

SELECT toDateTimeOrNull(1583851242, 'Asia/Shanghai'), toDateTimeOrNull(4294967296)

┌─toDateTimeOrNull(1583851242, 'Asia/Shanghai')─┬─toDateTimeOrNull(4294967296)─┐
│                           2020-03-10 22:40:42 │                         ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴──────────────────────────────┘

Добавленный в: v1.1.0

Преобразует входное значение в значение типа DateTime, но при получении некорректного аргумента возвращает нижнюю границу DateTime. То же, что и toDateTime, но при получении некорректного аргумента возвращает нижнюю границу DateTime.

Синтаксис

toDateTimeOrZero(x)

Аргументы

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

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

Возвращает значение DateTime в случае успешного выполнения, в противном случае — нижнюю границу DateTime (1970-01-01 00:00:00). DateTime

Примеры

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

SELECT toDateTimeOrZero('2025-12-30 13:44:17'), toDateTimeOrZero('invalid')

┌─toDateTimeOrZero('2025-12-30 13:44:17')─┬─toDateTimeOrZero('invalid')─┐
│                     2025-12-30 13:44:17 │         1970-01-01 00:00:00 │
└─────────────────────────────────────────┴─────────────────────────────┘

Добавленный в: v18.12.0

Преобразует входное значение в значение типа Decimal(38, S) с масштабом S. Генерирует исключение в случае ошибки.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы:

• Значения Float* NaN и Inf или их строковые представления (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений, например SELECT toDecimal128('0xc0fe', 1);.

Синтаксис

toDecimal128(expr, S)

Аргументы

• expr — выражение, возвращающее число или строковое представление числа. Expression
• S — параметр scale в диапазоне от 0 до 38, задающий, сколько цифр может быть в дробной части числа. UInt8

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

Возвращает значение типа Decimal(38, S) Decimal128(S)

Примеры

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

SELECT
    toDecimal128(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal128(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal128('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(38, 1)
b:      99.67
type_b: Decimal(38, 2)
c:      99.67
type_c: Decimal(38, 3)

Добавленный в: v21.11.0

Подобно toDecimal128, эта функция преобразует входное значение в значение типа Decimal(38, S), но в случае ошибки возвращает значение по умолчанию.

Синтаксис

toDecimal128OrDefault(expr, S[, default])

Аргументы

• expr — Строковое представление числа. String
• S — Параметр scale в диапазоне от 0 до 38, который указывает, сколько цифр может содержать дробная часть числа. UInt8
• default — Необязательно. Значение по умолчанию, возвращаемое, если преобразование в тип Decimal128(S) завершается неуспешно. Decimal128(S)

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

Значение типа Decimal(38, S) в случае успешного преобразования; в противном случае возвращается переданное значение по умолчанию или 0, если оно не задано. Decimal128(S)

Примеры

Успешное преобразование

SELECT toDecimal128OrDefault(toString(1/42), 18)

0.023809523809523808

Ошибка преобразования

SELECT toDecimal128OrDefault('Inf', 0, CAST('-1', 'Decimal128(0)'))

-1

Добавленный в: v20.1.0

Преобразует входное значение в значение типа Decimal(38, S), но в случае ошибки возвращает NULL. Аналогично toDecimal128, но при ошибках преобразования возвращает NULL вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращают NULL):

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений.
• Значения, выходящие за пределы Decimal128: (-1*10^(38 - S), 1*10^(38 - S)).

См. также:

• toDecimal128.
• toDecimal128OrZero.
• toDecimal128OrDefault.

Синтаксис

toDecimal128OrNull(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Expression
• S — Параметр scale в диапазоне от 0 до 38, задающий, сколько цифр может содержать дробная часть числа. UInt8

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

Возвращает значение типа Decimal(38, S) в случае успеха, иначе — NULL. Decimal128(S) или NULL

Примеры

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

SELECT toDecimal128OrNull('42.7', 2), toDecimal128OrNull('invalid', 2)

┌─toDecimal128OrNull('42.7', 2)─┬─toDecimal128OrNull('invalid', 2)─┐
│                          42.7 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

Добавленный в: v20.1.0

Преобразует входное значение в значение типа Decimal(38, S), но в случае ошибки возвращает 0. Аналогично toDecimal128, но при ошибках преобразования возвращает 0 вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращается 0):

• Значения Float* NaN и Inf или их строковые представления (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений.

Синтаксис

toDecimal128OrZero(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Expression
• S — параметр scale в диапазоне от 0 до 38, который задаёт, сколько цифр может быть в дробной части числа. UInt8

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

При успешном выполнении возвращает значение Decimal(38, S), в противном случае — 0. Decimal128(S)

Примеры

Базовое использование

SELECT toDecimal128OrZero('42.7', 2), toDecimal128OrZero('invalid', 2)

┌─toDecimal128OrZero('42.7', 2)─┬─toDecimal128OrZero('invalid', 2)─┐
│                          42.7 │                                0 │
└───────────────────────────────┴──────────────────────────────────┘

Добавленный в: v20.8.0

Преобразует входное значение в значение типа Decimal(76, S) с масштабом S. В случае ошибки генерирует исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы:

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений, например SELECT toDecimal256('0xc0fe', 1);.

Синтаксис

toDecimal256(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Expression
• S — параметр scale от 0 до 76, задающий, сколько знаков может быть в дробной части числа. UInt8

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

Возвращает значение типа Decimal(76, S). Decimal256(S)

Примеры

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

SELECT
    toDecimal256(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal256(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal256('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(76, 1)
b:      99.67
type_b: Decimal(76, 2)
c:      99.67
type_c: Decimal(76, 3)

Добавленный в: v21.11.0

Как и toDecimal256, эта функция преобразует входное значение в тип Decimal(76, S), но в случае ошибки возвращает значение по умолчанию.

Синтаксис

toDecimal256OrDefault(expr, S[, default])

Аргументы

• expr — Строковое представление числа. String
• S — Параметр scale в диапазоне от 0 до 76, задающий, сколько цифр может быть в дробной части числа. UInt8
• default — Необязательно. Значение по умолчанию, которое возвращается, если разбор в тип Decimal256(S) завершается неуспешно. Decimal256(S)

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

Значение типа Decimal(76, S) в случае успешного выполнения; в противном случае возвращается значение по умолчанию, если оно передано, или 0, если нет. Decimal256(S)

Примеры

Успешное преобразование

SELECT toDecimal256OrDefault(toString(1/42), 76)

0.023809523809523808

Ошибка преобразования

SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))

-1

Добавленный в: v20.8.0

Преобразует входное значение в значение типа Decimal(76, S), но в случае ошибки возвращает NULL. Аналогично toDecimal256, но при ошибках преобразования возвращает NULL вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращается NULL):

• Значения Float* NaN и Inf, а также их строковые представления (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений.
• Значения, выходящие за пределы Decimal256: (-1 * 10^(76 - S), 1 * 10^(76 - S)).

См. также:

• toDecimal256.
• toDecimal256OrZero.
• toDecimal256OrDefault.

Синтаксис

toDecimal256OrNull(expr, S)

Аргументы

• expr — выражение, возвращающее число или строковое представление числа. Expression
• S — параметр scale в диапазоне от 0 до 76, задающий, сколько цифр может быть в дробной части числа. UInt8

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

В случае успеха возвращает значение Decimal(76, S), в противном случае — NULL. Decimal256(S) или NULL

Примеры

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

SELECT toDecimal256OrNull('42.7', 2), toDecimal256OrNull('invalid', 2)

┌─toDecimal256OrNull('42.7', 2)─┬─toDecimal256OrNull('invalid', 2)─┐
│                          42.7 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

Добавленный в: v20.8.0

Преобразует входное значение в значение типа Decimal(76, S), но в случае ошибки возвращает 0. Аналогична toDecimal256, но при ошибках преобразования возвращает 0 вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращается 0):

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений.

См. также:

• toDecimal256.
• toDecimal256OrNull.
• toDecimal256OrDefault.

Синтаксис

toDecimal256OrZero(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Expression
• S — Параметр scale в диапазоне от 0 до 76, задающий количество цифр в дробной части числа. UInt8

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

Возвращает значение Decimal(76, S) в случае успеха, иначе 0. Decimal256(S)

Примеры

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

SELECT toDecimal256OrZero('42.7', 2), toDecimal256OrZero('invalid', 2)

┌─toDecimal256OrZero('42.7', 2)─┬─toDecimal256OrZero('invalid', 2)─┐
│                          42.7 │                                0 │
└───────────────────────────────┴──────────────────────────────────┘

Добавленный в: v18.12.0

Преобразует входное значение в значение типа Decimal(9, S) с масштабом S. В случае ошибки генерирует исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы:

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений, например SELECT toDecimal32('0xc0fe', 1);.

Синтаксис

toDecimal32(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Expression
• S — Параметр scale в диапазоне от 0 до 9, указывающий, сколько цифр может быть в дробной части числа. UInt8

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

Возвращает значение типа Decimal(9, S) Decimal32(S)

Примеры

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

SELECT
    toDecimal32(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal32(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal32('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2
type_a: Decimal(9, 1)
b:      4.2
type_b: Decimal(9, 2)
c:      4.2
type_c: Decimal(9, 3)

Добавленный в: v21.11.0

Как и toDecimal32, эта функция преобразует входное значение в значение типа Decimal(9, S), но в случае ошибки возвращает значение по умолчанию.

Синтаксис

toDecimal32OrDefault(expr, S[, default])

Аргументы

• expr — Строковое представление числа. String
• S — Параметр масштаба от 0 до 9, задающий, сколько цифр может быть в дробной части числа. UInt8
• default — Необязательно. Значение по умолчанию, которое возвращается, если не удалось выполнить разбор в тип Decimal32(S). Decimal32(S)

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

Значение типа Decimal(9, S) в случае успешного выполнения; в противном случае возвращается переданное значение по умолчанию или 0, если оно не задано. Decimal32(S)

Примеры

Успешное преобразование

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

Ошибка преобразования

SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))

-1

Добавленный в: v20.1.0

Преобразует входное значение в значение типа Decimal(9, S), но в случае ошибки возвращает NULL. Аналогична toDecimal32, но при ошибках преобразования возвращает NULL вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращает NULL):

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений.
• Значения, выходящие за границы Decimal32:(-1*10^(9 - S), 1*10^(9 - S)).

См. также:

• toDecimal32.
• toDecimal32OrZero.
• toDecimal32OrDefault.

Синтаксис

toDecimal32OrNull(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Выражение
• S — параметр масштаба в диапазоне от 0 до 9, задающий, сколько цифр может быть в дробной части числа. UInt8

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

В случае успеха возвращается значение Decimal(9, S), в противном случае — NULL. Decimal32(S) или NULL

Примеры

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

SELECT toDecimal32OrNull('42.7', 2), toDecimal32OrNull('invalid', 2)

┌─toDecimal32OrNull('42.7', 2)─┬─toDecimal32OrNull('invalid', 2)─┐
│                         42.7 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

Добавленный в: v20.1.0

Преобразует входное значение в значение типа Decimal(9, S), но в случае ошибки возвращает 0. Аналогично toDecimal32, но при ошибках преобразования возвращает 0 вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращается 0):

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимые).
• Строковые представления двоичных и шестнадцатеричных значений.

Синтаксис

toDecimal32OrZero(expr, S)

Аргументы

• expr — Выражение, возвращающее число или его строковое представление. Выражение
• S — параметр масштаба со значением от 0 до 9, задающий, сколько цифр может быть в дробной части числа. UInt8

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

В случае успеха возвращает значение Decimal(9, S), в противном случае — 0. Decimal32(S)

Примеры

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

SELECT toDecimal32OrZero('42.7', 2), toDecimal32OrZero('invalid', 2)

┌─toDecimal32OrZero('42.7', 2)─┬─toDecimal32OrZero('invalid', 2)─┐
│                         42.7 │                               0 │
└──────────────────────────────┴─────────────────────────────────┘

Добавленный в: v18.12.0

Преобразует входное значение в значение типа Decimal(18, S) с масштабом S. Генерирует исключение в случае ошибки.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы:

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления бинарных и шестнадцатеричных значений, например SELECT toDecimal64('0xc0fe', 1);.

Синтаксис

toDecimal64(expr, S)

Аргументы

• expr — Выражение, возвращающее число или его строковое представление. Выражение
• S — параметр масштаба от 0 до 18, указывающий, сколько цифр может быть в дробной части числа. UInt8

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

Возвращает десятичное значение. Decimal(18, S)

Примеры

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

SELECT
    toDecimal64(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal64(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal64('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2
type_a: Decimal(18, 1)
b:      4.2
type_b: Decimal(18, 2)
c:      4.2
type_c: Decimal(18, 3)

Добавленный в: v21.11.0

Как и toDecimal64, эта функция преобразует входное значение в тип Decimal(18, S), но в случае ошибки возвращает значение по умолчанию.

Синтаксис

toDecimal64OrDefault(expr, S[, default])

Аргументы

• expr — Строковое представление числа. String
• S — Параметр масштаба в диапазоне от 0 до 18, задающий, сколько цифр может содержать дробная часть числа. UInt8
• default — Необязательно. Значение по умолчанию, которое возвращается, если преобразование в тип Decimal64(S) не удалось. Decimal64(S)

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

Значение типа Decimal(18, S) в случае успешного преобразования; в противном случае возвращается значение по умолчанию, если оно было передано, или 0, если нет. Decimal64(S)

Примеры

Успешное преобразование

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

Не удалось преобразовать

SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))

-1

Добавленный в: v20.1.0

Преобразует входное значение в значение типа Decimal(18, S), но в случае ошибки возвращает NULL. Аналогично toDecimal64, но при ошибках преобразования возвращает NULL вместо того, чтобы генерировать исключение.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращают NULL):

• Значения Float* NaN и Inf, а также их строковые представления (регистронезависимые).
• Строковые представления двоичных и шестнадцатеричных значений.
• Значения, выходящие за пределы Decimal64: (-1*10^(18 - S), 1*10^(18 - S)).

См. также:

• toDecimal64.
• toDecimal64OrZero.
• toDecimal64OrDefault.

Синтаксис

toDecimal64OrNull(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Выражение
• S — параметр масштаба в диапазоне от 0 до 18, задающий, сколько цифр может содержать дробная часть числа. UInt8

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

Возвращает значение Decimal(18, S) в случае успеха, иначе — NULL. Decimal64(S) или NULL

Примеры

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

SELECT toDecimal64OrNull('42.7', 2), toDecimal64OrNull('invalid', 2)

┌─toDecimal64OrNull('42.7', 2)─┬─toDecimal64OrNull('invalid', 2)─┐
│                         42.7 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

Добавленный в: v20.1.0

Преобразует входное значение в значение типа Decimal(18, S), но в случае ошибки возвращает 0. Аналогична toDecimal64, но при ошибках преобразования возвращает 0 вместо генерирования исключения.

Поддерживаемые аргументы:

• Значения или строковые представления типа (U)Int*.
• Значения или строковые представления типа Float*.

Неподдерживаемые аргументы (возвращается 0):

• Значения или строковые представления значений Float* NaN и Inf (регистронезависимо).
• Строковые представления двоичных и шестнадцатеричных значений.

См. также:

• toDecimal64.
• toDecimal64OrNull.
• toDecimal64OrDefault.

Синтаксис

toDecimal64OrZero(expr, S)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Выражение
• S — параметр масштаба в диапазоне от 0 до 18, определяющий, сколько цифр может быть в дробной части числа. UInt8

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

Возвращает значение Decimal(18, S) в случае успеха, иначе 0. Decimal64(S)

Примеры

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

SELECT toDecimal64OrZero('42.7', 2), toDecimal64OrZero('invalid', 2)

┌─toDecimal64OrZero('42.7', 2)─┬─toDecimal64OrZero('invalid', 2)─┐
│                         42.7 │                               0 │
└──────────────────────────────┴─────────────────────────────────┘

Добавленный в: v23.3.0

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

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

Синтаксис

toDecimalString(number, scale)

Аргументы

• number — Числовое значение, которое нужно преобразовать в строку. Может иметь любой числовой тип (Int, UInt, Float, Decimal). Int8 or Int16 or Int32 or Int64 or UInt8 or UInt16 or UInt32 or UInt64 or Float32 or Float64 or Decimal
• scale — Количество цифр для отображения в дробной части. При необходимости результат будет округлён. UInt8

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

Возвращает строковое представление числа с ровно указанным количеством цифр в дробной части. String

Примеры

Округление и форматирование числа

SELECT toDecimalString(2.1456, 2)

┌─toDecimalString(2.1456, 2)─┐
│ 2.15                       │
└────────────────────────────┘

Заполнить нулями

SELECT toDecimalString(5, 3)

┌─toDecimalString(5, 3)─┐
│ 5.000                 │
└───────────────────────┘

Разные числовые типы

SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
       toDecimalString(CAST(42.7 AS Float32), 4) AS float_val

┌─decimal_val─┬─float_val─┐
│ 123.46      │ 42.7000   │
└─────────────┴───────────┘

Добавленный в: v1.1.0

Преобразует аргумент String в тип FixedString(N) (строку фиксированной длины N).

Если строка содержит меньше байтов, чем N, справа она дополняется null-байтами. Если строка содержит больше байтов, чем N, генерируется исключение.

Синтаксис

toFixedString(s, N)

Аргументы

• s — Строка, которую нужно преобразовать. String
• N — Длина результирующей FixedString. const UInt*

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

Возвращает FixedString длиной N. FixedString(N)

Примеры

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

-- The padding is made of null bytes, so the result is shown with `hex`.
SELECT hex(toFixedString('foo', 8)) AS s;

┌─s────────────────┐
│ 666F6F0000000000 │
└──────────────────┘

Добавленный в: v1.1.0

Преобразует входное значение в значение типа Float32. Генерирует исключение в случае ошибки.

Поддерживаемые аргументы:

• Значения типа (U)Int*.
• Строковые представления (U)Int8/16/32/128/256.
• Значения типа Float*, включая NaN и Inf.
• Строковые представления Float*, включая NaN и Inf (регистронезависимые).

Неподдерживаемые аргументы:

• Строковые представления двоичных и шестнадцатеричных значений, например SELECT toFloat32('0xc0fe');.

См. также:

• toFloat32OrZero.
• toFloat32OrNull.
• toFloat32OrDefault.

Синтаксис

toFloat32(expr)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Выражение

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

Возвращает 32-битное значение с плавающей точкой. Float32

Примеры

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

SELECT
    toFloat32(42.7),
    toFloat32('42.7'),
    toFloat32('NaN')
FORMAT Vertical

Строка 1:
──────
toFloat32(42.7):   42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'):  nan

Добавленный в: v21.11.0

Как и toFloat32, эта функция преобразует входное значение в значение типа Float32, но в случае ошибки возвращает значение по умолчанию. Если значение default не указано, то в случае ошибки возвращается 0.

Синтаксис

toFloat32OrDefault(expr[, default])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. String или (U)Int* или Float*
• default — Необязательно. Значение по умолчанию, которое возвращается, если не удалось выполнить разбор. Float32

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

В случае успеха возвращает значение типа Float32, в противном случае — значение по умолчанию, если оно передано, или 0, если нет. Float32

Примеры

Успешное преобразование

SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))

8

Ошибка преобразования

SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))

0

Добавленный в: v1.1.0

Преобразует входное значение в значение типа Float32, но в случае ошибки возвращает NULL. Аналогично toFloat32, но при ошибках преобразования возвращает NULL вместо генерации исключения.

Поддерживаемые аргументы:

• Значения типа (U)Int*.
• Строковые представления (U)Int8/16/32/128/256.
• Значения типа Float*, включая NaN и Inf.
• Строковые представления Float*, включая NaN и Inf (регистронезависимо).

Неподдерживаемые аргументы (возвращают NULL):

• Строковые представления двоичных и шестнадцатеричных значений, например: SELECT toFloat32OrNull('0xc0fe');.
• Недопустимые строковые форматы.

См. также:

• toFloat32.
• toFloat32OrZero.
• toFloat32OrDefault.

Синтаксис

toFloat32OrNull(x)

Аргументы

• x — Строковое представление числа. String

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

Возвращает значение типа Float32 в случае успеха, в противном случае — NULL. Float32 или NULL

Примеры

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

SELECT
    toFloat32OrNull('42.7'),
    toFloat32OrNull('NaN'),
    toFloat32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  ᴺᵁᴸᴸ

Добавленный в: v1.1.0

Преобразует входное значение в тип Float32, но в случае ошибки возвращает 0. Аналогично toFloat32, но при ошибках преобразования возвращает 0 вместо генерации исключения.

См. также:

• toFloat32.
• toFloat32OrNull.
• toFloat32OrDefault.

Синтаксис

toFloat32OrZero(x)

Аргументы

• x — Строковое представление числа. String

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

Возвращает 32-битное значение Float32 в случае успеха, иначе — 0. Float32

Примеры

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

SELECT
    toFloat32OrZero('42.7'),
    toFloat32OrZero('abc')
FORMAT Vertical

Строка 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'):  0

Добавленный в: v1.1.0

Преобразует входное значение в значение типа Float64. Генерирует исключение в случае ошибки.

Поддерживаемые аргументы:

• Значения типа (U)Int*.
• Строковые представления значений типа (U)Int8/16/32/128/256.
• Значения типа Float*, включая NaN и Inf.
• Строковые представления значений типа Float*, включая NaN и Inf (регистронезависимо).

Неподдерживаемые аргументы:

• Строковые представления двоичных и шестнадцатеричных значений, например SELECT toFloat64('0xc0fe');.

См. также:

• toFloat64OrZero.
• toFloat64OrNull.
• toFloat64OrDefault.

Синтаксис

toFloat64(expr)

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. Expression

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

Возвращает 64-битное значение с плавающей точкой. Float64

Примеры

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

SELECT
    toFloat64(42.7),
    toFloat64('42.7'),
    toFloat64('NaN')
FORMAT Vertical

Строка 1:
──────
toFloat64(42.7):   42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'):  nan

Добавленный в: v21.11.0

Как и toFloat64, эта функция преобразует входное значение в значение типа Float64, но в случае ошибки возвращает значение по умолчанию. Если значение default не указано, то в случае ошибки возвращается 0.

Синтаксис

toFloat64OrDefault(expr[, default])

Аргументы

• expr — Выражение, возвращающее число или строковое представление числа. String или (U)Int* или Float*
• default — Необязательно. Значение по умолчанию, возвращаемое при неуспешном парсинге. Float64

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

При успешном выполнении возвращает значение типа Float64, в противном случае — значение по умолчанию, если оно передано, или 0, если нет. Float64

Примеры

Успешное преобразование

SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))

8

Преобразование не удалось

SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))

0