Funções de conversão de tipos - ClickHouse Documentation

Problemas comuns na conversão de dados

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.

Esteja ciente da possível perda de dados ao converter valores de um tipo de dado para um tipo menor (por exemplo, de Int64 para Int32) ou entre tipos de dados incompatíveis (por exemplo, de String para Int). Verifique com cuidado se o resultado é o esperado.

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

┌─source_type────────────┬─to_type_result_type────┬─cast_result_type─┐
│ LowCardinality(String) │ LowCardinality(String) │ String           │
└────────────────────────┴────────────────────────┴──────────────────┘

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

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ String           │
└──────────────────┴─────────────────────┴──────────────────┘

SELECT
    toTypeName(toNullable('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type
SETTINGS cast_keep_nullable = 1

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ Nullable(String) │
└──────────────────┴─────────────────────┴──────────────────┘

Observações sobre as funções `toString`

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.

Observações sobre as funções `toDate`/`toDateTime`

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

Query

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

Response

┌──────────────────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.

CAST

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

Query

SELECT CAST(42, 'String')

Response

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

Usando a sintaxe AS

Query

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

Response

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

Usando a sintaxe ::

Query

SELECT '123'::UInt32

Response

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

DATE

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

Query

SELECT DATE('2023-01-01')

Response

2023-01-01

accurateCast

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

Query

SELECT accurateCast(42, 'UInt16')

Response

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

De String para número

Query

SELECT accurateCast('123.45', 'Float64')

Response

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

accurateCastOrDefault

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

Query

SELECT accurateCastOrDefault(42, 'String')

Response

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

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

Query

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

Response

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

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

Query

SELECT accurateCastOrDefault('abc', 'UInt32')

Response

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

accurateCastOrNull

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

Query

SELECT accurateCastOrNull(42, 'String')

Response

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

Em caso de falha na conversão, retorna NULL

Query

SELECT accurateCastOrNull('abc', 'UInt32')

Response

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

formatRow

Introduzido em: v20.7.0 Converte expressões arbitrárias em uma string usando o formato especificado.

Se o formato contiver um sufixo/prefixo, ele será gravado em cada linha. Somente formatos por linha são compatíveis com esta função.

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

Query

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

Response

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

Com formato personalizado

Query

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

Response

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

formatRowNoNewline

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

Query

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

Response

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

fromUnixTimestamp64Micro

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

Query

SELECT fromUnixTimestamp64Micro(1640995200123456)

Response

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

fromUnixTimestamp64Milli

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

Query

SELECT fromUnixTimestamp64Milli(1640995200123)

Response

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

fromUnixTimestamp64Nano

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).

Observe que o valor de entrada é tratado como um timestamp em UTC, e não com o fuso horário do valor de entrada.

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

Query

SELECT fromUnixTimestamp64Nano(1640995200123456789)

Response

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

fromUnixTimestamp64Second

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

Query

SELECT fromUnixTimestamp64Second(1640995200)

Response

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

kqlParameterCast

Introduzida na: v26.9.0 Verifica um valor em relação a um tipo declarado da Kusto Query Language e o converte para o tipo correspondente do ClickHouse: um argumento cujo tipo não pertence ao tipo KQL declarado é rejeitado durante a análise, e um valor que não couber (um overflow de int, por exemplo) gera um erro por linha. O segundo argumento é o nome do tipo KQL declarado e o terceiro descreve o parâmetro para a mensagem de erro; ambos devem ser strings constantes. Esta função dá suporte a parâmetros de função tipados quando dialect = 'kusto'. Ela não deve ser chamada diretamente a partir do SQL. Sintaxe

kqlParameterCast(value, type, parameter)

Argumentos

value — O argumento fornecido por uma chamada de função KQL. - type — O nome do tipo KQL declarado, uma string constante. - parameter — Uma descrição do parâmetro, uma string constante usada na mensagem de erro.

Valor retornado value como o tipo ClickHouse correspondente ao tipo declarado. Exemplos long

Query

SELECT kqlParameterCast(5, 'long', 'the parameter') AS x, toTypeName(x)

Response

5	Int64

real

Query

SELECT kqlParameterCast(5, 'real', 'the parameter') AS x, toTypeName(x)

Response

5	Float64

kqlToTimespan

Introduzida na: v26.8.0 Converte um valor em um intervalo de tempo (um Interval em nanossegundos) da mesma forma que a função totimespan() da Kusto Query Language: um intervalo de tempo é repassado sem alteração, um número é interpretado como dias e uma string é lida no formato [-][d.]hh:mm:ss[.fffffff] — retornando NULL quando não é possível interpretá-la. Esta função dá suporte a totimespan() quando dialect = 'kusto'. Ela não deve ser chamada diretamente no SQL. Sintaxe

kqlToTimespan(x)

Arguments

x — Um intervalo de tempo, um número de dias ou uma string que expressa um intervalo de tempo.

Returned value O valor como um interval de nanossegundos; NULL para uma string que não expressa um intervalo de tempo. Examples string

Query

SELECT kqlToTimespan('0.00:01:00')

Response

60000000000

dias

Query

SELECT kqlToTimespan(2)

Response

172800000000000

parseDateTime

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

Query

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

Response

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

parseDateTime32BestEffort

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

Query

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

Response

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

Com fuso horário

Query

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

Response

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

Unix timestamp

Query

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

Response

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

parseDateTime32BestEffortOrNull

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

Query

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

Response

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

parseDateTime32BestEffortOrZero

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

Query

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

Response

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

parseDateTime64

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

Query

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

Response

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

parseDateTime64BestEffort

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

Query

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

Response

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

parseDateTime64BestEffortOrNull

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

Query

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

Response

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

parseDateTime64BestEffortOrZero

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

Query

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

Response

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

parseDateTime64BestEffortUS

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

Query

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

Response

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

parseDateTime64BestEffortUSOrNull

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

Query

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

Response

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

parseDateTime64BestEffortUSOrZero

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

Query

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

Response

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

parseDateTime64InJodaSyntax

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

Query

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

Response

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

parseDateTime64InJodaSyntaxOrNull

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

Query

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

Response

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

parseDateTime64InJodaSyntaxOrZero

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

Query

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

Response

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

parseDateTime64OrNull

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

Query

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

Response

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

parseDateTime64OrZero

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

Query

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

Response

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

parseDateTimeBestEffort

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

Query

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

Response

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

Com fuso horário

Query

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

Response

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

timestamp Unix

Query

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

Response

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

parseDateTimeBestEffortOrNull

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

Query

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

Response

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

parseDateTimeBestEffortOrZero

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

Query

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

Response

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

parseDateTimeBestEffortUS

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

Query

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

Response

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

parseDateTimeBestEffortUSOrNull

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

Query

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

Response

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

parseDateTimeBestEffortUSOrZero

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

Query

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

Response

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

parseDateTimeInJodaSyntax

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

Query

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

Response

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

parseDateTimeInJodaSyntaxOrNull

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

Query

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

Response

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

parseDateTimeInJodaSyntaxOrZero

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

Query

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

Response

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

parseDateTimeOrNull

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

Query

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

Response

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

parseDateTimeOrZero

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

Query

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

Response

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

reinterpret

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

Query

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

Response

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

Exemplo de Array

Query

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

Response

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

Exemplo de Array para String

Query

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

Response

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

reinterpretAsDate

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

Query

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

Response

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

reinterpretAsDateTime

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

Query

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

Response

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

reinterpretAsFixedString

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

Query

-- 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')))

Response

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

reinterpretAsFloat32

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

Query

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

Response

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

reinterpretAsFloat64

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

Query

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

Response

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

reinterpretAsInt128

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

Query

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

Response

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

reinterpretAsInt16

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

Query

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

Response

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

reinterpretAsInt256

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

Query

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

Response

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

reinterpretAsInt32

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

Query

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

Response

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

reinterpretAsInt64

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

Query

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

Response

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

reinterpretAsInt8

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

Query

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

Response

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

reinterpretAsString

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

Query

-- 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')))

Response

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

Exemplo de Array para String

Query

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

Response

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

reinterpretAsUInt128

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

Query

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

Response

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

reinterpretAsUInt16

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

Query

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

Response

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

reinterpretAsUInt256

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

Query

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

Response

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

reinterpretAsUInt32

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

Query

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

Response

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

reinterpretAsUInt64

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

Query

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

Response

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

reinterpretAsUInt8

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

Query

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

Response

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

reinterpretAsUUID

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

Query

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

Response

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

toBFloat16

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

Query

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

Response

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

toBFloat16OrNull

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.

A função permite perda silenciosa de precisão ao converter a representação em String.

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

Query

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

Response

\N	12.25	12.3125

toBFloat16OrZero

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.

A função permite perda silenciosa de precisão ao converter a partir da representação String.

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

Query

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

Response

0	12.25	12.3125

toBool

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

Query

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

Response

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

toDate

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

Query

SELECT toDate('2025-04-15')

Response

2025-04-15

Conversão de DateTime para Date

Query

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

Response

2025-04-15

Conversão de inteiro para data

Query

SELECT toDate(20297)

Response

2025-07-28

toDate32

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

Query

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

Response

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

Antes de 1900

Query

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

Response

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

toDate32OrDefault

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

Query

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

Response

1930-01-01

Falha na conversão

Query

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

Response

2020-01-01

Número fora do intervalo

Query

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

Response

2020-01-01

toDate32OrNull

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

Query

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

Response

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

toDate32OrZero

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

Query

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

Response

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

toDateOrDefault

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

Query

SELECT toDateOrDefault('2022-12-30')

Response

2022-12-30

Falha na conversão

Query

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

Response

2023-01-01

toDateOrNull

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

Query

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

Response

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

toDateOrZero

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

Query

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

Response

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

toDateTime

Introduzido em: v1.1.0 Converte um valor de entrada para o tipo DateTime.

Se expr for um número, ele será interpretado como o número de segundos desde o início da epoch Unix (como timestamp Unix). Se expr for uma String, ela poderá ser interpretada como um timestamp Unix ou como uma representação em string de data / data com hora. Assim, o parsing de representações em string de números curtos (até 4 dígitos) é explicitamente desabilitado devido à ambiguidade; por exemplo, uma string '1999' pode ser tanto um ano (uma representação em string incompleta de Date / DateTime) quanto um timestamp Unix. Strings numéricas mais longas são permitidas.

Se expr for um valor Time ou Time64, ele será interpretado como o número de segundos desde o início da epoch Unix: a parte fracionária de um Time64 é arredondada em direção ao infinito negativo, e valores fora do intervalo de DateTime seguem a configuração date_time_overflow_behavior. Sintaxe

toDateTime(expr[, time_zone])

Argumentos

expr — O valor. String ou Int ou Date ou Date32 ou Time ou Time64 ou DateTime ou DateTime64
time_zone — Fuso horário. String

Valor retornado Retorna um valor de data e hora. DateTime Exemplos Exemplo de uso

Query

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

Response

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

toDateTime32

Introduzido em: v20.9.0 Converte um valor de entrada para o tipo DateTime. Oferece suporte à conversão de String, FixedString, Date, Date32, Time, Time64, DateTime, DateTime64 ou tipos numéricos ((U)Int8, (U)Int16, (U)Int32, (U)Int64, (U)Int128, (U)Int256, BFloat16, Float32, Float64). Não há suporte para valores Decimal, que resultam em uma exceçã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, DateTime64, Time ou Time64, 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. Valores Time64 são primeiro arredondados para baixo, em direção ao infinito negativo, para segundos inteiros. 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 Time64 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

Query

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

Response

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

A partir de um timestamp Unix

Query

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

Response

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

Com um fuso horário

Query

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

Response

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

toDateTime64

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

Query

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

Response

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

Como Decimal com precisão especificada

Query

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);

