Funções de conversão de tipos

O ClickHouse geralmente usa o mesmo comportamento dos programas em C++.

As funções to<type> e cast se comportam de maneira diferente em alguns casos, por exemplo com LowCardinality: cast remove a propriedade LowCardinality, enquanto as funções to<type> não. O mesmo ocorre com Nullable; esse comportamento não é compatível com o padrão SQL e pode ser alterado com a configuração cast_keep_nullable.

Exemplo:

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

┌

A família de funções toString permite converter entre números, strings (mas não strings fixas), datas e datas com hora. Todas essas funções aceitam um argumento.

• Ao converter para string ou de string, o valor é formatado ou interpretado usando as mesmas regras do formato TabSeparated (e de quase todos os outros formatos de texto). Se a string não puder ser interpretada, uma exceção é lançada e a solicitação é cancelada.
• Ao converter datas em números ou vice-versa, a data corresponde ao número de dias desde o início da epoch Unix.
• Ao converter datas com hora em números ou vice-versa, a data com hora corresponde ao número de segundos desde o início da epoch Unix.
• A função toString do argumento DateTime pode receber um segundo argumento String contendo o nome do fuso horário, por exemplo: Europe/Amsterdam. Nesse caso, a hora é formatada de acordo com o fuso horário especificado.

Os formatos de data e de data e hora das funções toDate/toDateTime são definidos da seguinte forma:

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

Como exceção, se a conversão for de tipos numéricos UInt32, Int32, UInt64 ou Int64 para Date, e se o número for maior ou igual a 65536, ele será interpretado como um timestamp Unix (e não como um número de dias) e será arredondado para a data. Isso permite dar suporte ao caso comum de escrever toDate(unix_timestamp), que, de outra forma, geraria um erro e exigiria a forma mais trabalhosa toDate(toDateTime(unix_timestamp)).

A conversão entre uma data e uma data com hora é feita da forma natural: adicionando uma hora nula ou removendo a hora.

A conversão entre tipos numéricos usa as mesmas regras das atribuições entre diferentes tipos numéricos em C++.

Exemplo

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 │
└─────────────────────┴───────────────────┴─────────────────────┘

Consulte também a função toUnixTimestamp.

Introduzido em: v1.1.0

Converte um valor para um tipo de dado especificado. Ao contrário da função reinterpret, CAST tenta gerar o mesmo valor no tipo de destino. Se isso não for possível, uma exceção é lançada.

Sintaxe

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

Argumentos

• x — Um valor de qualquer tipo. Any
• T — O tipo de dado de destino. String

Valor retornado

Retorna o valor convertido no tipo de dado de destino. Any

Exemplos

Uso básico

SELECT CAST(42, 'String')

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

Usando a sintaxe AS

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

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

Usando a sintaxe ::

SELECT '123'::UInt32

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

Introduzido em: v21.2.0

Converte o argumento para o tipo de dado Date. Este é um alias de compatibilidade com o MySQL para toDate. Ele se comporta da mesma forma que toDate.

Sintaxe

DATE(expr)

Argumentos

• expr — O valor a ser convertido. String ou UInt32 ou Date ou DateTime

Valor retornado

Retorna um valor do tipo Date. Date

Exemplos

Uso básico

SELECT DATE('2023-01-01')

2023-01-01

Introduzido em: v1.1.0

Converte um valor para um tipo de dado especificado. Diferentemente de CAST, accurateCast faz uma verificação de tipos mais rigorosa e lança uma exceção se a conversão resultar em perda de precisão dos dados ou se a conversão não for possível.

Esta função é mais segura do que o CAST padrão, pois evita perda de precisão e conversões inválidas.

Sintaxe

accurateCast(x, T)

Argumentos

• x — Um valor a ser convertido. Any
• T — O nome do tipo de dado de destino. String

Valor retornado

Retorna o valor convertido para o tipo de dado de destino. Any

Exemplos

Conversão bem-sucedida

SELECT accurateCast(42, 'UInt16')

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

De String para número

SELECT accurateCast('123.45', 'Float64')

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

Introduzido em: v21.1.0

Converte um valor para um tipo de dado especificado. Como accurateCast, mas retorna um valor padrão em vez de gerar uma exceção se a conversão não puder ser feita com precisão.

Se um valor padrão for fornecido como segundo argumento, ele deverá ser do tipo de destino. Se nenhum valor padrão for fornecido, será usado o valor padrão do tipo de destino.

Sintaxe

accurateCastOrDefault(x, T[, default_value])

Argumentos

• x — Um valor a ser convertido. Any
• T — O nome do tipo de dado de destino. const String
• default_value — Opcional. O valor padrão a ser retornado se a conversão falhar. Any

Valor retornado

Retorna o valor convertido para o tipo de dado de destino, ou o valor padrão caso a conversão não seja possível. Any

Exemplos

Conversão bem-sucedida

SELECT accurateCastOrDefault(42, 'String')

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

Falha de conversão com valor padrão explícito

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

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

Falha na conversão com valor padrão implícito

SELECT accurateCastOrDefault('abc', 'UInt32')

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

Introduzido em: v1.1.0

Converte um valor para um tipo de dado especificado. Como accurateCast, mas retorna NULL em vez de lançar uma exceção se a conversão não puder ser realizada com precisão.

Esta função combina a segurança de accurateCast com um tratamento de erros mais adequado.

Sintaxe

accurateCastOrNull(x, T)

Argumentos

• x — Um valor a ser convertido. Any
• T — O nome do tipo de dado de destino. String

Valor retornado

Retorna o valor convertido para o tipo de dado de destino, ou NULL se a conversão não for possível. Any

Exemplos

Conversão bem-sucedida

SELECT accurateCastOrNull(42, 'String')

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

Em caso de falha na conversão, retorna NULL

SELECT accurateCastOrNull('abc', 'UInt32')

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

Introduzido em: v20.7.0

Converte expressões arbitrárias em uma string usando o formato especificado.

Sintaxe

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

Argumentos

• format — Formato de texto. Por exemplo, CSV, TSV. String
• x, y, ... — Expressões. Any

Valor retornado

Uma string formatada. (para formatos de texto, geralmente termina com um caractere de nova linha). String

Exemplos

Uso básico

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

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

Com formato personalizado

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>                                     │
└──────────────────────────────────────────────┘

Introduzido em: v20.7.0

Igual a formatRow, mas remove o caractere de nova linha de cada linha.

Converte expressões arbitrárias em uma string usando o formato especificado, mas remove quaisquer caracteres de nova linha no final do resultado.

Sintaxe

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

Argumentos

• format — Formato de texto. Por exemplo, CSV, TSV. String
• x, y, ... — Expressões. Any

Valor retornado

Retorna uma string formatada sem quebras de linha. String

Exemplos

Uso básico

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

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

Introduzido em: v20.5.0

Converte um timestamp Unix em microssegundos em um valor DateTime64 com precisão de microssegundos.

O valor de entrada é tratado como um timestamp Unix com precisão de microssegundos (número de microssegundos desde 1970-01-01 00:00:00 UTC).

Sintaxe

fromUnixTimestamp64Micro(value[, timezone])

Argumentos

• value — timestamp Unix em microssegundos. Int64
• timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado

Retorna um valor DateTime64 com precisão de microssegundos. DateTime64(6)

Exemplos

Exemplo de uso

SELECT fromUnixTimestamp64Micro(1640995200123456)

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

Introduzido em: v20.5.0

Converte um timestamp Unix em milissegundos em um valor DateTime64 com precisão de milissegundos.

O valor de entrada é tratado como um timestamp Unix com precisão de milissegundos (número de milissegundos desde 1970-01-01 00:00:00 UTC).

Sintaxe

fromUnixTimestamp64Milli(value[, timezone])

Argumentos

• value — timestamp Unix em milissegundos. Int64
• timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado

Um valor DateTime64 com precisão de milissegundos. DateTime64(3)

Exemplos

Exemplo de uso

SELECT fromUnixTimestamp64Milli(1640995200123)

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

Introduzido em: v20.5.0

Converte um timestamp Unix em nanossegundos em um valor DateTime64 com precisão de nanossegundos.

O valor de entrada é tratado como um timestamp Unix com precisão de nanossegundos (número de nanossegundos desde 1970-01-01 00:00:00 UTC).

Sintaxe

fromUnixTimestamp64Nano(value[, timezone])

Argumentos

• value — Timestamp Unix em nanossegundos. Int64
• timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado

Retorna um valor DateTime64 com precisão de nanossegundos. DateTime64(9)

Exemplos

Exemplo de uso

SELECT fromUnixTimestamp64Nano(1640995200123456789)

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

Introduzido em: v24.12.0

