diff --git a/docs/en/sql-reference/functions/type-conversion-functions.md b/docs/en/sql-reference/functions/type-conversion-functions.md index 8544356f895..d8d13d81d97 100644 --- a/docs/en/sql-reference/functions/type-conversion-functions.md +++ b/docs/en/sql-reference/functions/type-conversion-functions.md @@ -385,8 +385,6 @@ reinterpretAsUUID(fixed_string) - `fixed_string` — Big-endian byte string. [FixedString](../../sql-reference/data-types/fixedstring.md#fixedstring). -## reinterpret(x, T) {#type_conversion_function-reinterpret} - **Returned value** - The UUID type value. [UUID](../../sql-reference/data-types/uuid.md#uuid-data-type). @@ -398,9 +396,7 @@ String to UUID. Query: ``` sql -SELECT reinterpret(toInt8(-1), 'UInt8') as int_to_uint, - reinterpret(toInt8(1), 'Float32') as int_to_float, - reinterpret('1', 'UInt32') as string_to_int; +SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f'))); ``` Result: @@ -431,15 +427,51 @@ Result: └─────────────────────┘ ``` +## reinterpret(x, T) {#type_conversion_function-reinterpret} + +Use the same source in-memory bytes sequence for `x` value and reinterpret it to destination type + +Query: +```sql +SELECT reinterpret(toInt8(-1), 'UInt8') as int_to_uint, + reinterpret(toInt8(1), 'Float32') as int_to_float, + reinterpret('1', 'UInt32') as string_to_int; +``` + +Result: + +``` +┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐ +│ 255 │ 1e-45 │ 49 │ +└─────────────┴──────────────┴───────────────┘ +``` + ## CAST(x, T) {#type_conversion_function-cast} -Converts input value `x` to the `T` data type. +Converts input value `x` to the `T` data type. Unlike to `reinterpret` function use external representation of `x` value. The syntax `CAST(x AS t)` is also supported. Note, that if value `x` does not fit the bounds of type T, the function overflows. For example, CAST(-1, 'UInt8') returns 255. -**Example** +**Examples** + +Query: + +```sql +SELECT + cast(toInt8(-1), 'UInt8') AS cast_int_to_uint, + cast(toInt8(1), 'Float32') AS cast_int_to_float, + cast('1', 'UInt32') AS cast_string_to_int +``` + +Result: + +``` +┌─cast_int_to_uint─┬─cast_int_to_float─┬─cast_string_to_int─┐ +│ 255 │ 1 │ 1 │ +└──────────────────┴───────────────────┴────────────────────┘ +``` Query: @@ -634,6 +666,7 @@ Result: ``` ## parseDateTimeBestEffort {#parsedatetimebesteffort} +## parseDateTime32BestEffort {#parsedatetime32besteffort} Converts a date and time in the [String](../../sql-reference/data-types/string.md) representation to [DateTime](../../sql-reference/data-types/datetime.md#data_type-datetime) data type. @@ -822,10 +855,12 @@ Result: ``` ## parseDateTimeBestEffortOrNull {#parsedatetimebesteffortornull} +## parseDateTime32BestEffortOrNull {#parsedatetime32besteffortornull} -Same as for [parseDateTimeBestEffort](#parsedatetimebesteffort) except that it returns null when it encounters a date format that cannot be processed. +Same as for [parseDateTimeBestEffort](#parsedatetimebesteffort) except that it returns `NULL` when it encounters a date format that cannot be processed. ## parseDateTimeBestEffortOrZero {#parsedatetimebesteffortorzero} +## parseDateTime32BestEffortOrZero {#parsedatetime32besteffortorzero} Same as for [parseDateTimeBestEffort](#parsedatetimebesteffort) except that it returns zero date or zero date time when it encounters a date format that cannot be processed. @@ -1001,6 +1036,57 @@ Result: └─────────────────────────────────┘ ``` +## parseDateTime64BestEffort {#parsedatetime64besteffort} + +Same as [parseDateTimeBestEffort](#parsedatetimebesteffort) function but also parse milliseconds and microseconds and return `DateTime64(3)` or `DateTime64(6)` data types. + +**Syntax** + +``` sql +parseDateTime64BestEffort(time_string [, precision [, time_zone]]) +``` + +**Parameters** + +- `time_string` — String containing a date or date with time to convert. [String](../../sql-reference/data-types/string.md). +- `precision` — `3` for milliseconds, `6` for microseconds. Default `3`. Optional [UInt8](../../sql-reference/data-types/int-uint.md). +- `time_zone` — [Timezone](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone). The function parses `time_string` according to the timezone. Optional. [String](../../sql-reference/data-types/string.md). + +**Examples** + +Query: + +```sql +SELECT parseDateTime64BestEffort('2021-01-01') AS a, toTypeName(a) AS t +UNION ALL +SELECT parseDateTime64BestEffort('2021-01-01 01:01:00.12346') AS a, toTypeName(a) AS t +UNION ALL +SELECT parseDateTime64BestEffort('2021-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t +UNION ALL +SELECT parseDateTime64BestEffort('2021-01-01 01:01:00.12346',3,'Europe/Moscow') AS a, toTypeName(a) AS t +FORMAT PrettyCompactMonoBlcok +``` + +Result: + +``` +┌──────────────────────────a─┬─t──────────────────────────────┐ +│ 2021-01-01 01:01:00.123000 │ DateTime64(3) │ +│ 2021-01-01 00:00:00.000000 │ DateTime64(3) │ +│ 2021-01-01 01:01:00.123460 │ DateTime64(6) │ +│ 2020-12-31 22:01:00.123000 │ DateTime64(3, 'Europe/Moscow') │ +└────────────────────────────┴────────────────────────────────┘ +``` + +## parseDateTime64BestEffortOrNull {#parsedatetime32besteffortornull} + +Same as for [parseDateTime64BestEffort](#parsedatetime64besteffort) except that it returns `NULL` when it encounters a date format that cannot be processed. + +## parseDateTime64BestEffortOrZero {#parsedatetime64besteffortorzero} + +Same as for [parseDateTime64BestEffort](#parsedatetimebesteffort) except that it returns zero date or zero date time when it encounters a date format that cannot be processed. + + ## toLowCardinality {#tolowcardinality} Converts input parameter to the [LowCardianlity](../../sql-reference/data-types/lowcardinality.md) version of same data type. @@ -1009,7 +1095,7 @@ To convert data from the `LowCardinality` data type use the [CAST](#type_convers **Syntax** -``` sql +```sql toLowCardinality(expr) ``` @@ -1027,7 +1113,7 @@ Type: `LowCardinality(expr_result_type)` Query: -``` sql +```sql SELECT toLowCardinality('1'); ``` @@ -1045,7 +1131,8 @@ Result: ## toUnixTimestamp64Nano {#tounixtimestamp64nano} -Converts a `DateTime64` to a `Int64` value with fixed sub-second precision. Input value is scaled up or down appropriately depending on it precision. Please note that output value is a timestamp in UTC, not in timezone of `DateTime64`. +Converts a `DateTime64` to a `Int64` value with fixed sub-second precision. +Input value is scaled up or down appropriately depending on it precision. Please note that output value is a timestamp in UTC, not in timezone of `DateTime64`. **Syntax** @@ -1078,6 +1165,8 @@ Result: └──────────────────────────────┘ ``` +Query: + ``` sql WITH toDateTime64('2019-09-16 19:20:12.345678910', 6) AS dt64 SELECT toUnixTimestamp64Nano(dt64); diff --git a/docs/ru/sql-reference/functions/type-conversion-functions.md b/docs/ru/sql-reference/functions/type-conversion-functions.md index 1bb7396ae3a..fc1dd15f8e3 100644 --- a/docs/ru/sql-reference/functions/type-conversion-functions.md +++ b/docs/ru/sql-reference/functions/type-conversion-functions.md @@ -423,15 +423,51 @@ SELECT uuid = uuid2; └─────────────────────┘ ``` +## reinterpret(x, T) {#type_conversion_function-reinterpret} + +Использует туже самую исходную последовательность байт в памяти для значения `x` и переинтерпретирует ее как конечный тип данных + +Запрос: +```sql +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 │ +└─────────────┴──────────────┴───────────────┘ +``` + ## CAST(x, T) {#type_conversion_function-cast} -Преобразует входное значение `x` в указанный тип данных `T`. +Преобразует входное значение `x` в указанный тип данных `T`. В отличии от функции `reinterpret` использует внешнее представление значения `x`. Поддерживается также синтаксис `CAST(x AS t)`. Обратите внимание, что если значение `x` не может быть преобразовано к типу `T`, возникает переполнение. Например, `CAST(-1, 'UInt8')` возвращает 255. -**Пример** +**Примеры** + +Запрос: + +```sql +SELECT + cast(toInt8(-1), 'UInt8') AS cast_int_to_uint, + cast(toInt8(1), 'Float32') AS cast_int_to_float, + cast('1', 'UInt32') AS cast_string_to_int +``` + +Результат: + +``` +┌─cast_int_to_uint─┬─cast_int_to_float─┬─cast_string_to_int─┐ +│ 255 │ 1 │ 1 │ +└──────────────────┴───────────────────┴────────────────────┘ +``` Запрос: @@ -511,7 +547,8 @@ SELECT cast(-1, 'UInt8') as uint8; ``` text ┌─uint8─┐ │ 255 │ -└───── +└───────┘ +``` Запрос: @@ -627,6 +664,7 @@ SELECT ``` ## parseDateTimeBestEffort {#parsedatetimebesteffort} +## parseDateTime32BestEffort {#parsedatetime32besteffort} Преобразует дату и время в [строковом](../../sql-reference/functions/type-conversion-functions.md) представлении к типу данных [DateTime](../../sql-reference/functions/type-conversion-functions.md#data_type-datetime). @@ -814,6 +852,16 @@ AS parseDateTimeBestEffortUS; └─────────────────────────——┘ ``` +## parseDateTimeBestEffortOrNull {#parsedatetimebesteffortornull} +## parseDateTime32BestEffortOrNull {#parsedatetime32besteffortornull} + +Работает также как [parseDateTimeBestEffort](#parsedatetimebesteffort), но возвращает `NULL` когда получает формат даты который не может быть обработан. + +## parseDateTimeBestEffortOrZero {#parsedatetimebesteffortorzero} +## parseDateTime32BestEffortOrZero {#parsedatetime32besteffortorzero} + +Работает также как [parseDateTimeBestEffort](#parsedatetimebesteffort), но возвращает нулевую дату или нулевую дату и время когда получает формат даты который не может быть обработан. + ## parseDateTimeBestEffortUSOrNull {#parsedatetimebesteffortusornull} Работает аналогично функции [parseDateTimeBestEffortUS](#parsedatetimebesteffortUS), но в отличие от нее возвращает `NULL`, если входная строка не может быть преобразована в тип данных [DateTime](../../sql-reference/data-types/datetime.md). @@ -986,9 +1034,100 @@ SELECT parseDateTimeBestEffortUSOrZero('02.2021') AS parseDateTimeBestEffortUSOr └─────────────────────────────────┘ ``` -## toUnixTimestamp64Milli -## toUnixTimestamp64Micro -## toUnixTimestamp64Nano +## parseDateTime64BestEffort {#parsedatetime64besteffort} + +Работает также как функция [parseDateTimeBestEffort](#parsedatetimebesteffort) но также понимамет милисекунды и микросекунды и возвращает `DateTime64(3)` или `DateTime64(6)` типы данных в зависимости от заданной точности. + +**Syntax** + +``` sql +parseDateTime64BestEffort(time_string [, precision [, time_zone]]) +``` + +**Parameters** + +- `time_string` — String containing a date or date with time to convert. [String](../../sql-reference/data-types/string.md). +- `precision` — `3` for milliseconds, `6` for microseconds. Default `3`. Optional [UInt8](../../sql-reference/data-types/int-uint.md). +- `time_zone` — [Timezone](../../operations/server-configuration-parameters/settings.md#server_configuration_parameters-timezone). The function parses `time_string` according to the timezone. Optional. [String](../../sql-reference/data-types/string.md). + +**Примеры** + +Запрос: + +```sql +SELECT parseDateTime64BestEffort('2021-01-01') AS a, toTypeName(a) AS t +UNION ALL +SELECT parseDateTime64BestEffort('2021-01-01 01:01:00.12346') AS a, toTypeName(a) AS t +UNION ALL +SELECT parseDateTime64BestEffort('2021-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t +UNION ALL +SELECT parseDateTime64BestEffort('2021-01-01 01:01:00.12346',3,'Europe/Moscow') AS a, toTypeName(a) AS t +FORMAT PrettyCompactMonoBlcok +``` + +Результат: + +``` +┌──────────────────────────a─┬─t──────────────────────────────┐ +│ 2021-01-01 01:01:00.123000 │ DateTime64(3) │ +│ 2021-01-01 00:00:00.000000 │ DateTime64(3) │ +│ 2021-01-01 01:01:00.123460 │ DateTime64(6) │ +│ 2020-12-31 22:01:00.123000 │ DateTime64(3, 'Europe/Moscow') │ +└────────────────────────────┴────────────────────────────────┘ +``` + +## parseDateTime64BestEffortOrNull {#parsedatetime32besteffortornull} + +Работает также как функция [parseDateTime64BestEffort](#parsedatetime64besteffort) но возвращает `NULL` когда встречает формат даты который не может обработать. + +## parseDateTime64BestEffortOrZero {#parsedatetime64besteffortorzero} + +Работает также как функция [parseDateTime64BestEffort](#parsedatetimebesteffort) но возвращает "нулевую" дату и время когда встречает формат даты который не может обработать. + + +## toLowCardinality {#tolowcardinality} + +Преобразует входные данные в версию [LowCardianlity](../data-types/lowcardinality.md) того же типа данных. + +Чтобы преобразовать данные из типа `LowCardinality`, используйте функцию [CAST](#type_conversion_function-cast). Например, `CAST(x as String)`. + +**Синтаксис** + +```sql +toLowCardinality(expr) +``` + +**Аргументы** + +- `expr` — [выражение](../syntax.md#syntax-expressions), которое в результате преобразуется в один из [поддерживаемых типов данных](../data-types/index.md#data_types). + +**Возвращаемое значение** + +- Результат преобразования `expr`. + +Тип: `LowCardinality(expr_result_type)` + +**Пример** + +Запрос: + +```sql +SELECT toLowCardinality('1'); +``` + +Результат: + +```text +┌─toLowCardinality('1')─┐ +│ 1 │ +└───────────────────────┘ +``` + +## toUnixTimestamp64Milli {#tounixtimestamp64milli} + +## toUnixTimestamp64Micro {#tounixtimestamp64micro} + +## toUnixTimestamp64Nano {#tounixtimestamp64nano} Преобразует значение `DateTime64` в значение `Int64` с фиксированной точностью менее одной секунды. Входное значение округляется соответствующим образом вверх или вниз в зависимости от его точности. Обратите внимание, что возвращаемое значение - это временная метка в UTC, а не в часовом поясе `DateTime64`. @@ -1039,9 +1178,11 @@ SELECT toUnixTimestamp64Nano(dt64); └─────────────────────────────┘ ``` -## fromUnixTimestamp64Milli -## fromUnixTimestamp64Micro -## fromUnixTimestamp64Nano +## fromUnixTimestamp64Milli {#fromunixtimestamp64milli} + +## fromUnixTimestamp64Micro {#fromunixtimestamp64micro} + +## fromUnixTimestamp64Nano {#fromunixtimestamp64nano} Преобразует значение `Int64` в значение `DateTime64` с фиксированной точностью менее одной секунды и дополнительным часовым поясом. Входное значение округляется соответствующим образом вверх или вниз в зависимости от его точности. Обратите внимание, что входное значение обрабатывается как метка времени UTC, а не метка времени в заданном (или неявном) часовом поясе. @@ -1077,45 +1218,6 @@ SELECT fromUnixTimestamp64Milli(i64, 'UTC'); └──────────────────────────────────────┘ ``` -## toLowCardinality {#tolowcardinality} - -Преобразует входные данные в версию [LowCardianlity](../data-types/lowcardinality.md) того же типа данных. - -Чтобы преобразовать данные из типа `LowCardinality`, используйте функцию [CAST](#type_conversion_function-cast). Например, `CAST(x as String)`. - -**Синтаксис** - -```sql -toLowCardinality(expr) -``` - -**Аргументы** - -- `expr` — [выражение](../syntax.md#syntax-expressions), которое в результате преобразуется в один из [поддерживаемых типов данных](../data-types/index.md#data_types). - - -**Возвращаемое значение** - -- Результат преобразования `expr`. - -Тип: `LowCardinality(expr_result_type)` - -**Пример** - -Запрос: - -```sql -SELECT toLowCardinality('1'); -``` - -Результат: - -```text -┌─toLowCardinality('1')─┐ -│ 1 │ -└───────────────────────┘ -``` - ## formatRow {#formatrow} Преобразует произвольные выражения в строку заданного формата.