Response

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

Com fuso horário

Query

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

Response

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

toDateTime64OrDefault

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

Query

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

Response

1976-10-18 00:00:00.300

Conversão malsucedida

Query

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

Response

2001-01-01 00:00:00.000

toDateTime64OrNull

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

Query

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

Response

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

toDateTime64OrZero

Introduzido em: v20.1.0 Converte um valor de entrada em um valor do tipo DateTime64, mas retorna o valor zero de DateTime64 (a epoch Unix, 1970-01-01 00:00:00) se receber um argumento inválido. Igual a toDateTime64, mas retorna o valor zero de DateTime64 se receber um argumento inválido. Veja também:

toDateTime64.
toDateTime64OrNull.
toDateTime64OrDefault.

Sintaxe

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

Argumentos

x — Uma representação textual de uma data com hora e precisão de frações de segundo. String
precision — Opcional. A precisão de frações de segundo do valor retornado. UInt8
timezone — Opcional. O fuso horário do valor retornado. String

Valor retornado Retorna um valor DateTime64 em caso de sucesso; caso contrário, o valor DateTime64 zero (1970-01-01 00:00:00) na precisão solicitada. DateTime64 Exemplos Exemplo de uso

Query

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

Response

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

toDateTimeOrDefault

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

Query

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

Response

2022-12-30 13:44:17

Falha de conversão

Query

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

Response

2023-01-01 00:00:00

toDateTimeOrNull

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

Query

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

Response

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

Argumento inteiro com fuso horário

Query

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

Response

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

toDateTimeOrZero

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

Query

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

Response

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

toDecimal128

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);.

Pode ocorrer overflow se o valor de expr exceder os limites de Decimal128: (-1*10^(38 - S), 1*10^(38 - S)). Dígitos excedentes na parte fracionária são descartados (não arredondados). Dígitos excedentes na parte inteira resultarão em uma exceção.

As conversões descartam dígitos excedentes e podem se comportar de forma inesperada ao trabalhar com entradas Float32/Float64, pois as operações são realizadas usando instruções de ponto flutuante. Por exemplo: toDecimal128(1.15, 2) é igual a 1.14 porque 1.15 * 100 em ponto flutuante é 114.99. Você pode usar uma entrada String para que as operações usem o tipo inteiro subjacente: toDecimal128('1.15', 2) = 1.15

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

Query

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

Response

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)

toDecimal128OrDefault

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

Query

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

Response

0.023809523809523808

Falha na conversão

Query

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

Response

-1

toDecimal128OrNull

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

Query

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

Response

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

toDecimal128OrZero

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.

Se o valor de entrada exceder os limites de Decimal128:(-1*10^(38 - S), 1*10^(38 - S)), a função retornará 0.

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

Query

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

Response

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

toDecimal256

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);.

Pode ocorrer overflow se o valor de expr exceder os limites de Decimal256:(-1*10^(76 - S), 1*10^(76 - S)). Dígitos excedentes na parte fracionária são descartados (não arredondados). Dígitos excedentes na parte inteira gerarão uma exceção.

As conversões descartam dígitos extras e podem se comportar de maneira inesperada ao trabalhar com entradas Float32/Float64, já que as operações são realizadas com instruções de ponto flutuante. Por exemplo: toDecimal256(1.15, 2) é igual a 1.14 porque 1.15 * 100 em ponto flutuante é 114.99. Você pode usar uma entrada String para que as operações usem o tipo inteiro subjacente: toDecimal256('1.15', 2) = 1.15

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

Query

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

Response

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)

toDecimal256OrDefault

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

Query

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

Response

0.023809523809523808

Falha na conversão

Query

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

Response

-1

toDecimal256OrNull

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

Query

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

Response

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

toDecimal256OrZero

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.

Se o valor de entrada exceder os limites de Decimal256:(-1*10^(76 - S), 1*10^(76 - S)), a função retorna 0.

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

Query

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

Response

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

toDecimal32

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);.

Pode haver overflow se o valor de expr exceder os limites de Decimal32:(-1*10^(9 - S), 1*10^(9 - S)). Dígitos excedentes na parte fracionária são descartados (não arredondados). Dígitos excedentes na parte inteira causarão uma exceção.

As conversões descartam dígitos excedentes e podem se comportar de forma inesperada ao trabalhar com entradas Float32/Float64, pois as operações são realizadas usando instruções de ponto flutuante. Por exemplo: toDecimal32(1.15, 2) é igual a 1.14 porque 1.15 * 100 em ponto flutuante é 114.99. Você pode usar uma entrada String para que as operações usem o tipo inteiro subjacente: toDecimal32('1.15', 2) = 1.15

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

Query

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

Response

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)

toDecimal32OrDefault

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

Query

SELECT toDecimal32OrDefault(toString(0.0001), 5)

Response

0.0001

Falha de conversão

Query

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

Response

-1

toDecimal32OrNull

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

Query

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

Response

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

toDecimal32OrZero

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.

Se o valor de entrada exceder os limites de Decimal32:(-1*10^(9 - S), 1*10^(9 - S)), a função retorna 0.

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

Query

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

Response

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

toDecimal64

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);.

Pode ocorrer overflow se o valor de expr exceder os limites de Decimal64:(-1*10^(18 - S), 1*10^(18 - S)). Dígitos em excesso na parte fracionária são descartados (não arredondados). Dígitos em excesso na parte inteira causarão uma exceção.

As conversões descartam dígitos extras e podem se comportar de forma inesperada ao trabalhar com entradas Float32/Float64, pois as operações são realizadas com instruções de ponto flutuante. Por exemplo: toDecimal64(1.15, 2) é igual a 1.14 porque 1.15 * 100 em ponto flutuante é 114.99. Você pode usar uma entrada String para que as operações usem o tipo inteiro subjacente: toDecimal64('1.15', 2) = 1.15

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

Query

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

Response

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)

toDecimal64OrDefault

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

Query

SELECT toDecimal64OrDefault(toString(0.0001), 18)

Response

0.0001

Falha na conversão