Converte um timestamp Unix em segundos em um valor DateTime64 com precisão de segundo.

O valor de entrada é tratado como um timestamp Unix com precisão de segundo (número de segundos desde 1970-01-01 00:00:00 UTC).

Sintaxe

fromUnixTimestamp64Second(value[, timezone])

Argumentos

• value — timestamp Unix em segundos. Int64
• timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado

Retorna um valor DateTime64 com precisão de segundos. DateTime64(0)

Exemplos

Exemplo de uso

SELECT fromUnixTimestamp64Second(1640995200)

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

Introduzido em: v23.3.0

Interpreta uma string de data e hora de acordo com uma String de formato de data do MySQL.

Esta função é o inverso de formatDateTime. Ela interpreta um argumento String usando uma String de formato. Retorna um valor do tipo DateTime.

Sintaxe

parseDateTime(time_string, format[, timezone])

Aliases: TO_UNIXTIME

Argumentos

• time_string — String a ser convertida para DateTime. String
• format — String de formato que especifica como fazer o parse de time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna um DateTime obtido a partir da string de entrada, de acordo com a string de formato no estilo MySQL. DateTime

Exemplos

Exemplo de uso

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 │
└───────────────────────────────────────────────────────────┘

Introduzido em: v20.9.0

Converte uma representação textual de data e hora para o tipo de dado DateTime.

A função analisa ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, os formatos de data e hora do ClickHouse e alguns outros formatos.

Sintaxe

parseDateTime32BestEffort(time_string[, time_zone])

Argumentos

• time_string — String contendo uma data e hora a ser convertida. String
• time_zone — Opcional. Fuso horário segundo o qual time_string é interpretado String

Valor retornado

Retorna time_string como um DateTime. DateTime

Exemplos

Exemplo de uso

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

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

Com fuso horário

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

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

Unix timestamp

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

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

Introduzido em: v20.9.0

Igual a parseDateTime32BestEffort, exceto que retorna NULL quando encontra um formato de data que não pode ser processado.

Sintaxe

parseDateTime32BestEffortOrNull(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora a serem convertidas. String
• time_zone — Opcional. Fuso horário de acordo com o qual time_string é interpretado. String

Valor retornado

Retorna um objeto DateTime interpretado a partir da string, ou NULL se a interpretação falhar. DateTime

Exemplos

Exemplo de uso

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

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

Introduzido em: v20.9.0

Igual a parseDateTime32BestEffort, exceto que retorna uma data zero ou data e hora zero quando encontra um formato de data que não pode ser processado.

Sintaxe

parseDateTime32BestEffortOrZero(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora para converter. String
• time_zone — Opcional. Fuso horário com base no qual time_string é interpretado. String

Valor retornado

Retorna um objeto DateTime interpretado da string ou a data zero (1970-01-01 00:00:00) se a interpretação falhar. DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────┴─────────────────────┘

Introduzido em: v24.11.0

Interpreta uma string de data e hora com precisão de subsegundos de acordo com uma string de formato de data do MySQL.

Esta função é o inverso de formatDateTime para DateTime64. Ela interpreta um argumento String usando uma string de formato. Retorna um tipo DateTime64, que pode representar datas de 0000 a 9999 com precisão de subsegundos (precisões altas cobrem um intervalo mais estreito porque o valor é armazenado em um número Int64 de ticks: a precisão 8 alcança cerca de 4892 e a precisão 9 abrange de 1677 a 2262).

Sintaxe

parseDateTime64(time_string, format[, timezone])

Argumentos

• time_string — String a ser convertida em DateTime64. String
• format — String de formato que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna um DateTime64 convertido da string de entrada de acordo com a string de formato no estilo MySQL. DateTime64

Exemplos

Exemplo de uso

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 │
└────────────────────────────────────────────────────────────────────┘

Introduzido em: v20.1.0

Igual à função parseDateTimeBestEffort, mas também processa milissegundos e microssegundos e retorna o tipo de dado DateTime64.

Sintaxe

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

Argumentos

• time_string — String que contém uma data ou data com hora a ser convertida. String
• precision — Opcional. Precisão requerida. 3 para milissegundos, 6 para microssegundos. Padrão: 3. UInt8
• time_zone — Opcional. Fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna time_string convertido para o tipo de dado DateTime64. DateTime64

Exemplos

Exemplo de uso

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') │
└────────────────────────────┴────────────────────────────────┘

Introduzido em: v20.1.0

Igual a parseDateTime64BestEffort, exceto que retorna NULL quando encontra um formato de data que não pode ser processado.

Sintaxe

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

Argumentos

• time_string — String contendo uma data ou uma data e hora a ser convertida. String
• precision — Opcional. Precisão necessária. 3 para milissegundos, 6 para microssegundos. Padrão: 3. UInt8
• time_zone — Opcional. Fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna time_string convertido para DateTime64, ou NULL se a entrada não puder ser interpretada. DateTime64 ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v20.1.0

Igual a parseDateTime64BestEffort, exceto pelo fato de retornar data zero ou data e hora zero quando encontra um formato de data que não pode ser processado.

Sintaxe

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

Argumentos

• time_string — String contendo uma data ou data e hora para converter. String
• precision — Opcional. Precisão necessária. 3 para milissegundos, 6 para microssegundos. Padrão: 3. UInt8
• time_zone — Opcional. Fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna time_string convertido para DateTime64, ou data/data e hora zero (1970-01-01 00:00:00.000) se a entrada não puder ser interpretada. DateTime64

Exemplos

Exemplo de uso

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 │
└─────────────────────────┴─────────────────────────┘

Introduzido em: v22.8.0

Igual a parseDateTime64BestEffort, exceto pelo fato de que esta função prioriza o formato de data dos EUA (MM/DD/YYYY etc.) em caso de ambiguidade.

Sintaxe

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

Argumentos

• time_string — String contendo uma data ou data e hora para converter. String
• precision — Opcional. Precisão necessária. 3 para milissegundos, 6 para microssegundos. Padrão: 3. UInt8
• time_zone — Opcional. Fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna time_string convertido para DateTime64, usando a preferência de formato de data dos EUA em casos ambíguos. DateTime64

Exemplos

Exemplo de uso

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 │
└─────────────────────────┴─────────────────────────┘

Introduzido em: v22.8.0

Igual a parseDateTime64BestEffort, exceto que esta função dá preferência ao formato de data dos EUA (MM/DD/YYYY etc.) em caso de ambiguidade e retorna NULL ao encontrar um formato de data que não pode ser processado.

Sintaxe

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

Argumentos

• time_string — String que contém uma data ou uma data com hora a ser convertida. String
• precision — Opcional. Precisão desejada. 3 para milissegundos, 6 para microssegundos. Padrão: 3. UInt8
• time_zone — Opcional. Fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna time_string convertido para DateTime64 seguindo a preferência de formato dos EUA, ou NULL se a entrada não puder ser interpretada. DateTime64 ou NULL

Exemplos

Exemplo de uso

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 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

Introduzido em: v22.8.0

Igual a parseDateTime64BestEffort, exceto que esta função prioriza o formato de data dos EUA (MM/DD/YYYY etc.) em caso de ambiguidade e retorna data zero ou data e hora zero quando encontra um formato de data que não pode ser processado.

Sintaxe

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

Argumentos

• time_string — String que contém uma data ou uma data com hora para conversão. String
• precision — Opcional. Precisão necessária. 3 para milissegundos, 6 para microssegundos. Padrão: 3. UInt8
• time_zone — Opcional. Fuso horário. A função analisa time_string de acordo com o fuso horário. String

Valor retornado

Retorna time_string convertido para DateTime64 usando a preferência de formato dos EUA, ou data/data e hora zero (1970-01-01 00:00:00.000) se a entrada não puder ser analisada. DateTime64

Exemplos

Exemplo de uso

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 │
└─────────────────────────┴─────────────────────────┘

Introduzido em: v24.10.0

Converte uma string de data e hora com precisão de frações de segundo de acordo com uma string de formato de data Joda.

Esta função é o inverso de formatDateTimeInJodaSyntax para DateTime64. Ela converte um argumento String usando uma String de formato no estilo Joda. Retorna um tipo DateTime64, que pode representar datas de 0000 a 9999 com precisão de frações de segundo (precisões mais altas cobrem um intervalo mais estreito porque o valor é armazenado em um número Int64 de ticks: a precisão 8 alcança aproximadamente 4892 e a precisão 9 abrange de 1677 a 2262).

Consulte a documentação do Joda Time para os padrões de formato.

Sintaxe

parseDateTime64InJodaSyntax(time_string, format[, timezone])

Argumentos

• time_string — String a ser analisada em DateTime64. String
• format — String de formato na sintaxe Joda que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna um DateTime64 obtido da string de entrada de acordo com a string de formato no estilo Joda. DateTime64

Exemplos

Exemplo de uso

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 │
└───────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v24.10.0

Igual a parseDateTime64InJodaSyntax, mas retorna NULL quando encontra um formato de data não analisável.

Sintaxe

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

Argumentos

• time_string — String a ser analisada como DateTime64. String
• format — String de formato na sintaxe Joda que especifica como analisar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime64 convertido a partir da string de entrada, ou NULL se a análise falhar. Nullable(DateTime64)

Exemplos

Exemplo de uso

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 │
└─────────────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v24.10.0

Igual a parseDateTime64InJodaSyntax, mas retorna a data zero quando encontra um formato de data não analisável.

Sintaxe

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

Argumentos

• time_string — String a ser analisada em DateTime64. String
• format — String de formato na sintaxe Joda que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna um DateTime64 convertido da string de entrada, ou um DateTime64 zero se a interpretação falhar. DateTime64

Exemplos

Exemplo de uso

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 │
└─────────────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v24.11.0

Assim como parseDateTime64, mas retorna NULL quando encontra um formato de data não analisável.

Sintaxe

parseDateTime64OrNull(time_string, format[, timezone])

Argumentos

• time_string — String a ser analisada em DateTime64. String
• format — String de formato que especifica como converter time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime64 convertido da string de entrada, ou NULL se a conversão falhar. Nullable(DateTime64)

Exemplos

Exemplo de uso

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 │
└──────────────────────────────────────────────────────────────────────────┘

Introduzido em: v24.11.0

Igual a parseDateTime64, mas retorna uma data zero quando encontra um formato de data não analisável.

Sintaxe

parseDateTime64OrZero(time_string, format[, timezone])

Argumentos

• time_string — String a ser analisada em DateTime64. String
• format — String de formato que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime64 convertido da string de entrada ou DateTime64 zero se a conversão falhar. DateTime64

Exemplos

Exemplo de uso

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 │
└──────────────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Converte uma data e hora em representação String para o tipo de dado DateTime. A função interpreta os formatos ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, os formatos de data e hora do ClickHouse e alguns outros formatos.

Formatos não padrão suportados:

• Uma string contendo um timestamp Unix de 9..10 dígitos.
• Uma string com um componente de data e hora: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss, etc.
• Uma string com uma data, mas sem componente de hora: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY etc.
• Uma string com dia e hora: DD, DD hh, DD hh:mm. Nesse caso, MM é substituído por 01.
• Uma string que inclui a data e hora junto com informações de deslocamento de fuso horário: YYYY-MM-DD hh:mm:ss ±h:mm, etc.
• Um timestamp de syslog: Mmm dd hh:mm:ss. Por exemplo, Jun 9 14:20:32.

Para todos os formatos com separador, a função interpreta nomes de meses expressos pelo nome completo ou pelas três primeiras letras do nome do mês. Se o ano não for especificado, considera-se que ele é igual ao ano atual.

Sintaxe

parseDateTimeBestEffort(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora a serem convertidas. String
• time_zone — Opcional. Fuso horário segundo o qual time_string é analisado. String

Valor retornado

Retorna time_string como um DateTime. DateTime

Exemplos

Exemplo de uso

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

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

Com fuso horário

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

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

timestamp Unix

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

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

Introduzido em: v1.1.0

Igual a parseDateTimeBestEffort, exceto que retorna NULL quando encontra um formato de data que não pode ser processado. A função analisa ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, os formatos de data e hora do ClickHouse e alguns outros formatos.

Formatos não padrão compatíveis:

• Uma string contendo um timestamp Unix de 9..10 dígitos.
• Uma string com componentes de data e hora: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss etc.
• Uma string com uma data, mas sem componente de hora: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY etc.
• Uma string com dia e hora: DD, DD hh, DD hh:mm. Nesse caso, MM é substituído por 01.
• Uma string que inclui data e hora junto com informações de deslocamento de fuso horário: YYYY-MM-DD hh:mm:ss ±h:mm etc.
• Um timestamp de syslog: Mmm dd hh:mm:ss. Por exemplo, Jun 9 14:20:32.

Em todos os formatos com separador, a função analisa nomes de meses escritos por extenso ou pelas três primeiras letras do nome do mês. Se o ano não for especificado, ele será considerado igual ao ano atual.

Sintaxe

parseDateTimeBestEffortOrNull(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora a ser convertida. String
• time_zone — Opcional. Fuso horário segundo o qual time_string é analisado. String

Valor retornado

Retorna time_string como DateTime, ou NULL se a entrada não puder ser analisada. DateTime ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Igual a parseDateTimeBestEffort, exceto pelo fato de retornar uma data zero ou data e hora zero quando encontra um formato de data que não pode ser processado. A função analisa ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, os formatos de data e hora do ClickHouse e alguns outros formatos.

Formatos não padrão compatíveis:

• Uma string contendo um timestamp Unix de 9 a 10 dígitos.
• Uma string com um componente de data e hora: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss etc.
• Uma string com uma data, mas sem componente de hora: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY etc.
• Uma string com um dia e hora: DD, DD hh, DD hh:mm. Nesse caso, MM é substituído por 01.
• Uma string que inclui a data e a hora junto com informações de deslocamento de fuso horário: YYYY-MM-DD hh:mm:ss ±h:mm etc.
• Um timestamp de syslog: Mmm dd hh:mm:ss. Por exemplo, Jun 9 14:20:32.

Para todos os formatos com separador, a função analisa nomes de meses expressos pelo nome completo ou pelas três primeiras letras do nome do mês. Se o ano não for especificado, será considerado o ano atual.

Sintaxe

parseDateTimeBestEffortOrZero(time_string[, time_zone])

Argumentos

• time_string — String contendo uma data e hora a serem convertidas. String
• time_zone — Opcional. Fuso horário segundo o qual time_string é analisado. String

Valor retornado

Retorna time_string como um DateTime ou data/DateTime zero (1970-01-01 ou 1970-01-01 00:00:00) se a entrada não puder ser analisada. DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────┴─────────────────────┘

Introduzido em: v1.1.0

Esta função se comporta como parseDateTimeBestEffort para formatos de data ISO, por exemplo, YYYY-MM-DD hh:mm:ss, e outros formatos de data em que os componentes de mês e dia podem ser extraídos sem ambiguidade, por exemplo, YYYYMMDDhhmmss, YYYY-MM, DD hh ou YYYY-MM-DD hh:mm:ss ±h:mm. Se os componentes de mês e dia não puderem ser extraídos sem ambiguidade, por exemplo, MM/DD/YYYY, MM-DD-YYYY ou MM-DD-YY, ela prefere o formato de data dos EUA em vez de DD/MM/YYYY, DD-MM-YYYY ou DD-MM-YY. Como exceção ao caso anterior, se o mês for maior que 12 e menor ou igual a 31, esta função retorna ao comportamento de parseDateTimeBestEffort; por exemplo, 15/08/2020 é interpretado como 2020-08-15.

Sintaxe

parseDateTimeBestEffortUS(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora para converter. String
• time_zone — Opcional. Fuso horário de acordo com o qual time_string é interpretado. String

Valor retornado

Retorna time_string como um DateTime, usando a preferência do formato de data dos EUA em casos ambíguos. DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────┴──────────────────────┘

Introduzido em: v1.1.0

Igual à função parseDateTimeBestEffortUS, exceto que retorna NULL quando encontra um formato de data que não pode ser processado.

Esta função se comporta como parseDateTimeBestEffort para formatos de data ISO, mas, em casos ambíguos, prefere o formato de data dos EUA e retorna NULL em caso de erros de parsing.

Sintaxe

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora a serem convertidas. String
• time_zone — Opcional. Fuso horário segundo o qual time_string é interpretado. String

Valor retornado

Retorna time_string como um DateTime, com preferência pelo formato dos EUA, ou NULL se a entrada não puder ser interpretada. DateTime ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Igual à função parseDateTimeBestEffortUS, exceto que retorna data zero (1970-01-01) ou data zero com hora (1970-01-01 00:00:00) ao encontrar um formato de data que não pode ser processado.

Esta função se comporta como parseDateTimeBestEffort para formatos de data ISO, mas prefere o formato de data dos EUA em casos ambíguos, retornando zero em caso de erro de parsing.

Sintaxe

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

Argumentos

• time_string — String que contém uma data e hora para converter. String
• time_zone — Opcional. Fuso horário segundo o qual time_string é interpretado. String

Valor retornado

Retorna time_string como DateTime, usando a preferência de formato dos EUA, ou a data zero/data e hora zero (1970-01-01 ou 1970-01-01 00:00:00) se a entrada não puder ser interpretada. DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────┴─────────────────────┘

Introduzido em: v23.3.0

Faz o parse de uma string de data e hora de acordo com uma string de formato de data do Joda.

Esta função é o inverso de formatDateTimeInJodaSyntax. Ela faz o parse de um argumento String usando uma String de formato no estilo Joda. Retorna um tipo DateTime.

Consulte a documentação do Joda Time para os padrões de formato.

Sintaxe

parseDateTimeInJodaSyntax(time_string, format[, timezone])

Argumentos

• time_string — String a ser convertida em DateTime. String
• format — String de formato na sintaxe Joda que especifica como analisar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna um DateTime convertido da string de entrada de acordo com a string de formato no estilo Joda. DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────────────────────────────────────────────────────────┘

Introduzido em: v23.3.0

Igual a parseDateTimeInJodaSyntax, mas retorna NULL quando encontra um formato de data não analisável.

Sintaxe

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

Argumentos

• time_string — String a ser convertida em DateTime. String
• format — String de formato na sintaxe Joda que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime convertido da string de entrada, ou NULL se a conversão falhar. Nullable(DateTime)

Exemplos

Exemplo de uso

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 │
└───────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v23.3.0

Igual a parseDateTimeInJodaSyntax, mas retorna a data zero quando encontra um formato de data não analisável.

Sintaxe

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

Argumentos

• time_string — String a ser convertida em DateTime. String
• format — String de formato na sintaxe Joda que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime interpretado da string de entrada, ou um DateTime zero se a interpretação falhar. DateTime

Exemplos

Exemplo de uso

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 │
└───────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v23.3.0

Igual a parseDateTime, mas retorna NULL quando encontra um formato de data não analisável.

Sintaxe

parseDateTimeOrNull(time_string, format[, timezone])

Aliases: str_to_date

Argumentos

• time_string — String a ser convertida em DateTime. String
• format — String de formato que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime obtido da string de entrada, ou NULL se a análise falhar. Nullable(DateTime)

Exemplos

Exemplo de uso

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 │
└─────────────────────────────────────────────────────────────────┘

Introduzido em: v23.3.0

Igual a parseDateTime, mas retorna a data zero quando encontra um formato de data não analisável.

Sintaxe

parseDateTimeOrZero(time_string, format[, timezone])

Argumentos

• time_string — String a ser convertida em DateTime. String
• format — String de formato que especifica como interpretar time_string. String
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o DateTime convertido da string de entrada ou o DateTime zero se a interpretação falhar. DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Usa a mesma sequência de bytes na memória de origem para o valor x fornecido e a reinterpreta como o tipo de destino. Quando o tipo de destino é String, um Array de origem só tem suporte se o tipo de seus elementos for de tamanho fixo e contíguo na memória (por exemplo, Array(UInt8) ou Array(FixedString(2))); os bytes dos elementos são copiados literalmente em sua ordem nativa na memória, de modo que o resultado possa ser reinterpretado de volta para o tipo Array original em qualquer arquitetura. Arrays cujos elementos sejam de comprimento variável (por exemplo, Array(String)) ou Nullable (por exemplo, Array(Nullable(Int32))) não têm suporte.

Sintaxe

reinterpret(x, type)

Argumentos

• x — Valor a ser reinterpretado. Ao reinterpretar para String, um Array de origem deve ter elementos contíguos de tamanho fixo. Any
• type — Tipo de destino. Se for um Array, o tipo de elemento do Array deverá ser de comprimento fixo. String

Valor retornado

Valor do tipo de destino. Any

Exemplos

Exemplo de uso

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 │
└─────────────┴──────────────┴───────────────┘

Exemplo de 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]  │
└────────────────────────────┘

Exemplo de Array para 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                   │
└──────────────────────────┘

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor Date (assumindo a ordem little endian), que é o número de dias desde o início da epoch Unix em 1970-01-01

Sintaxe

reinterpretAsDate(x)

Argumentos

• x — Número de dias desde o início da epoch Unix. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Date. Date

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor DateTime (assumindo a ordem little endian), que representa o número de dias desde o início da epoch Unix, em 1970-01-01

Sintaxe

reinterpretAsDateTime(x)

Argumentos

• x — Número de segundos desde o início do epoch Unix. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Data e hora. DateTime

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como uma string de tamanho fixo (assumindo a ordem little endian). Os bytes nulos no final são ignorados; por exemplo, para o valor UInt32 255, a função retorna uma string com um único caractere.

Sintaxe

reinterpretAsFixedString(x)

Argumentos

• x — Valor a ser reinterpretado como string. (U)Int* ou Float* ou Date ou DateTime

Valor retornado

String fixa que contém os bytes que representam x. FixedString

Exemplos

Exemplo de uso

-- 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                                                │
└──────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Float32. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não for capaz de representar o tipo de entrada, o resultado será indefinido.

Sintaxe

reinterpretAsFloat32(x)

Argumentos

• x — Valor a ser reinterpretado como Float32. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado x. Float32

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Float64. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não conseguir representar o tipo de entrada, o resultado será indefinido.

Sintaxe

reinterpretAsFloat64(x)

Argumentos

• x — Valor a ser reinterpretado como Float64. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado x. Float64

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Int128. Diferentemente de CAST, a função não tenta preservar o valor original — se o tipo de destino não for capaz de representar o tipo de entrada, o resultado será indefinido.

Sintaxe

reinterpretAsInt128(x)

Argumentos

• x — Valor a ser reinterpretado como Int128. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado x. Int128

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Int16. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não conseguir representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsInt16(x)

Argumentos

• x — Valor a ser reinterpretado como Int16. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor x reinterpretado. Int16

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Int256. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não conseguir representar o tipo de entrada, o resultado será indefinido.

Sintaxe

reinterpretAsInt256(x)

Argumentos

• x — Valor a ser reinterpretado como Int256. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor x reinterpretado. Int256

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Int32. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não puder representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsInt32(x)

Argumentos

• x — Valor a ser reinterpretado como Int32. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado x. Int32

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Int64. Diferentemente de CAST, a função não tenta preservar o valor original — se o tipo de destino não conseguir representar o tipo de entrada, o resultado é indefinido.

Sintaxe

reinterpretAsInt64(x)

Argumentos

• x — Valor a ser reinterpretado como Int64. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor x reinterpretado. Int64

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo Int8. Ao contrário de CAST, a função não tenta preservar o valor original; se o tipo de destino não conseguir representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsInt8(x)

Argumentos

• x — Valor a ser reinterpretado como Int8. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor x reinterpretado. Int8

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como uma string. Para valores escalares, a ordem dos bytes é normalizada para little-endian, e os bytes nulos no final são ignorados; por exemplo, para o valor UInt32 255, a função retorna uma string com um único caractere. Para um Array de elementos de tamanho fixo, os bytes dos elementos são copiados literalmente em sua ordem nativa na memória, sem remover bytes zero à direita e sem normalizar para little-endian, de modo que o resultado possa ser reinterpretado de volta para o tipo Array original em qualquer arquitetura.

Sintaxe

reinterpretAsString(x)

Argumentos

• x — Valor a ser reinterpretado como string. (U)Int* ou Float* ou Date ou DateTime ou Array

Valor retornado

String contendo os bytes que representam x. String

Exemplos

Exemplo de uso

-- 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                                             │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘

Exemplo de Array para String

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo UInt128. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não puder representar o tipo de entrada, o resultado será indefinido.

Sintaxe

reinterpretAsUInt128(x)

Argumentos

• x — Valor a ser reinterpretado como UInt128. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado de x. UInt128

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo UInt16. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não for capaz de representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsUInt16(x)

Argumentos

• x — Valor a ser reinterpretado como UInt16. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado de x. UInt16

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo UInt256. Diferentemente de CAST, a função não tenta preservar o valor original — se o tipo de destino não conseguir representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsUInt256(x)

Argumentos

• x — Valor a ser reinterpretado como UInt256. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor x reinterpretado. UInt256

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo UInt32. Diferentemente de CAST, a função não tenta preservar o valor original — se o tipo de destino não conseguir representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsUInt32(x)

Argumentos

• x — Valor a reinterpretar como UInt32. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor x reinterpretado. UInt32

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo UInt64. Ao contrário de CAST, a função não tenta preservar o valor original — se o tipo de destino não for capaz de representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsUInt64(x)

Argumentos

• x — Valor a ser reinterpretado como UInt64. Int* ou UInt* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado de x. UInt64

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Reinterpreta o valor de entrada como um valor do tipo UInt8. Diferentemente de CAST, a função não tenta preservar o valor original — se o tipo de destino não puder representar o tipo de entrada, a saída será indefinida.

Sintaxe

reinterpretAsUInt8(x)

Argumentos

• x — Valor a ser reinterpretado como UInt8. (U)Int* ou Float* ou Date ou DateTime ou UUID ou String ou FixedString

Valor retornado

Retorna o valor reinterpretado de x. UInt8

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Aceita uma string de 16 bytes e retorna um UUID, interpretando cada metade de 8 bytes na ordem de bytes little-endian. Se a string não for longa o suficiente, a função se comporta como se ela fosse preenchida no final com a quantidade necessária de bytes nulos. Se a string tiver mais de 16 bytes, os bytes extras no final serão ignorados.

Sintaxe

reinterpretAsUUID(fixed_string)

Argumentos

• fixed_string — Cadeia de bytes em big-endian. FixedString

Valor retornado

O valor do tipo UUID. UUID

Exemplos

De string para UUID

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

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

Introduzido na versão: v1.1.0

Converte um valor de entrada em um valor do tipo BFloat16. Lança uma exceção em caso de erro.

Veja também:

• toBFloat16OrZero.
• toBFloat16OrNull.

Sintaxe

toBFloat16(expr)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expression

Valor retornado

Retorna um valor brain-float de 16 bits. BFloat16

Exemplos

Exemplo de uso

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

Introduzido em: v1.1.0

Converte um valor de entrada do tipo String em um valor do tipo BFloat16. Se a string não representar um valor de ponto flutuante, a função retorna NULL.

Argumentos compatíveis:

• Representações em String de valores numéricos.

Argumentos não suportados (retornam NULL):

• Representações em String de valores binários e hexadecimais.
• Valores numéricos.

Veja também:

• toBFloat16.
• toBFloat16OrZero.

Sintaxe

toBFloat16OrNull(x)

Argumentos

• x — Uma representação em String de um número. String

Valor retornado

Retorna um valor brain-float de 16 bits ou NULL. BFloat16 ou NULL

Exemplos

Exemplo de uso

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

\N	12.25	12.3125

Introduzido em: v1.1.0

Converte um valor de entrada String em um valor do tipo BFloat16. Se a string não representar um valor de ponto flutuante, a função retorna zero.

Argumentos suportados:

• Representações String de valores numéricos.

Argumentos não suportados (retornam 0):

• Representações String de valores binários e hexadecimais.
• Valores numéricos.

Veja também:

• toBFloat16.
• toBFloat16OrNull.

Sintaxe

toBFloat16OrZero(x)

Argumentos

• x — Uma representação em string de um número. String

Valor retornado

Retorna um valor brain-float de 16 bits; caso contrário, 0. BFloat16

Exemplos

Exemplo de uso

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

0	12.25	12.3125

Introduzido em: v22.2.0

Converte um valor de entrada em um valor do tipo Bool.

Sintaxe

toBool(expr)

Argumentos

• expr — Expressão que retorna um número ou uma string. Para strings, aceita 'true' ou 'false' (sem distinção entre maiúsculas e minúsculas). (U)Int* ou Float* ou String ou Expression

Valor retornado

Retorna true ou false com base na avaliação do argumento. Bool

Exemplos

Exemplo de uso

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

Introduzido em: v1.1.0

Converte um valor de entrada para o tipo Date. É compatível com a conversão de String, FixedString, DateTime ou tipos numéricos.

Sintaxe

toDate(x)

Argumentos

• x — Valor de entrada a ser convertido. String ou FixedString ou DateTime ou (U)Int* ou Float*

Valor retornado

Retorna o valor de entrada convertido. Date

Exemplos

Conversão de String para Date

SELECT toDate('2025-04-15')

2025-04-15

Conversão de DateTime para Date

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

2025-04-15

Conversão de inteiro para data

SELECT toDate(20297)

2025-07-28

Introduzido em: v21.9.0

Converte o argumento para o tipo de dado Date32. Se o valor estiver fora do intervalo [0000-01-01, 9999-12-31], toDate32 retorna os valores de limite suportados por Date32. Se o argumento for do tipo Date, seus limites serão considerados.

Sintaxe

toDate32(expr)

Argumentos

• expr — O valor a ser convertido. String ou UInt32 ou Date

Valor retornado

Retorna uma data de calendário. Date32

Exemplos

No intervalo

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

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

Antes de 1900

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

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

Introduzido em: v21.11.0

Converte o argumento para o tipo de dado Date32. Se o argumento não puder ser convertido, incluindo um valor numérico fora do intervalo de Date32, a função retornará um valor padrão, que será o segundo argumento (se especificado) ou, caso contrário, 1900-01-01, o valor padrão histórico de Date32 (e não seu limite inferior, que é 0000-01-01). Se o argumento for do tipo Date, os limites desse tipo serão levados em consideração.

Observe que, diferentemente de toDate32, esta função não satura um argumento numérico fora do intervalo para os limites de Date32; esse argumento é tratado como não conversível.

Sintaxe

toDate32OrDefault(expr[, default])

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. String ou (U)Int* ou Float*
• default — Opcional. O valor padrão a ser retornado se a análise não for bem-sucedida. Date32

Valor retornado

Valor do tipo Date32 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 1900-01-01, se não. Date32

Exemplos

Conversão bem-sucedida

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

1930-01-01

Falha na conversão

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

2020-01-01

Número fora do intervalo

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

2020-01-01

Introduzido em: v21.9.0

Converte um valor de entrada em um valor do tipo Date32, mas retorna NULL se receber um argumento inválido. Igual a toDate32, mas retorna NULL se receber um argumento inválido.

Sintaxe

toDate32OrNull(x)

Argumentos

• x — Uma representação textual de uma data. String

Valor retornado

Retorna um valor Date32 em caso de sucesso; caso contrário, NULL. Date32 ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v21.9.0

Converte um valor de entrada em um valor do tipo Date32, mas retorna o valor padrão 1900-01-01 se receber um argumento inválido. É igual a toDate32, mas retorna 1900-01-01 se receber um argumento inválido. Observe que 1900-01-01 é um valor padrão histórico para entradas inválidas, não o limite inferior de Date32, que é 0000-01-01.

Veja também:

• toDate32
• toDate32OrNull
• toDate32OrDefault

Sintaxe

toDate32OrZero(x)

Argumentos

• x — Uma representação textual de uma data. String

Valor retornado

Retorna um valor Date32 em caso de sucesso; caso contrário, o valor padrão histórico para entrada inválida (1900-01-01). Date32

Exemplos

Exemplo de uso

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

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

Introduzido em: v21.11.0

Assim como toDate, mas, em caso de falha, retorna um valor padrão, que é o segundo argumento (se especificado) ou, caso contrário, o limite inferior de Date.

Sintaxe

toDateOrDefault(expr[, default])

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. String ou (U)Int* ou Float*
• default — Opcional. O valor padrão a ser retornado se o parsing não for bem-sucedido. Date

Valor retornado

Valor do tipo Date em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 1970-01-01, se não. Date

Exemplos

Conversão bem-sucedida

SELECT toDateOrDefault('2022-12-30')

2022-12-30

Falha na conversão

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

2023-01-01

Introduzido na versão: v1.1.0

Converte um valor de entrada em um valor do tipo Date, mas retorna NULL se receber um argumento inválido. É o mesmo que toDate, mas retorna NULL se receber um argumento inválido. Um argumento inteiro é interpretado da mesma forma que em toDate (como um número de dias desde 1970-01-01 se não exceder 65535; caso contrário, como um timestamp Unix) e produz NULL se estiver fora do intervalo do tipo Date.

Sintaxe

toDateOrNull(x)

Argumentos

• x — Uma representação textual de uma data, ou um número inteiro de dias ou um timestamp Unix. String ou (U)Int8/16/32/64

Valor retornado

Retorna um valor Date em caso de sucesso; caso contrário, NULL. Date ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Converte um valor de entrada em um valor do tipo Date, mas retorna o limite inferior de Date caso receba um argumento inválido. É o mesmo que toDate, mas retorna o limite inferior de Date caso receba um argumento inválido.

Veja também:

• toDate
• toDateOrNull
• toDateOrDefault

Sintaxe

toDateOrZero(x)

Argumentos

• x — Uma representação textual de uma data. String

Valor retornado

Retorna um valor do tipo Date em caso de sucesso; caso contrário, o limite inferior de Date (1970-01-01). Date

Exemplos

Exemplo de uso

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

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

Introduzido em: v1.1.0

Converte um valor de entrada para o tipo DateTime.

Sintaxe

toDateTime(expr[, time_zone])

Argumentos

• expr — O valor. String ou Int ou Date ou DateTime
• time_zone — Fuso horário. String

Valor retornado

Retorna um valor de data e hora. DateTime

Exemplos

Exemplo de uso

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

Introduzido em: v20.9.0

Converte um valor de entrada para o tipo DateTime. Oferece suporte à conversão de String, FixedString, Date, Date32, Time, DateTime, DateTime64 ou tipos numéricos ((U)Int8, (U)Int16, (U)Int32, (U)Int64, BFloat16, Float32, Float64). Não há suporte para valores Decimal e Time64, que resultam em uma exceção; o tipo Time e tipos inteiros largos, como (U)Int128/(U)Int256, sofrem wraparound em vez de saturação. DateTime32 é um alias de DateTime e oferece suporte a datas de 1970-01-01 00:00:00 a 2106-02-07 06:28:15. Ao converter uma string ou um dos tipos numéricos saturáveis listados acima, valores fora desse intervalo são saturados nos limites do intervalo. Valores de ponto flutuante não finitos (NaN, inf, -inf) não podem ser convertidos e resultam em uma exceção. Conversões de outros tipos de data e hora, como Date32 ou DateTime64, seguem a configuração date_time_overflow_behavior: o modo padrão ignore pode gerar valores com wraparound, saturate os limita aos limites do intervalo e throw lança uma exceção.

Sintaxe

toDateTime32(x[, timezone])

Argumentos

• x — Valor de entrada a converter. String ou FixedString ou (U)Int* ou Float* ou BFloat16 ou Date ou Date32 ou Time ou DateTime ou DateTime64
• timezone — Opcional. Fuso horário do valor DateTime retornado. String

Valor retornado

Retorna o valor de entrada convertido. DateTime

Exemplos

De uma string

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

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

A partir de um timestamp Unix

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

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

Com um fuso horário

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') │
└─────────────────────┴───────────────────────────┘

Introduzido na: v20.1.0

Converte um valor de entrada em um valor do tipo DateTime64.

Sintaxe

toDateTime64(expr, scale[, timezone])

Argumentos

• expr — Expressão que retorna um número ou uma representação textual de um número. Expression
• scale — Tamanho do tick (precisão): 10^(-scale) segundos. UInt8
• timezone — Opcional. Fuso horário do objeto DateTime64 especificado. String

Valor retornado

Retorna uma data e hora, com precisão de subsegundos. DateTime64

Exemplos

O valor está dentro do intervalo

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)     │
└─────────────────────────┴───────────────────┘

Como Decimal com precisão especificada

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)     │
└─────────────────────────┴───────────────────┘

Com fuso horário

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') │
└─────────────────────────┴────────────────────────────────┘

Introduzido em: v21.11.0

Assim como toDateTime64, esta função converte um valor de entrada em um valor do tipo DateTime64, mas retorna o valor padrão de DateTime64 ou o valor padrão fornecido caso receba um argumento inválido.

Sintaxe

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

Argumentos

• expr — Expressão que retorna um número ou uma representação textual de um número. String ou (U)Int* ou Float*
• scale — Tamanho do tick (precisão): 10^-precisão segundos. UInt8
• timezone — Opcional. Fuso horário. String
• default — Opcional. O valor padrão a ser retornado se o parsing falhar. DateTime64

Valor retornado

Valor do tipo DateTime64 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 1970-01-01 00:00:00.000, se não. DateTime64

Exemplos

Conversão bem-sucedida

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

1976-10-18 00:00:00.300

Conversão malsucedida

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

Introduzido em: v20.1.0

Converte um valor de entrada para o tipo DateTime64, mas retorna NULL se receber um argumento inválido. Igual a toDateTime64, mas retorna NULL se receber um argumento inválido. Um argumento inteiro é interpretado como um timestamp Unix em segundos inteiros e retorna NULL se estiver fora do intervalo do tipo DateTime64.

Sintaxe

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

Argumentos

• x — Uma representação textual de uma data e hora com precisão de frações de segundo, ou um timestamp Unix inteiro. String ou (U)Int8/16/32/64
• precision — Opcional. A precisão de frações de segundo do valor retornado. UInt8
• timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado

Retorna um valor DateTime64 em caso de sucesso; caso contrário, NULL. DateTime64 ou NULL

Exemplos

Exemplo de uso

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 │                          ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴───────────────────────────────┘

Introduzido em: v20.1.0

Converte um valor de entrada em um valor do tipo DateTime64, mas retorna o limite inferior de DateTime64 se receber um argumento inválido. Igual a toDateTime64, mas retorna o limite inferior de DateTime64 se receber um argumento inválido.

Veja também:

• toDateTime64.
• toDateTime64OrNull.
• toDateTime64OrDefault.

Sintaxe

toDateTime64OrZero(x)

Argumentos

• x — Uma representação textual de uma data com hora e precisão de frações de segundo. String

Valor retornado

Retorna um valor DateTime64 em caso de sucesso; caso contrário, o limite inferior de DateTime64 (1970-01-01 00:00:00.000). DateTime64

Exemplos

Exemplo de uso

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 │
└───────────────────────────────────────────────┴───────────────────────────────┘

Introduzido em: v21.11.0

Semelhante a toDateTime, mas, se não for bem-sucedido, retorna um valor padrão, que é o terceiro argumento (se especificado) ou, caso contrário, o limite inferior de DateTime.

Sintaxe

toDateTimeOrDefault(expr[, timezone, default])

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. String ou (U)Int* ou Float*
• timezone — Opcional. Fuso horário. String
• default — Opcional. O valor padrão a ser retornado se não for possível fazer o parsing. DateTime

Valor retornado

Valor do tipo DateTime em caso de sucesso; caso contrário, retorna o valor padrão, se ele tiver sido informado, ou 1970-01-01 00:00:00, se não. DateTime

Exemplos

Conversão bem-sucedida

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

2022-12-30 13:44:17

Falha de conversão

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

2023-01-01 00:00:00

Introduzido na versão: v1.1.0

Converte um valor de entrada em um valor do tipo DateTime, mas retorna NULL se receber um argumento inválido. O mesmo que toDateTime, mas retorna NULL se receber um argumento inválido. Um argumento inteiro é interpretado como um timestamp Unix e retorna NULL se estiver fora do intervalo do tipo DateTime.

Sintaxe

toDateTimeOrNull(x[, timezone])

Argumentos

• x — Uma representação textual de uma data com hora ou um timestamp Unix inteiro. String ou (U)Int8/16/32/64
• timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado

Retorna um valor DateTime em caso de sucesso; caso contrário, NULL. DateTime ou NULL

Exemplos

Exemplo de uso

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 │                        ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘

Argumento inteiro com fuso horário

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

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

Introduzido em: v1.1.0

Converte um valor de entrada em um valor do tipo DateTime, mas retorna o limite inferior de DateTime se receber um argumento inválido. É igual a toDateTime, mas retorna o limite inferior de DateTime se receber um argumento inválido.

Sintaxe

toDateTimeOrZero(x)

Argumentos

• x — Uma representação textual de uma data e hora. String

Valor retornado

Retorna um valor DateTime em caso de sucesso; caso contrário, retorna o limite inferior de DateTime (1970-01-01 00:00:00). DateTime

Exemplos

Exemplo de uso

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 │
└─────────────────────────────────────────┴─────────────────────────────┘

Introduzido em: v18.12.0

Converte um valor de entrada em um valor do tipo Decimal(38, S) com escala S. Lança uma exceção em caso de erro.

Argumentos compatíveis:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não compatíveis:

• Valores ou representações em string de valores Float* NaN e Inf (sem distinção entre maiúsculas e minúsculas).
• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toDecimal128('0xc0fe', 1);.

Sintaxe

toDecimal128(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expression
• S — Parâmetro de escala entre 0 e 38, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor do tipo Decimal(38, S) Decimal128(S)

Exemplos

Exemplo de uso

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)

Introduzido em: v21.11.0

Assim como toDecimal128, esta função converte um valor de entrada para um valor do tipo Decimal(38, S), mas retorna o valor padrão em caso de erro.

Sintaxe

toDecimal128OrDefault(expr, S[, default])

Argumentos

• expr — Uma representação textual de um número. String
• S — Parâmetro de escala entre 0 e 38, especificando quantos dígitos a parte fracionária de um número pode ter. UInt8
• default — Opcional. O valor padrão a ser retornado se a conversão para o tipo Decimal128(S) não for bem-sucedida. Decimal128(S)

Valor retornado

Valor do tipo Decimal(38, S) em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, caso não seja. Decimal128(S)

Exemplos

Conversão bem-sucedida

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

0.023809523809523808

Falha na conversão

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

-1

Introduzido em: v20.1.0

Converte um valor de entrada em um valor do tipo Decimal(38, S), mas retorna NULL em caso de erro. Como toDecimal128, mas retorna NULL em vez de lançar uma exceção em erros de conversão.

Argumentos aceitos:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não aceitos (retornam NULL):

• Valores ou representações em string de valores Float* NaN e Inf (sem distinção entre maiúsculas e minúsculas).
• Representações em string de valores binários e hexadecimais.
• Valores que excedem os limites de Decimal128:(-1*10^(38 - S), 1*10^(38 - S)).

Veja também:

• toDecimal128.
• toDecimal128OrZero.
• toDecimal128OrDefault.

Sintaxe

toDecimal128OrNull(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expression
• S — Parâmetro de escala entre 0 e 38, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(38, S) em caso de sucesso; caso contrário, NULL. Decimal128(S) ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v20.1.0

Converte um valor de entrada em um valor do tipo Decimal(38, S), mas retorna 0 em caso de erro. É como toDecimal128, mas retorna 0 em vez de lançar uma exceção em caso de erro de conversão.

Argumentos compatíveis:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos sem suporte (retornam 0):

• Valores ou representações em string de valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais.

Sintaxe

toDecimal128OrZero(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expression
• S — Parâmetro de escala entre 0 e 38, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(38, S) em caso de sucesso; caso contrário, 0. Decimal128(S)

Exemplos

Uso básico

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

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

Introduzido em: v20.8.0

Converte um valor de entrada em um valor do tipo Decimal(76, S) com escala S. Gera uma exceção em caso de erro.

Argumentos aceitos:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não aceitos:

• Valores ou representações em string dos valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toDecimal256('0xc0fe', 1);.

Sintaxe

toDecimal256(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. Expression
• S — Parâmetro de escala entre 0 e 76, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor do tipo Decimal(76, S). Decimal256(S)

Exemplos

Exemplo de uso

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)

Introduzido em: v21.11.0

Assim como toDecimal256, esta função converte um valor de entrada em um valor do tipo Decimal(76, S), mas retorna o valor padrão em caso de erro.

Sintaxe

toDecimal256OrDefault(expr, S[, default])

Argumentos

• expr — Uma representação de um número em String. String
• S — Parâmetro de escala entre 0 e 76, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8
• default — Opcional. O valor padrão a ser retornado se a conversão para o tipo Decimal256(S) falhar. Decimal256(S)

Valor retornado

Valor do tipo Decimal(76, S) em caso de sucesso; caso contrário, retorna o valor padrão, se informado, ou 0, se não. Decimal256(S)

Exemplos

Conversão bem-sucedida

SELECT toDecimal256OrDefault(toString(1/42), 76)

0.023809523809523808

Falha na conversão

SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))

-1

Introduzido em: v20.8.0

Converte um valor de entrada em um valor do tipo Decimal(76, S), mas retorna NULL em caso de erro. É semelhante a toDecimal256, mas retorna NULL em vez de gerar uma exceção em caso de erro de conversão.

Argumentos suportados:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não suportados (retornam NULL):

• Valores ou representações em string de valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais.
• Valores que excedem os limites de Decimal256: (-1 * 10^(76 - S), 1 * 10^(76 - S)).

Veja também:

• toDecimal256.
• toDecimal256OrZero.
• toDecimal256OrDefault.

Sintaxe

toDecimal256OrNull(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expression
• S — Parâmetro de escala entre 0 e 76, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(76, S) em caso de sucesso; caso contrário, NULL. Decimal256(S) ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v20.8.0

Converte um valor de entrada em um valor do tipo Decimal(76, S), mas retorna 0 em caso de erro. Como toDecimal256, mas retorna 0 em vez de lançar uma exceção em erros de conversão.

Argumentos aceitos:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não suportados (retornam 0):

• Valores ou representações em string de valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais.

Veja também:

• toDecimal256.
• toDecimal256OrNull.
• toDecimal256OrDefault.

Sintaxe

toDecimal256OrZero(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. Expression
• S — Parâmetro de escala entre 0 e 76, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(76, S) em caso de sucesso; caso contrário, 0. Decimal256(S)

Exemplos

Exemplo de uso

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

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

Introduzido em: v18.12.0

Converte um valor de entrada para o tipo Decimal(9, S) com escala S. Lança uma exceção em caso de erro.

Argumentos com suporte:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos sem suporte:

• Valores ou representações em string dos valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toDecimal32('0xc0fe', 1);.

Sintaxe

toDecimal32(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. Expression
• S — Parâmetro de escala entre 0 e 9, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor do tipo Decimal(9, S) Decimal32(S)

Exemplos

Exemplo de uso

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)

Introduzido em: v21.11.0

Assim como toDecimal32, esta função converte um valor de entrada em um valor do tipo Decimal(9, S), mas retorna o valor padrão em caso de erro.

Sintaxe

toDecimal32OrDefault(expr, S[, default])

Argumentos

• expr — Uma representação em string de um número. String
• S — Parâmetro de escala entre 0 e 9, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8
• default — Opcional. O valor padrão a ser retornado se a conversão para o tipo Decimal32(S) não for bem-sucedida. Decimal32(S)

Valor retornado

Valor do tipo Decimal(9, S) em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. Decimal32(S)

Exemplos

Conversão bem-sucedida

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

Falha de conversão

SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))

-1

Introduzido em: v20.1.0

Converte um valor de entrada em um valor do tipo Decimal(9, S), mas retorna NULL em caso de erro. Assim como toDecimal32, mas retorna NULL em vez de lançar uma exceção em caso de erro de conversão.

Argumentos aceitos:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não aceitos (retornam NULL):

• Valores ou representações em string de valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais.
• Valores que excedem os limites de Decimal32:(-1*10^(9 - S), 1*10^(9 - S)).

Veja também:

• toDecimal32.
• toDecimal32OrZero.
• toDecimal32OrDefault.

Sintaxe

toDecimal32OrNull(expr, S)

Argumentos

• expr — Expressão que retorna um número ou uma representação textual de um número. Expressão
• S — Parâmetro de escala entre 0 e 9, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(9, S) em caso de sucesso; caso contrário, NULL. Decimal32(S) ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v20.1.0

Converte um valor de entrada em um valor do tipo Decimal(9, S), mas retorna 0 em caso de erro. Semelhante a toDecimal32, mas retorna 0 em vez de lançar uma exceção em erros de conversão.

Argumentos compatíveis:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos sem suporte (retornam 0):

• Valores ou representações em string de valores NaN e Inf do tipo Float* (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais.

Sintaxe

toDecimal32OrZero(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expressão
• S — Parâmetro de escala entre 0 e 9, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(9, S) em caso de sucesso; caso contrário, 0. Decimal32(S)

Exemplos

Exemplo de uso

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

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

Introduzido em: v18.12.0

Converte um valor de entrada em um valor do tipo Decimal(18, S), com escala S. Lança uma exceção em caso de erro.

Argumentos aceitos:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não aceitos:

• Valores ou representações em string dos valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toDecimal64('0xc0fe', 1);.

Sintaxe

toDecimal64(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. Expressão
• S — Parâmetro de escala entre 0 e 18, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor decimal. Decimal(18, S)

Exemplos

Exemplo de uso

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)

Introduzido em: v21.11.0

Assim como toDecimal64, esta função converte um valor de entrada em um valor do tipo Decimal(18, S), mas retorna o valor padrão em caso de erro.

Sintaxe

toDecimal64OrDefault(expr, S[, default])

Argumentos

• expr — Uma representação em string de um número. String
• S — Parâmetro de escala entre 0 e 18, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8
• default — Opcional. O valor padrão a ser retornado caso a conversão para o tipo Decimal64(S) falhe. Decimal64(S)

Valor retornado

Um valor do tipo Decimal(18, S) em caso de sucesso; caso contrário, retorna o valor padrão, se ele tiver sido fornecido, ou 0, se não. Decimal64(S)

Exemplos

Conversão bem-sucedida

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

Falha na conversão

SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))

-1

Introduzido em: v20.1.0

Converte um valor de entrada em um valor do tipo Decimal(18, S), mas retorna NULL em caso de erro. Como toDecimal64, mas retorna NULL em vez de lançar uma exceção em erros de conversão.

Argumentos suportados:

• Valores ou representações em string do tipo (U)Int*.
• Valores ou representações em string do tipo Float*.

Argumentos não suportados (retornam NULL):

• Valores ou representações em string de valores Float* NaN e Inf (sem diferenciar maiúsculas de minúsculas).
• Representações em string de valores binários e hexadecimais.
• Valores que excedem os limites de Decimal64:(-1*10^(18 - S), 1*10^(18 - S)).

Veja também:

• toDecimal64.
• toDecimal64OrZero.
• toDecimal64OrDefault.

Sintaxe

toDecimal64OrNull(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação textual de um número. Expressão
• S — Parâmetro de escala entre 0 e 18, especificando quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(18, S) em caso de sucesso; caso contrário, NULL. Decimal64(S) ou NULL

Exemplos

Exemplo de uso

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

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

Introduzido em: v20.1.0

Converte um valor de entrada para um valor do tipo Decimal(18, S), mas retorna 0 em caso de erro. Semelhante a toDecimal64, mas retorna 0 em vez de lançar uma exceção quando ocorrem erros de conversão.

Argumentos suportados:

• Valores ou representações textuais do tipo (U)Int*.
• Valores ou representações textuais do tipo Float*.

Argumentos não suportados (retornam 0):

• Valores ou representações textuais de valores Float* NaN e Inf (sem distinguir maiúsculas de minúsculas).
• Representações textuais de valores binários e hexadecimais.

Veja também:

• toDecimal64.
• toDecimal64OrNull.
• toDecimal64OrDefault.

Sintaxe

toDecimal64OrZero(expr, S)

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. Expressão
• S — Parâmetro de escala entre 0 e 18, que especifica quantos dígitos a parte fracionária de um número pode ter. UInt8

Valor retornado

Retorna um valor Decimal(18, S) em caso de sucesso; caso contrário, 0. Decimal64(S)

Exemplos

Exemplo de uso

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

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

Introduzido em: v23.3.0

Converte um valor numérico para uma String com o número especificado de dígitos fracionários.

A função arredonda o valor de entrada para o número especificado de casas decimais. Se o valor de entrada tiver menos dígitos fracionários do que o solicitado, o resultado será preenchido com zeros para atingir exatamente o número de dígitos fracionários especificado.

Sintaxe

toDecimalString(number, scale)

Argumentos

• number — O valor numérico a ser convertido em uma String. Pode ser qualquer tipo numérico (Int, UInt, Float, Decimal). Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• scale — O número de dígitos a serem exibidos na parte fracionária. O resultado será arredondado, se necessário. UInt8

Valor retornado

Retorna uma representação em String do número com exatamente a quantidade especificada de dígitos fracionários. String

Exemplos

Arredondar e formatar um número

SELECT toDecimalString(2.1456, 2)

┌─toDecimalString(2.1456, 2)─┐
│ 2.15                       │
└────────────────────────────┘

Completar com zeros

SELECT toDecimalString(5, 3)

┌─toDecimalString(5, 3)─┐
│ 5.000                 │
└───────────────────────┘

Diferentes tipos numéricos

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   │
└─────────────┴───────────┘

Introduzido em: v1.1.0

Converte um argumento String em um tipo FixedString(N) (uma string com comprimento fixo N).

Se a string tiver menos bytes do que N, ela será preenchida com bytes nulos à direita. Se a string tiver mais bytes do que N, uma exceção será gerada.

Sintaxe

toFixedString(s, N)

Argumentos

• s — String a ser convertida. String
• N — Comprimento da FixedString resultante. const UInt*

Valor retornado

Retorna uma FixedString de comprimento N. FixedString(N)

Exemplos

Exemplo de uso

-- The padding is made of null bytes, so the result is shown with `hex`.
SELECT hex(toFixedString('foo', 8)) AS s;

┌─s────────────────┐
│ 666F6F0000000000 │
└──────────────────┘

Introduzido em: v1.1.0

Converte um valor de entrada em um valor do tipo Float32. Lança uma exceção em caso de erro.

Argumentos suportados:

• Valores do tipo (U)Int*.
• Representações em string de (U)Int8/16/32/128/256.
• Valores do tipo Float*, incluindo NaN e Inf.
• Representações em string de Float*, incluindo NaN e Inf (sem diferenciar maiúsculas de minúsculas).

Argumentos não suportados:

• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toFloat32('0xc0fe');.

Veja também:

• toFloat32OrZero.
• toFloat32OrNull.
• toFloat32OrDefault.

Sintaxe

toFloat32(expr)

Argumentos

• expr — Expressão que retorna um número ou uma representação em string de um número. Expressão

Valor retornado

Retorna um valor de ponto flutuante de 32 bits. Float32

Exemplos

Exemplo de uso

SELECT
    toFloat32(42.7),
    toFloat32('42.7'),
    toFloat32('NaN')
FORMAT Vertical

Linha 1:
──────
toFloat32(42.7):   42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'):  nan

Introduzido em: v21.11.0

Assim como toFloat32, esta função converte um valor de entrada em um valor do tipo Float32, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro.

Sintaxe

toFloat32OrDefault(expr[, default])

Argumentos

• expr — Expressão que retorna um número ou a representação em string de um número. String ou (U)Int* ou Float*
• default — Opcional. O valor padrão a ser retornado se a análise não for bem-sucedida. Float32

Valor retornado

Retorna um valor do tipo Float32 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. Float32

Exemplos

Conversão bem-sucedida

SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))

8

Falha na conversão

SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))