Query

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

Response

-1

toDecimal64OrNull

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

Query

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

Response

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

toDecimal64OrZero

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.

Se o valor de entrada exceder os limites de Decimal64:(-1*10^(18 - S), 1*10^(18 - S)), a função retorna 0.

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

Query

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

Response

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

toDecimalString

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

Query

SELECT toDecimalString(2.1456, 2)

Response

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

Completar com zeros

Query

SELECT toDecimalString(5, 3)

Response

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

Diferentes tipos numéricos

Query

SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
       toDecimalString(CAST(42.7 AS Float32), 4) AS float_val

Response

┌─decimal_val─┬─float_val─┐
│ 123.46      │ 42.7000   │
└─────────────┴───────────┘

toFixedString

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

Query

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

Response

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

toFloat32

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

Query

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

Response

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

toFloat32OrDefault

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

Query

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

Response

Falha na conversão

Query

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

Response

toFloat32OrNull

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

Query

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

Response

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

toFloat32OrZero

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

Query

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

Response

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

toFloat64

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

Query

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

Response

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

toFloat64OrDefault

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

Query

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

Response

Falha na conversão

Query

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

Response

toFloat64OrNull

Introduzido em: v1.1.0 Converte um valor de entrada para o tipo Float64, mas retorna NULL em caso de erro. Como toFloat64, mas retorna NULL em vez de lançar uma exceção em erros 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 do tipo 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 toFloat64OrNull('0xc0fe');.
Formatos de string inválidos.

Veja também:

toFloat64.
toFloat64OrZero.
toFloat64OrDefault.

Sintaxe

toFloat64OrNull(x)

Argumentos

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

Valor retornado Retorna um valor Float64 em caso de sucesso; caso contrário, NULL. Float64 ou NULL Exemplos Exemplo de uso

Query

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

Response

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

toFloat64OrZero

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo Float64, mas retorna 0 em caso de erro. Semelhante a toFloat64, mas retorna 0 em vez de lançar uma exceção em caso de erro de conversão. Veja também:

toFloat64.
toFloat64OrNull.
toFloat64OrDefault.

Sintaxe

toFloat64OrZero(x)

Argumentos

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

Valor retornado Retorna um valor Float64 em caso de sucesso; caso contrário, 0. Float64 Exemplos Exemplo de uso

Query

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

Response

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

toInt128

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo Int128. Lança uma exceção em caso de erro. A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números. Argumentos compatíveis:

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

Argumentos não compatíveis:

Representações em string de valores do tipo Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt128('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int128, o resultado sofrerá overflow ou underflow. Isso não é considerado um erro.

Veja também:

toInt128OrZero.
toInt128OrNull.
toInt128OrDefault.

Sintaxe

toInt128(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 inteiro de 128 bits. Int128 Exemplos Exemplo de uso

Query

SELECT
    toInt128(-128),
    toInt128(-128.8),
    toInt128('-128')
FORMAT Vertical

Response

Row 1:
──────
toInt128(-128):   -128
toInt128(-128.8): -128
toInt128('-128'): -128

toInt128OrDefault

Introduzido em: v21.11.0 Assim como toInt128, esta função converte um valor de entrada em um valor do tipo Int128, mas retorna o valor padrão em caso de erro. Se nenhum valor default for fornecido, 0 será retornado em caso de erro. Sintaxe

toInt128OrDefault(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 análise falhar. Int128

Valor retornado Retorna um valor do tipo Int128 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. Int128 Exemplos Conversão bem-sucedida

Query

SELECT toInt128OrDefault('-128', CAST('-1', 'Int128'))

Response

-128

Falha na conversão

Query

SELECT toInt128OrDefault('abc', CAST('-1', 'Int128'))

Response

-1

toInt128OrNull

Introduzido em: v20.8.0 Assim como toInt128, esta função converte um valor de entrada em um valor do tipo Int128, mas retorna NULL em caso de erro. Argumentos aceitos:

Representações de string de (U)Int*.

Argumentos não aceitos (retornam NULL):

Representações de string de valores Float*, incluindo NaN e Inf.
Representações de string de valores binários e hexadecimais, por exemplo, SELECT toInt128OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int128, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt128.
toInt128OrZero.
toInt128OrDefault.

Sintaxe

toInt128OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int128 ou NULL se a conversão não for bem-sucedida. Int128 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toInt128OrNull('-128'),
    toInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'):  ᴺᵁᴸᴸ

toInt128OrZero

Introduzido em: v20.8.0 Converte um valor de entrada para o tipo Int128, mas retorna 0 em caso de erro. Semelhante a toInt128, mas retorna 0 em vez de gerar uma exceção. Veja também:

toInt128.
toInt128OrNull.
toInt128OrDefault.

Sintaxe

toInt128OrZero(x)

Argumentos

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

Valor retornado Retorna o valor de entrada convertido ou 0 se a conversão falhar. Int128 Exemplos Exemplo de uso

Query

SELECT toInt128OrZero('123')

Response

Conversões com falha retornam zero

Query

SELECT toInt128OrZero('abc')

Response

toInt16

Introduzido em: v1.1.0 Converte um valor de entrada para um valor do tipo Int16. Lança uma exceção em caso de erro. Argumentos suportados:

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

Argumentos não suportados:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt16('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int16, ocorre overflow ou underflow no resultado. Isso não é considerado um erro. Por exemplo: SELECT toInt16(32768) == -32768;.

A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números.

Veja também:

toInt16OrZero.
toInt16OrNull.
toInt16OrDefault.

Sintaxe

toInt16(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 inteiro de 16 bits. Int16 Exemplos Exemplo de uso

Query

SELECT
    toInt16(-16),
    toInt16(-16.16),
    toInt16('-16')
FORMAT Vertical

Response

Row 1:
──────
toInt16(-16):    -16
toInt16(-16.16): -16
toInt16('-16'):  -16

toInt16OrDefault

Introduzido em: v21.11.0 Assim como toInt16, esta função converte um valor de entrada em um valor do tipo Int16, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toInt16OrDefault(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. Int16

Valor retornado Retorna um valor do tipo Int16 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. Int16 Exemplos Conversão bem-sucedida

Query

SELECT toInt16OrDefault('-16', CAST('-1', 'Int16'))

Response

-16

Falha de conversão

Query

SELECT toInt16OrDefault('abc', CAST('-1', 'Int16'))

Response

-1

toInt16OrNull

Introduzido em: v1.1.0 Assim como toInt16, esta função converte um valor de entrada para um valor do tipo Int16, mas retorna NULL em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int*.

Argumentos não compatíveis (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt16OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int16, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt16.
toInt16OrZero.
toInt16OrDefault.

Sintaxe

toInt16OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int16 ou NULL, caso a conversão não seja bem-sucedida. Int16 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toInt16OrNull('-16'),
    toInt16OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): ᴺᵁᴸᴸ

toInt16OrZero

Introduzido em: v1.1.0 Assim como toInt16, esta função converte um valor de entrada em um valor do tipo Int16, mas retorna 0 em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int*.

Argumentos incompatíveis (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt16OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int16, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt16.
toInt16OrNull.
toInt16OrDefault.

Sintaxe

toInt16OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int16 ou 0, se a conversão falhar. Int16 Exemplos Exemplo de uso

Query

SELECT
    toInt16OrZero('16'),
    toInt16OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt16OrZero('16'):  16
toInt16OrZero('abc'): 0

toInt256

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo Int256. Lança uma exceção em caso de erro. A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números. Argumentos suportados:

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

Argumentos não suportados:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt256('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int256, o resultado terá overflow ou underflow. Isso não é considerado um erro.

Veja também:

toInt256OrZero.
toInt256OrNull.
toInt256OrDefault.

Sintaxe

toInt256(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro de 256 bits. Int256 Exemplos Exemplo de uso

Query

SELECT
    toInt256(-256),
    toInt256(-256.256),
    toInt256('-256')
FORMAT Vertical

Response

Row 1:
──────
toInt256(-256):     -256
toInt256(-256.256): -256
toInt256('-256'):   -256

toInt256OrDefault

Introduzido em: v21.11.0 Assim como toInt256, esta função converte um valor de entrada em um valor do tipo Int256, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toInt256OrDefault(expr[, default])

Argumentos

expr — Expressão que retorna um número ou uma 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 interpretação não for bem-sucedida. Int256

Valor retornado Retorna um valor do tipo Int256 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, caso contrário. Int256 Exemplos Conversão bem-sucedida

Query

SELECT toInt256OrDefault('-256', CAST('-1', 'Int256'))

Response

-256

Falha na conversão

Query

SELECT toInt256OrDefault('abc', CAST('-1', 'Int256'))

Response

-1

toInt256OrNull

Introduzido em: v20.8.0 Assim como toInt256, esta função converte um valor de entrada em um valor do tipo Int256, mas retorna NULL em caso de erro. Argumentos suportados:

representações em string de (U)Int*.

Argumentos não suportados (retornam NULL):

representações em string de valores Float*, incluindo NaN e Inf.
representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt256OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int256, ocorrerá overflow ou underflow do resultado. Isso não é considerado um erro.

Veja também:

toInt256.
toInt256OrZero.
toInt256OrDefault.

Sintaxe

toInt256OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int256; caso a conversão não seja bem-sucedida, retorna NULL. Int256 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toInt256OrNull('-256'),
    toInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'):  ᴺᵁᴸᴸ

toInt256OrZero

Introduzido em: v20.8.0 Converte um valor de entrada para o tipo Int256, mas retorna 0 em caso de erro. Semelhante a toInt256, mas retorna 0 em vez de gerar uma exceção. Veja também:

toInt256.
toInt256OrNull.
toInt256OrDefault.

Sintaxe

toInt256OrZero(x)

Argumentos

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

Valor retornado Retorna o valor de entrada convertido; caso a conversão falhe, retorna 0. Int256 Exemplos Exemplo de uso

Query

SELECT toInt256OrZero('123')

Response

Conversões com falha retornam zero

Query

SELECT toInt256OrZero('abc')

Response

toInt32

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo Int32. Lança uma exceção em caso de erro. Argumentos compatíveis:

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

Argumentos não compatíveis:

representações em string de valores Float*, incluindo NaN e Inf.
representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt32('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int32, o resultado sofrerá overflow ou underflow. Isso não é considerado um erro. Por exemplo: SELECT toInt32(2147483648) == -2147483648;

A função usa arredondamento em direção a zero, o que significa que ela trunca os dígitos fracionários dos números.

Veja também:

toInt32OrZero.
toInt32OrNull.
toInt32OrDefault.

Sintaxe

toInt32(expr)

Argumentos

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

Valor retornado Retorna um inteiro de 32 bits. Int32 Exemplos Exemplo de uso

Query

SELECT
    toInt32(-32),
    toInt32(-32.32),
    toInt32('-32')
FORMAT Vertical

Response

Row 1:
──────
toInt32(-32):    -32
toInt32(-32.32): -32
toInt32('-32'):  -32

toInt32OrDefault

Introduzido em: v21.11.0 Assim como toInt32, esta função converte um valor de entrada em um valor do tipo Int32, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toInt32OrDefault(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 o parsing não for bem-sucedido. Int32

Valor retornado Retorna um valor do tipo Int32 em caso de sucesso; caso contrário, retorna o valor padrão, se informado, ou 0, caso não tenha sido informado. Int32 Exemplos Conversão bem-sucedida

Query

SELECT toInt32OrDefault('-32', CAST('-1', 'Int32'))

Response

-32

Falha na conversão

Query

SELECT toInt32OrDefault('abc', CAST('-1', 'Int32'))

Response

-1

toInt32OrNull

Introduzido em: v1.1.0 Assim como toInt32, esta função converte um valor de entrada em um valor do tipo Int32, mas retorna NULL em caso de erro. Argumentos aceitos:

Representações em string de (U)Int*.

Argumentos não aceitos (retornam NULL):

representações em string de valores Float*, incluindo NaN e Inf.
representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt32OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int32, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt32.
toInt32OrZero.
toInt32OrDefault.

Sintaxe

toInt32OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int32 ou NULL, caso a conversão não seja bem-sucedida. Int32 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toInt32OrNull('-32'),
    toInt32OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): ᴺᵁᴸᴸ

toInt32OrZero

Introduzido em: v1.1.0 Assim como toInt32, esta função converte um valor de entrada em um valor do tipo Int32, mas retorna 0 em caso de erro. Argumentos aceitos:

Representações em string de (U)Int*.

Argumentos não aceitos (retornam 0):

representações em string de valores Float*, incluindo NaN e Inf.
representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt32OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado nos limites de Int32, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt32.
toInt32OrNull.
toInt32OrDefault.

Sintaxe

toInt32OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int32; caso a conversão falhe, retorna 0. Int32 Exemplos Exemplo de uso

Query

SELECT
    toInt32OrZero('32'),
    toInt32OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt32OrZero('32'):  32
toInt32OrZero('abc'): 0

toInt64

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo Int64. Lança uma exceção em caso de erro. Argumentos compatíveis:

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

Argumentos não compatíveis:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo: SELECT toInt64('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int64, o resultado terá overflow ou underflow. Isso não é considerado um erro. Por exemplo: SELECT toInt64(9223372036854775808) == -9223372036854775808;

A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números.

Veja também:

toInt64OrZero.
toInt64OrNull.
toInt64OrDefault.

Sintaxe

toInt64(expr)

Argumentos

expr — Expressão que retorna um número ou a representação em string de um número. Compatível com: valores ou representações em string do tipo (U)Int*; valores do tipo Float*. Não compatível com: representações em string de valores Float*, incluindo NaN e Inf; representações em string de valores binários e hexadecimais. Expressão

Valor retornado Retorna um valor inteiro de 64 bits. Int64 Exemplos Exemplo de uso

Query

SELECT
    toInt64(-64),
    toInt64(-64.64),
    toInt64('-64')
FORMAT Vertical

Response

Row 1:
──────
toInt64(-64):    -64
toInt64(-64.64): -64
toInt64('-64'):  -64

toInt64OrDefault

Introduzido em: v21.11.0 Assim como toInt64, esta função converte um valor de entrada em um valor do tipo Int64, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toInt64OrDefault(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 falhar. Int64

Valor retornado Retorna um valor do tipo Int64 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0. Int64 Exemplos Conversão bem-sucedida

Query

SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))

Response

-64

Falha na conversão

Query

SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))

Response

-1

toInt64OrNull

Introduzido em: v1.1.0 Assim como toInt64, esta função converte um valor de entrada em um valor do tipo Int64, mas retorna NULL em caso de erro. Argumentos suportados:

Representações em string de (U)Int*.

Argumentos não suportados (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt64OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int64, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt64.
toInt64OrZero.
toInt64OrDefault.

Sintaxe

toInt64OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int64; caso contrário, NULL se a conversão não for bem-sucedida. Int64 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toInt64OrNull('-64'),
    toInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): ᴺᵁᴸᴸ

toInt64OrZero

Introduzido em: v1.1.0 Converte um valor de entrada para o tipo Int64, mas retorna 0 em caso de erro. Semelhante a toInt64, mas retorna 0 em vez de lançar uma exceção. Veja também:

toInt64.
toInt64OrNull.
toInt64OrDefault.

Sintaxe

toInt64OrZero(x)

Argumentos

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

Valor retornado Retorna o valor de entrada convertido; caso contrário, 0 se a conversão falhar. Int64 Exemplos Exemplo de uso

Query

SELECT toInt64OrZero('123')

Response

Em caso de falha na conversão, retorna zero

Query

SELECT toInt64OrZero('abc')

Response

toInt8

Introduzido em: v1.1.0 Converte um valor de entrada para o tipo Int8. Lança uma exceção em caso de erro. Argumentos compatíveis:

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

Argumentos não compatíveis:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt8('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int8, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro. Por exemplo: SELECT toInt8(128) == -128;.

A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números.

Veja também:

toInt8OrZero.
toInt8OrNull.
toInt8OrDefault.

Sintaxe

toInt8(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro de 8 bits. Int8 Exemplos Exemplo de uso

Query

SELECT
    toInt8(-8),
    toInt8(-8.8),
    toInt8('-8')
FORMAT Vertical

Response

Row 1:
──────
toInt8(-8):   -8
toInt8(-8.8): -8
toInt8('-8'): -8

toInt8OrDefault

Introduzido em: v21.11.0 Assim como toInt8, esta função converte um valor de entrada em um valor do tipo Int8, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toInt8OrDefault(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 o parsing não for bem-sucedido. Int8

Valor retornado Retorna um valor do tipo Int8 se a conversão for bem-sucedida; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. Int8 Exemplos Conversão bem-sucedida

Query

SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))

Response

-8

Falha na conversão

Query

SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))

Response

-1

toInt8OrNull

Introduzido em: v1.1.0 Assim como toInt8, esta função converte um valor de entrada em um valor do tipo Int8, mas retorna NULL em caso de erro. Argumentos suportados:

Representações de string de (U)Int*.

Argumentos não suportados (retornam NULL):

Representações de string de valores Float*, incluindo NaN e Inf.
Representações de string de valores binários e hexadecimais, por exemplo, SELECT toInt8OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int8, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt8.
toInt8OrZero.
toInt8OrDefault.

Sintaxe

toInt8OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int8; caso contrário, NULL se a conversão não for bem-sucedida. Int8 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toInt8OrNull('-8'),
    toInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): ᴺᵁᴸᴸ

toInt8OrZero

Introduzido em: v1.1.0 Assim como toInt8, esta função converte um valor de entrada em um valor do tipo Int8, mas retorna 0 em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int*.

Argumentos não compatíveis (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toInt8OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de Int8, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toInt8.
toInt8OrNull.
toInt8OrDefault.

Sintaxe

toInt8OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo Int8 ou 0 caso a conversão falhe. Int8 Exemplos Exemplo de uso

Query

SELECT
    toInt8OrZero('8'),
    toInt8OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt8OrZero('8'):   8
toInt8OrZero('abc'): 0

toInterval

Introduzido em: v25.4.0 Cria um valor Interval a partir de um valor numérico e de uma unidade em formato String. Esta função fornece uma forma unificada de criar intervalos de diferentes tipos (segundos, minutos, horas, dias, semanas, meses, trimestres, anos) a partir de uma única função, especificando a unidade como um argumento String. A unidade em String não diferencia maiúsculas de minúsculas. Isso equivale a chamar funções específicas de tipo, como toIntervalSecond, toIntervalMinute, toIntervalDay etc., mas permite especificar a unidade dinamicamente como um parâmetro String. Sintaxe

toInterval(value, unit)

Argumentos

value — O valor numérico que representa a quantidade de unidades. Pode ser qualquer tipo numérico: Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64
unit — A unidade de tempo. Deve ser uma string constante. Valores válidos: ‘nanosecond’, ‘microsecond’, ‘millisecond’, ‘second’, ‘minute’, ‘hour’, ‘day’, ‘week’, ‘month’, ‘quarter’, ‘year’. String

Valor retornado Retorna um valor do tipo Interval do tipo especificado. O tipo do resultado depende da unidade: IntervalNanosecond, IntervalMicrosecond, IntervalMillisecond, IntervalSecond, IntervalMinute, IntervalHour, IntervalDay, IntervalWeek, IntervalMonth, IntervalQuarter ou IntervalYear. Interval Exemplos Criar intervalos com diferentes unidades

Query

SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months

Response

┌─seconds─┬─days─┬─months─┐
│       5 │    3 │      2 │
└─────────┴──────┴────────┘

Use intervalos na aritmética de datas

Query

SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago

Response

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

Criação dinâmica de intervalos

Query

SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)

Response

┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘

toIntervalDay

Introduzido em: v1.1.0 Retorna um intervalo de n dias do tipo de dados IntervalDay. Sintaxe

toIntervalDay(n)

Argumentos

n — Número de dias. Números inteiros ou suas representações em formato de string, e números de ponto flutuante. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n dias. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result

Response

┌─────result─┐
│ 2025-06-20 │
└────────────┘

toIntervalHour

Introduzido em: v1.1.0 Retorna um intervalo de n horas do tipo de dados IntervalHour. Sintaxe

toIntervalHour(n)

Argumentos

n — Número de horas. Números inteiros ou suas representações em string, e números de ponto flutuante. Int* ou UInt* ou Float* ou String

Valor retornado Retorna um intervalo de n horas. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result

Response

┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘

toIntervalMicrosecond

Introduzido em: v22.6.0 Retorna um intervalo de n microssegundos do tipo de dados IntervalMicrosecond. Sintaxe

toIntervalMicrosecond(n)

Argumentos

n — Número de microssegundos. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n microssegundos. Interval Exemplos Exemplo de uso

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result

Response

┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘

toIntervalMillisecond

Introduzido em: v22.6.0 Retorna um intervalo de n milissegundos do tipo de dados IntervalMillisecond. Sintaxe

toIntervalMillisecond(n)

Argumentos

n — Número de milissegundos. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n milissegundos. Interval Exemplos Exemplo de uso

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result

Response

┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘

toIntervalMinute

Introduzido em: v1.1.0 Retorna um intervalo de n minutos do tipo IntervalMinute. Sintaxe

toIntervalMinute(n)

Argumentos

n — Número de minutos. Números inteiros ou suas representações em string, além de números de ponto flutuante. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n minutos. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

toIntervalMonth

Introduzido na versão: v1.1.0 Retorna um intervalo de n meses do tipo de dados IntervalMonth. Sintaxe

toIntervalMonth(n)

Argumentos

n — Número de meses. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n meses. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

Response

┌─────result─┐
│ 2025-07-15 │
└────────────┘

toIntervalNanosecond

Introduzido em: v22.6.0 Retorna um interval de n nanossegundos do tipo de dado IntervalNanosecond. Sintaxe

toIntervalNanosecond(n)

Argumentos

n — Quantidade de nanossegundos. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n nanossegundos. Interval Exemplos Exemplo de uso

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

Response

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

toIntervalQuarter

Introduzido em: v1.1.0 Retorna um intervalo de n trimestres do tipo de dados IntervalQuarter. Sintaxe

toIntervalQuarter(n)

Argumentos

n — Número de trimestres. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n trimestres. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

Response

┌─────result─┐
│ 2025-09-15 │
└────────────┘

toIntervalSecond

Introduzido em: v1.1.0 Retorna um intervalo de n segundos do tipo de dado IntervalSecond. Sintaxe

toIntervalSecond(n)

Argumentos

n — Número de segundos. Números inteiros ou suas representações como string, e números de ponto flutuante. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n segundos. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

toIntervalWeek

Introduzido em: v1.1.0 Retorna um intervalo de n semanas do tipo de dados IntervalWeek. Sintaxe

toIntervalWeek(n)

Argumentos

n — Número de semanas. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n semanas. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

Response

┌─────result─┐
│ 2025-06-22 │
└────────────┘

toIntervalYear

Introduzido em: v1.1.0 Retorna um intervalo de n anos do tipo de dado IntervalYear. Sintaxe

toIntervalYear(n)

Argumentos

n — Número de anos. (U)Int* ou Float* ou String

Valor retornado Retorna um intervalo de n anos. Interval Exemplos Exemplo de uso

Query

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

Response

┌─────result─┐
│ 2025-06-15 │
└────────────┘

toLowCardinality

Introduzido em: v18.12.0 Converte o argumento de entrada para a versão LowCardinality do mesmo tipo de dado.

Para converter do tipo de dado LowCardinality para um tipo de dado regular, use a função CAST. Por exemplo: CAST(x AS String).

Sintaxe

toLowCardinality(expr)

Argumentos

expr — Expressão que resulta em um dos tipos de dados compatíveis. String ou FixedString ou Date ou DateTime ou (U)Int* ou Float*

Valor retornado Retorna o valor de entrada convertido para o tipo de dados LowCardinality. LowCardinality Exemplos Exemplo de uso

Query

SELECT toLowCardinality('1')

Response

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

toString

Introduzido em: v1.1.0 Converte valores para sua representação em string. Para argumentos DateTime, a função pode receber um segundo argumento String contendo o nome do fuso horário. Sintaxe

toString(value[, timezone])

Argumentos

value — Valor a ser convertido para string. Any
timezone — Opcional. Nome do fuso horário para a conversão de DateTime. String

Valor retornado Retorna uma representação em string do valor de entrada. String Exemplos Exemplo de uso

Query

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

Response

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

toStringCutToZero

Introduzido em: v1.1.0 Aceita um argumento String ou FixedString e retorna uma String que contém uma cópia da string original truncada no primeiro byte nulo. Bytes nulos (\0) são considerados terminadores de string. Esta função é útil para processar strings no estilo C ou dados binários nos quais bytes nulos marcam o fim do conteúdo significativo. Sintaxe

toStringCutToZero(s)

Argumentos

s — String ou FixedString a ser processado. String ou FixedString

Valor retornado Retorna uma String contendo os caracteres anteriores ao primeiro byte nulo. String Exemplos Exemplo de uso

Query

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

Response

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

toTime

Introduzido em: v25.5.0 Converte um valor de entrada para o tipo Time. Suporta conversão de String, FixedString, DateTime, DateTime64, Time64 ou tipos numéricos que representam segundos desde a meia-noite. Valores numéricos fora do intervalo do tipo (-999:59:59 a 999:59:59, ou seja, de -3599999 a 3599999 segundos) são limitados aos limites do intervalo, e valores de ponto flutuante não finitos (NaN, inf, -inf) não podem ser convertidos e resultam em uma exceção. Valores Time64 são arredondados em direção ao infinito negativo para segundos inteiros e limitados ao mesmo intervalo.

Antes da v25.5, toTime era uma função diferente, que convertia uma data com hora em uma data fixa (1970-01-02) enquanto preservava o componente de hora. Essa função ainda está disponível com o nome toTimeWithFixedDate.Definir use_legacy_to_time como 1 também mantém o nome toTime vinculado à função legada, ou seja, chamadas a toTime são resolvidas como toTimeWithFixedDate em vez da função de conversão descrita aqui. Enquanto a configuração estiver habilitada, use CAST(x AS Time) ou x::Time para converter para o tipo Time. A configuração usa 0 por padrão desde a v26.7, mas usava 1 por padrão da v25.6 à v26.6, motivo pelo qual os exemplos abaixo a definem explicitamente.

Sintaxe

toTime(x)

Argumentos

x — Valor de entrada a converter. String ou FixedString ou DateTime ou DateTime64 ou Time64 ou (U)Int* ou BFloat16 ou Float*

Valor retornado Retorna o valor convertido. Time Exemplos Conversão de DateTime64 para Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime64('2025-04-15 14:30:25.123', 3))

Response

14:30:25

Conversão de DateTime para Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime('2025-04-15 14:30:25'))

Response

14:30:25

Conversão de inteiro (segundos desde epoch) em Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime(52225, 'UTC'))

Response

14:30:25

toTime64

Introduzido em: v25.6.0 Converte um valor de entrada para o tipo Time64. Oferece suporte à conversão de String, FixedString, DateTime64 ou tipos numéricos que representam segundos desde a meia-noite. Fornece precisão de frações de segundo para valores de tempo, com até scale dígitos fracionários. Sintaxe

toTime64(x, scale)

Argumentos

x — Valor de entrada para conversão. String ou FixedString ou DateTime64 ou (U)Int* ou Float*
scale — Precisão (número de dígitos fracionários, 0–9) do Time64 resultante. (U)Int*

Valor retornado Retorna o valor convertido com o scale especificado. Time64 Exemplos Conversão de String para Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64('14:30:25.123456', 6)

Response

14:30:25.123456

Conversão de DateTime64 para Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6), 6)

Response

14:30:25.123456

Conversão de Float (segundos após a meia-noite) para Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64(52225.123456, 6)

Response

14:30:25.123456

toTime64OrNull

Introduzido em: v25.6.0 Converte um valor de entrada em um valor do tipo Time64, mas retorna NULL em caso de erro. É como toTime64, mas retorna NULL em vez de lançar uma exceção em caso de erro de conversão. Veja também:

toTime64
toTime64OrZero

Sintaxe

toTime64OrNull(x[, precision])

Argumentos

x — Uma representação textual de um horário com precisão de frações de segundo. String
precision — Opcional. A precisão de frações de segundo do valor retornado. UInt8

Valor retornado Retorna um valor Time64 em caso de sucesso; caso contrário, NULL. Time64 ou NULL Exemplos Exemplo de uso

Query

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

Response

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

toTime64OrZero

Introduzido em: v25.6.0 Converte um valor de entrada em um valor do tipo Time64, mas retorna o valor zero de Time64 (00:00:00) caso receba um argumento inválido. O mesmo que toTime64, mas retorna o valor zero de Time64 caso receba um argumento inválido. Veja também:

toTime64.
toTime64OrNull.

Sintaxe

toTime64OrZero(x[, precision])

Argumentos

x — Uma representação textual de um horário com precisão de frações de segundo. String
precision — Opcional. A precisão de frações de segundo do valor retornado. UInt8

Valor retornado Retorna um valor Time64 em caso de sucesso; caso contrário, o valor Time64 zero (00:00:00) na precisão solicitada. Time64 Exemplos Exemplo de uso

Query

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

Response

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │              00:00:00.000 │
└────────────────────────────────┴───────────────────────────┘

toTimeOrNull

Introduzido em: v25.5.0 Converte um valor de entrada em um valor do tipo Time, mas retorna NULL em caso de erro. Semelhante a toTime, mas retorna NULL em vez de lançar uma exceção em caso de erro de conversão. Veja também:

toTime
toTimeOrZero

Sintaxe

toTimeOrNull(x)

Argumentos

x — Uma representação textual de um horário. String

Valor retornado Retorna um valor Time em caso de sucesso; caso contrário, NULL. Time ou NULL Exemplos Exemplo de uso

Query

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

Response

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

toTimeOrZero

Introduzido em: v25.5.0 Converte um valor de entrada em um valor do tipo Time, mas retorna 00:00:00 em caso de erro. Semelhante a toTime, mas retorna 00:00:00 em vez de lançar uma exceção em caso de erros de conversão. Sintaxe

toTimeOrZero(x)

Argumentos

x — Uma representação textual de um horário. String

Valor retornado Retorna um valor Time em caso de sucesso; caso contrário, 00:00:00. Time Exemplos Exemplo de uso

Query

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

Response

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

toUInt128

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo UInt128. Lança uma exceção em caso de erro. A função usa arredondamento em direção a zero, o que significa que trunca os dígitos fracionários dos números. Argumentos aceitos:

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

Argumentos não aceitos:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt128('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt128, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt128OrZero.
toUInt128OrNull.
toUInt128OrDefault.

Sintaxe

toUInt128(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro sem sinal de 128 bits. UInt128 Exemplos Exemplo de uso

Query

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Response

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

toUInt128OrDefault

Introduzido em: v21.11.0 Assim como toUInt128, esta função converte um valor de entrada em um valor do tipo UInt128, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toUInt128OrDefault(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. UInt128

Valor retornado Retorna um valor do tipo UInt128 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. UInt128 Exemplos Conversão bem-sucedida

Query

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

Response

Conversão malsucedida

Query

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

Response

toUInt128OrNull

Introduzido em: v21.6.0 Assim como toUInt128, esta função converte um valor de entrada para o tipo UInt128, mas retorna NULL em caso de erro. Argumentos suportados:

Representações em string de (U)Int*.

Argumentos não suportados (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt128OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt128, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt128.
toUInt128OrZero.
toUInt128OrDefault.

Sintaxe

toUInt128OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt128 ou NULL se a conversão não for bem-sucedida. UInt128 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): ᴺᵁᴸᴸ

toUInt128OrZero

Introduzido em: v1.1.0 Assim como toUInt128, esta função converte um valor de entrada em um valor do tipo UInt128, mas retorna 0 em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int*.

Argumentos não compatíveis (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt128OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado nos limites de UInt128, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt128.
toUInt128OrNull.
toUInt128OrDefault.

Sintaxe

toUInt128OrZero(x)

Argumentos

x — Uma string que representa um número. String

Valor retornado Retorna um valor do tipo UInt128; caso contrário, 0 se a conversão falhar. UInt128 Exemplos Exemplo de uso

Query

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

toUInt16

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo UInt16. Lança uma exceção em caso de erro. Argumentos suportados:

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

Argumentos não suportados:

Representações em string de valores do tipo Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo: SELECT toUInt16('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt16, ocorre overflow ou underflow no resultado. Isso não é considerado um erro. Por exemplo: SELECT toUInt16(65536) == 0;.

A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números.

Veja também:

toUInt16OrZero.
toUInt16OrNull.
toUInt16OrDefault.

Sintaxe

toUInt16(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro sem sinal de 16 bits. UInt16 Exemplos Exemplo de uso

Query

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Response

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

toUInt16OrDefault

Introduzido em: v21.11.0 Assim como toUInt16, esta função converte um valor de entrada em um valor do tipo UInt16, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toUInt16OrDefault(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. UInt16

Valor retornado Retorna um valor do tipo UInt16 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. UInt16 Exemplos Conversão bem-sucedida

Query

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

Response

Falha na conversão

Query

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

Response

toUInt16OrNull

Introduzido em: v1.1.0 Assim como toUInt16, esta função converte um valor de entrada em um valor do tipo UInt16, mas retorna NULL em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int8/16/32/128/256.

Argumentos não compatíveis (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt16OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt16, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt16.
toUInt16OrZero.
toUInt16OrDefault.

Sintaxe

toUInt16OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt16 ou NULL, caso a conversão não seja bem-sucedida. UInt16 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toUInt16OrNull('16'),
    toUInt16OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): ᴺᵁᴸᴸ

toUInt16OrZero

Introduzido em: v1.1.0 Assim como toUInt16, esta função converte um valor de entrada para um valor do tipo UInt16, mas retorna 0 em caso de erro. Argumentos suportados:

Representações em string de (U)Int8/16/32/128/256.

Argumentos não suportados (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt16OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt16, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt16.
toUInt16OrNull.
toUInt16OrDefault.

Sintaxe

toUInt16OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt16; caso a conversão não seja bem-sucedida, retorna 0. UInt16 Exemplos Exemplo de uso

Query

SELECT
    toUInt16OrZero('16'),
    toUInt16OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt16OrZero('16'):  16
toUInt16OrZero('abc'): 0

toUInt256

Introduzido em: v1.1.0 Converte um valor de entrada para o tipo UInt256. Lança uma exceção em caso de erro. A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números. Argumentos suportados:

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

Argumentos não suportados:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt256('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt256, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt256OrZero.
toUInt256OrNull.
toUInt256OrDefault.

Sintaxe

toUInt256(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro sem sinal de 256 bits. UInt256 Exemplos Exemplo de uso

Query

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Response

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

toUInt256OrDefault

Introduzido em: v21.11.0 Assim como toUInt256, esta função converte um valor de entrada em um valor do tipo UInt256, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toUInt256OrDefault(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 o parsing falhar. UInt256

Valor retornado Retorna um valor do tipo UInt256 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, caso não seja. UInt256 Exemplos Conversão bem-sucedida

Query

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

Response

Conversão malsucedida

Query

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

Response

toUInt256OrNull

Introduzido em: v20.8.0 Assim como toUInt256, esta função converte um valor de entrada em um valor do tipo UInt256, mas retorna NULL em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int*.

Argumentos não compatíveis (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt256OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt256, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt256.
toUInt256OrZero.
toUInt256OrDefault.

Sintaxe

toUInt256OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt256 ou NULL, se a conversão não for bem-sucedida. UInt256 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): ᴺᵁᴸᴸ

toUInt256OrZero

Introduzido em: v20.8.0 Assim como toUInt256, esta função converte um valor de entrada em um valor do tipo UInt256, mas retorna 0 em caso de erro. Argumentos suportados:

Representações em string de (U)Int*.

Argumentos não suportados (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt256OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt256, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt256.
toUInt256OrNull.
toUInt256OrDefault.

Sintaxe

toUInt256OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt256; caso a conversão não seja bem-sucedida, retorna 0. UInt256 Exemplos Exemplo de uso

Query

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

toUInt32

Introduzido em: v1.1.0 Converte um valor de entrada para um valor do tipo UInt32. Lança uma exceção em caso de erro. Argumentos suportados:

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

Argumentos não suportados:

Representações de string de valores Float*, incluindo NaN e Inf.
Representações de string de valores binários e hexadecimais, por exemplo, SELECT toUInt32('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt32, ocorre overflow ou underflow no resultado. Isso não é considerado um erro. Por exemplo: SELECT toUInt32(4294967296) == 0;

A função usa arredondamento em direção a zero, o que significa que ela trunca os dígitos fracionários dos números.

Veja também:

toUInt32OrZero.
toUInt32OrNull.
toUInt32OrDefault.

Sintaxe

toUInt32(expr)

Argumentos

expr — Expressão que retorna um número ou sua representação textual. Expressão

Valor retornado Retorna um valor inteiro sem sinal de 32 bits. UInt32 Exemplos Exemplo de uso

Query

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Response

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

toUInt32OrDefault

Introduzido em: v21.11.0 Assim como toUInt32, esta função converte um valor de entrada em um valor do tipo UInt32, mas retorna o valor padrão em caso de erro. Se nenhum valor default for fornecido, 0 será retornado em caso de erro. Sintaxe

toUInt32OrDefault(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 falhar. UInt32

Valor retornado Retorna um valor do tipo UInt32 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. UInt32 Exemplos Conversão bem-sucedida

Query

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

Response

Falha na conversão

Query

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

Response

toUInt32OrNull

Introduzido em: v1.1.0 Assim como toUInt32, esta função converte um valor de entrada em um valor do tipo UInt32, mas retorna NULL em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int8/16/32/128/256.

Argumentos não compatíveis (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt32OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt32, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt32.
toUInt32OrZero.
toUInt32OrDefault.

Sintaxe

toUInt32OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt32 ou NULL, se a conversão não for bem-sucedida. UInt32 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toUInt32OrNull('32'),
    toUInt32OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): ᴺᵁᴸᴸ

toUInt32OrZero

Introduzido em: v1.1.0 Assim como toUInt32, esta função converte um valor de entrada em um valor do tipo UInt32, mas retorna 0 em caso de erro. Argumentos aceitos:

Representações em string de (U)Int8/16/32/128/256.

Argumentos não aceitos (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt32OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt32, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt32.
toUInt32OrNull.
toUInt32OrDefault.

Sintaxe

toUInt32OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt32 ou 0, se a conversão falhar. UInt32 Exemplos Exemplo de uso

Query

SELECT
    toUInt32OrZero('32'),
    toUInt32OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt32OrZero('32'):  32
toUInt32OrZero('abc'): 0

toUInt64

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo UInt64. Lança uma exceção em caso de erro. Argumentos aceitos:

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

Tipos não suportados:

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt64('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt64, o resultado sofrerá overflow ou underflow. Isso não é considerado um erro. Por exemplo: SELECT toUInt64(18446744073709551616) == 0;

A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números.

Veja também:

toUInt64OrZero.
toUInt64OrNull.
toUInt64OrDefault.

Sintaxe

toUInt64(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro sem sinal de 64 bits. UInt64 Exemplos Exemplo de uso

Query

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Response

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

toUInt64OrDefault

Introduzido em: v21.11.0 Assim como toUInt64, esta função converte um valor de entrada em um valor do tipo UInt64, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toUInt64OrDefault(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. UInt64

Valor retornado Retorna um valor do tipo UInt64 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. UInt64 Exemplos Conversão bem-sucedida

Query

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

Response

Falha na conversão

Query

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

Response

toUInt64OrNull

Introduzido em: v1.1.0 Assim como toUInt64, esta função converte um valor de entrada em um valor do tipo UInt64, mas retorna NULL em caso de erro. Argumentos suportados:

Representações em string de (U)Int*.

Argumentos não suportados (retornam NULL):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt64OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt64, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt64.
toUInt64OrZero.
toUInt64OrDefault.

Sintaxe

toUInt64OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt64; caso a conversão não seja bem-sucedida, retorna NULL. UInt64 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): ᴺᵁᴸᴸ

toUInt64OrZero

Introduzido em: v1.1.0 Como toUInt64, esta função converte um valor de entrada em um valor do tipo UInt64, mas retorna 0 em caso de erro. Argumentos compatíveis:

Representações em string de (U)Int*.

Argumentos não compatíveis (retornam 0):

Representações em string de valores Float*, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt64OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt64, ocorrerá overflow ou underflow do resultado. Isso não é considerado um erro.

Veja também:

toUInt64.
toUInt64OrNull.
toUInt64OrDefault.

Sintaxe

toUInt64OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt64 ou 0 se a conversão não for bem-sucedida. UInt64 Exemplos Exemplo de uso

Query

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

toUInt8

Introduzido em: v1.1.0 Converte um valor de entrada em um valor do tipo UInt8. Lança uma exceção em caso de erro. Argumentos aceitos:

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

Argumentos não aceitos:

Representações textuais de valores Float*, incluindo NaN e Inf.
Representações textuais de valores binários e hexadecimais, por exemplo, SELECT toUInt8('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt8, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro. Por exemplo: SELECT toUInt8(256) == 0;.

A função usa arredondamento em direção a zero, ou seja, trunca os dígitos fracionários dos números.

Veja também:

toUInt8OrZero.
toUInt8OrNull.
toUInt8OrDefault.

Sintaxe

toUInt8(expr)

Argumentos

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

Valor retornado Retorna um valor inteiro sem sinal de 8 bits. UInt8 Exemplos Exemplo de uso

Query

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Response

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

toUInt8OrDefault

Introduzido em: v21.11.0 Assim como toUInt8, esta função converte um valor de entrada em um valor do tipo UInt8, mas retorna o valor padrão em caso de erro. Se nenhum valor default for informado, 0 será retornado em caso de erro. Sintaxe

toUInt8OrDefault(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 falhar. UInt8

Valor retornado Retorna um valor do tipo UInt8 em caso de sucesso; caso contrário, retorna o valor padrão, se fornecido, ou 0, se não. UInt8 Exemplos Conversão bem-sucedida

Query

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

Response

Falha na conversão

Query

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

Response

toUInt8OrNull

Introduzido em: v1.1.0 Assim como toUInt8, esta função converte um valor de entrada em um valor do tipo UInt8, mas retorna NULL em caso de erro. Argumentos suportados:

Representações em string de (U)Int8/16/32/128/256.

Argumentos não suportados (retornam NULL):

Representações em string de valores Float* convencionais, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo: SELECT toUInt8OrNull('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt8, ocorrerá overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt8.
toUInt8OrZero.
toUInt8OrDefault.

Sintaxe

toUInt8OrNull(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt8 ou NULL se a conversão não for bem-sucedida. UInt8 ou NULL Exemplos Exemplo de uso

Query

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): ᴺᵁᴸᴸ

toUInt8OrZero

Introduzido em: v1.1.0 Assim como toUInt8, esta função converte um valor de entrada em um valor do tipo UInt8, mas retorna 0 em caso de erro. Argumentos com suporte:

Representações em string de (U)Int8/16/32/128/256.

Argumentos sem suporte (retornam 0):

Representações em string de valores Float* comuns, incluindo NaN e Inf.
Representações em string de valores binários e hexadecimais, por exemplo, SELECT toUInt8OrZero('0xc0fe');.

Se o valor de entrada não puder ser representado dentro dos limites de UInt8, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.

Veja também:

toUInt8.
toUInt8OrNull.
toUInt8OrDefault.

Sintaxe

toUInt8OrZero(x)

Argumentos

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

Valor retornado Retorna um valor do tipo UInt8; se a conversão falhar, retorna 0. UInt8 Exemplos Exemplo de uso

Query

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

toUUID

Introduzido em: v1.1.0 Converte um valor do tipo String em um valor UUID. Sintaxe

toUUID(string)

Argumentos

string — UUID em formato de string. String ou FixedString

Valor retornado Retorna um UUID a partir da representação em string do UUID. UUID Exemplos Exemplo de uso

Query

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

Response

┌─uuid─────────────────────────────────┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrZero

Introduzido em: v20.12.0 Converte um valor de entrada em um valor do tipo UUID, mas retorna um UUID zero em caso de erro. Semelhante a toUUID, mas retorna um UUID zero (00000000-0000-0000-0000-000000000000) em vez de lançar uma exceção em erros de conversão. Argumentos suportados:

Representações de UUID em formato de string no formato padrão (8-4-4-4-12 dígitos hexadecimais).
Representações de UUID em formato de string sem hífens (32 dígitos hexadecimais).

Argumentos não suportados (retornam UUID zero):

Formatos de string inválidos.
Tipos que não são string.

Sintaxe

toUUIDOrZero(x)

Argumentos

x — Uma representação textual de um UUID. String

Valor retornado Retorna um valor UUID em caso de sucesso; caso contrário, retorna um UUID zero (00000000-0000-0000-0000-000000000000). UUID Exemplos Exemplo de uso

Query

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

toUnixTimestamp64Micro

Introduzido em: v20.5.0 Converte um DateTime64 em um valor Int64 com precisão fixa de microssegundos. O valor de entrada é ampliado ou reduzido conforme necessário, dependendo da sua precisão.

O valor de saída é relativo a UTC, não ao fuso horário do valor de entrada.

Sintaxe

toUnixTimestamp64Micro(value)

Argumentos

value — Valor do tipo DateTime64 com qualquer precisão. DateTime64

Valor retornado Retorna um timestamp Unix em microssegundos. Int64 Exemplos Exemplo de uso

Query

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

Response

┌─toUnixTimestamp64Micro(dt64)─┐
│             1739489491011123 │
└──────────────────────────────┘

toUnixTimestamp64Milli

Introduzido em: v20.5.0 Converte um DateTime64 em um valor Int64 com precisão fixa de milissegundos. O valor de entrada é ajustado para mais ou para menos conforme necessário, dependendo da sua precisão.

O valor de saída é relativo a UTC, não ao fuso horário do valor de entrada.

Sintaxe

toUnixTimestamp64Milli(value)

Argumentos

value — Valor do tipo DateTime64 com qualquer precisão. DateTime64

Valor retornado Retorna um timestamp Unix em milissegundos. Int64 Exemplos Exemplo de uso

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

Response

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

toUnixTimestamp64Nano

Introduzido em: v20.5.0 Converte um DateTime64 em um valor Int64 com precisão fixa em nanossegundos. O valor de entrada é ajustado para mais ou para menos conforme necessário, dependendo da sua precisão.

O valor de saída é relativo a UTC, não ao fuso horário do valor de entrada.

Sintaxe

toUnixTimestamp64Nano(value)

Argumentos

value — Valor do tipo DateTime64 com qualquer precisão. DateTime64

Valor retornado Retorna um timestamp Unix em nanossegundos. Int64 Exemplos Exemplo de uso

Query

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

Response

┌─toUnixTimestamp64Nano(dt64)─┐
│         1739489491011123456 │
└─────────────────────────────┘

toUnixTimestamp64Second

Introduzido na versão: v24.12.0 Converte um DateTime64 em um valor Int64 com precisão fixa de segundos. O valor de entrada é ajustado para mais ou para menos conforme necessário, dependendo da sua precisão.

O valor de saída é relativo a UTC, não ao fuso horário do valor de entrada.

Sintaxe

toUnixTimestamp64Second(value)

Argumentos

value — Valor do tipo DateTime64 com qualquer precisão. DateTime64

Valor retornado Retorna um timestamp Unix em segundos. Int64 Exemplos Exemplo de uso

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

Response

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘

Última modificação em 26 de setembro de 2026

​Problemas comuns na conversão de dados

​Observações sobre as funções toString

​Observações sobre as funções toDate/toDateTime

​CAST

​DATE

​accurateCast

​accurateCastOrDefault

​accurateCastOrNull

​formatRow

​formatRowNoNewline

​fromUnixTimestamp64Micro

​fromUnixTimestamp64Milli

​fromUnixTimestamp64Nano

​fromUnixTimestamp64Second

​kqlParameterCast

​kqlToTimespan

​parseDateTime

​parseDateTime32BestEffort

​parseDateTime32BestEffortOrNull

​parseDateTime32BestEffortOrZero

​parseDateTime64

​parseDateTime64BestEffort

​parseDateTime64BestEffortOrNull

​parseDateTime64BestEffortOrZero

​parseDateTime64BestEffortUS

​parseDateTime64BestEffortUSOrNull

​parseDateTime64BestEffortUSOrZero

​parseDateTime64InJodaSyntax

​parseDateTime64InJodaSyntaxOrNull

​parseDateTime64InJodaSyntaxOrZero

​parseDateTime64OrNull

​parseDateTime64OrZero

​parseDateTimeBestEffort

​parseDateTimeBestEffortOrNull

​parseDateTimeBestEffortOrZero

​parseDateTimeBestEffortUS

​parseDateTimeBestEffortUSOrNull

​parseDateTimeBestEffortUSOrZero

​parseDateTimeInJodaSyntax

​parseDateTimeInJodaSyntaxOrNull

​parseDateTimeInJodaSyntaxOrZero

​parseDateTimeOrNull

​parseDateTimeOrZero

​reinterpret

​reinterpretAsDate

​reinterpretAsDateTime

​reinterpretAsFixedString

​reinterpretAsFloat32

​reinterpretAsFloat64

​reinterpretAsInt128

​reinterpretAsInt16

​reinterpretAsInt256

​reinterpretAsInt32

​reinterpretAsInt64

​reinterpretAsInt8

​reinterpretAsString

​reinterpretAsUInt128

​reinterpretAsUInt16

​reinterpretAsUInt256

​reinterpretAsUInt32

​reinterpretAsUInt64

​reinterpretAsUInt8

​reinterpretAsUUID

​toBFloat16

​toBFloat16OrNull

​toBFloat16OrZero

​toBool

​toDate

​toDate32

​toDate32OrDefault

​toDate32OrNull

​toDate32OrZero

​toDateOrDefault

​toDateOrNull

​toDateOrZero

​toDateTime

​toDateTime32

​toDateTime64

​toDateTime64OrDefault

​toDateTime64OrNull

Problemas comuns na conversão de dados

Observações sobre as funções `toString`

Observações sobre as funções `toDate`/`toDateTime`

CAST

DATE

accurateCast

accurateCastOrDefault

accurateCastOrNull

formatRow

formatRowNoNewline

fromUnixTimestamp64Micro

fromUnixTimestamp64Milli

fromUnixTimestamp64Nano

fromUnixTimestamp64Second

kqlParameterCast

kqlToTimespan

parseDateTime

parseDateTime32BestEffort

parseDateTime32BestEffortOrNull

parseDateTime32BestEffortOrZero

parseDateTime64

parseDateTime64BestEffort

parseDateTime64BestEffortOrNull

parseDateTime64BestEffortOrZero

parseDateTime64BestEffortUS

parseDateTime64BestEffortUSOrNull

parseDateTime64BestEffortUSOrZero

parseDateTime64InJodaSyntax

parseDateTime64InJodaSyntaxOrNull

parseDateTime64InJodaSyntaxOrZero

parseDateTime64OrNull

parseDateTime64OrZero

parseDateTimeBestEffort

parseDateTimeBestEffortOrNull

parseDateTimeBestEffortOrZero

parseDateTimeBestEffortUS

parseDateTimeBestEffortUSOrNull

parseDateTimeBestEffortUSOrZero

parseDateTimeInJodaSyntax

parseDateTimeInJodaSyntaxOrNull

parseDateTimeInJodaSyntaxOrZero

parseDateTimeOrNull

parseDateTimeOrZero

reinterpret

reinterpretAsDate

reinterpretAsDateTime

reinterpretAsFixedString

reinterpretAsFloat32

reinterpretAsFloat64

reinterpretAsInt128

reinterpretAsInt16

reinterpretAsInt256

reinterpretAsInt32

reinterpretAsInt64

reinterpretAsInt8

reinterpretAsString

reinterpretAsUInt128

reinterpretAsUInt16

reinterpretAsUInt256

reinterpretAsUInt32

reinterpretAsUInt64

reinterpretAsUInt8

reinterpretAsUUID

toBFloat16

toBFloat16OrNull

toBFloat16OrZero

toBool

toDate

toDate32

toDate32OrDefault

toDate32OrNull

toDate32OrZero

toDateOrDefault

toDateOrNull

toDateOrZero

toDateTime

toDateTime32

toDateTime64

toDateTime64OrDefault

toDateTime64OrNull