0

Introduzido em: v1.1.0

Converte um valor de entrada em um valor do tipo Float32, mas retorna NULL em caso de erro. Semelhante a toFloat32, mas retorna NULL em vez de lançar uma exceção em caso de erro de conversão.

Argumentos suportados:

• Valores do tipo (U)Int*.
• Representações em string de (U)Int8/16/32/128/256.
• Valores do tipo Float*, incluindo NaN e Inf.
• Representações em string de Float*, incluindo NaN e Inf (sem diferenciar maiúsculas de minúsculas).

Argumentos não suportados (retornam NULL):

• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toFloat32OrNull('0xc0fe');.
• Formatos de string inválidos.

Veja também:

• toFloat32.
• toFloat32OrZero.
• toFloat32OrDefault.

Sintaxe

toFloat32OrNull(x)

Argumentos

• x — A representação em string de um número. String

Valor retornado

Retorna um valor Float32 em caso de sucesso; caso contrário, NULL. Float32 ou NULL

Exemplos

Exemplo de uso

SELECT
    toFloat32OrNull('42.7'),
    toFloat32OrNull('NaN'),
    toFloat32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  ᴺᵁᴸᴸ

Introduzido em: v1.1.0

Converte um valor de entrada em um valor do tipo Float32, mas retorna 0 em caso de erro. Semelhante a toFloat32, mas retorna 0 em vez de gerar uma exceção em caso de erro de conversão.

Veja também:

• toFloat32.
• toFloat32OrNull.
• toFloat32OrDefault.

Sintaxe

toFloat32OrZero(x)

Argumentos

• x — Uma representação textual de um número. String

Valor retornado

Retorna um valor Float32 em caso de sucesso; caso contrário, 0. Float32

Exemplos

Exemplo de uso

SELECT
    toFloat32OrZero('42.7'),
    toFloat32OrZero('abc')
FORMAT Vertical

Linha 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'):  0

Introduzido em: v1.1.0

Converte um valor de entrada em um valor do tipo Float64. Lança uma exceção em caso de erro.

Argumentos aceitos:

• Valores do tipo (U)Int*.
• Representações em string de (U)Int8/16/32/128/256.
• Valores do tipo Float*, incluindo NaN e Inf.
• Representações em string do tipo Float*, incluindo NaN e Inf (não diferencia maiúsculas de minúsculas).

Argumentos não aceitos:

• Representações em string de valores binários e hexadecimais, por exemplo, SELECT toFloat64('0xc0fe');.

Veja também:

• toFloat64OrZero.
• toFloat64OrNull.
• toFloat64OrDefault.

Sintaxe

toFloat64(expr)

Argumentos

• expr — Expressão que retorna um número ou uma representação textual de um número. Expression

Valor retornado

Retorna um valor de ponto flutuante de 64 bits. Float64

Exemplos

Exemplo de uso

SELECT
    toFloat64(42.7),
    toFloat64('42.7'),
    toFloat64('NaN')
FORMAT Vertical

Linha 1:
──────
toFloat64(42.7):   42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'):  nan

Introduzido em: v21.11.0

Assim como toFloat64, esta função converte um valor de entrada em um valor do tipo Float64, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro.

Sintaxe

toFloat64OrDefault(expr[, default])

Argumentos

• expr — Expressão que retorna um número ou uma representação textual de um número. String ou (U)Int* ou Float*
• default — Opcional. O valor padrão a ser retornado se a conversão não for bem-sucedida. Float64

Valor retornado

Retorna um valor do tipo Float64 se a conversão for bem-sucedida; caso contrário, retorna o valor padrão, se informado, ou 0, se não. Float64

Exemplos

Conversão bem-sucedida

SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))

8