Pular para o conteúdo principal

​
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 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 dados 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 dados 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', 999)─┐
│                                         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 │
└───────────────────────────────────────┘

​
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─┐
│       2015-07-07 12:04:41 │
└───────────────────────────┘

​
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 1900 a 2299 com precisão de subsegundos. 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.123       │
└─────────────────────────────────────────────────────────────────────┘

​
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 1900 a 2299 com precisão de frações de segundo. 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 convertida 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 analisado 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 que não pode ser analisado. Sintaxe 
parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])
Argumentos
  • time_string — String a ser convertida 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 interpretado 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 que não pode ser interpretado. Sintaxe 
parseDateTime64OrNull(time_string, format[, timezone])
Argumentos
  • time_string — String a ser convertida 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.123        │
└───────────────────────────────────────────────────────────────────────────┘

​
parseDateTime64OrZero

Introduzido em: v24.11.0 Igual a parseDateTime64, mas retorna uma data zero quando encontra um formato de data que não pode ser analisado. Sintaxe 
parseDateTime64OrZero(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 o DateTime64 interpretado 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.123       │
└───────────────────────────────────────────────────────────────────────────┘

​
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 que não pode ser analisado. 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 que não pode ser analisado. 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. Sintaxe 
reinterpret(x, type)
Argumentos
  • x — Qualquer tipo. 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]  │
└────────────────────────────┘

​
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 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 Valor retornado Data e hora. DateTime Exemplos Exemplo de uso
Query
SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')
Response
┌─reinterpretAsDateTime(65)─┬─reinterpretAsDateTime('A')─┐
│       1970-01-01 01:01:05 │        1970-01-01 01: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 Valor retornado String fixa que contém os bytes que representam x. FixedString Exemplos Exemplo de uso
Query
SELECT
    reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05')),
    reinterpretAsFixedString(toDate('1970-03-07'))
Response
┌─reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsFixedString(toDate('1970-03-07'))─┐
│ A                                                           │ A                                              │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘

​
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 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 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 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 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 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 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 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 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 (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 
reinterpretAsString(x)
Argumentos Valor retornado String contendo os bytes que representam x. String Exemplos Exemplo de uso
Query
SELECT
    reinterpretAsString(toDateTime('1970-01-01 01:01:05')),
    reinterpretAsString(toDate('1970-03-07'))
Response
┌─reinterpretAsString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsString(toDate('1970-03-07'))─┐
│ A                                                      │ A                                         │
└────────────────────────────────────────────────────────┴───────────────────────────────────────────┘

​
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 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 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 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 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 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 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: 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
toBFloat16(toFloat32(42.7)): 42.5
toBFloat16(t⋯32('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: 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'), -- argumentos sem suporte
       toBFloat16OrNull('12.3'), -- uso típico
       toBFloat16OrNull('12.3456789') -- perda silenciosa de precisão
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: 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'), -- argumentos sem suporte
       toBFloat16OrZero('12.3'), -- uso comum
       toBFloat16OrZero('12.3456789') -- perda silenciosa de precisão
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
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 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, 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 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
Linha 1:
──────
value:           2025-01-01
toTypeName(value): Date32
Fora do intervalo
Query
SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT Vertical
Response
Linha 1:
──────
value:           1900-01-01
toTypeName(value): Date32

​
toDate32OrDefault

Introduzido em: v21.11.0 Converte o argumento para o tipo de dado Date32. Se o valor estiver fora do intervalo, toDate32OrDefault retornará o valor do limite inferior compatível com Date32. Se o argumento for do tipo Date, os limites desse tipo serão levados em consideração. Retorna o valor padrão se um argumento inválido for recebido. 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

​
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 limite inferior de Date32 se receber um argumento inválido. É igual a toDate32, mas retorna o limite inferior de Date32 se receber um argumento inválido. Veja também: 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 limite inferior de Date32 (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. Sintaxe 
toDateOrNull(x)
Argumentos
  • x — Uma representação textual de uma data. String
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: 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.
Sintaxe 
toDateTime(expr[, time_zone])
Argumentos 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
Linha 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 na versão: v20.9.0 Converte um valor de entrada para o tipo DateTime. Suporta a conversão de String, FixedString, Date, Date32, DateTime ou tipos numéricos ((U)Int*, Float*, Decimal). DateTime32 oferece um intervalo maior em comparação com DateTime, com suporte a datas de 1900-01-01 a 2299-12-31. Sintaxe 
toDateTime32(x[, timezone])
Argumentos Valor retornado Retorna o valor de entrada convertido. DateTime 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(toDateTime64('20255-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                                          │
└─────────────────────────┴────────────────────────────────────────────────────────┘
Como Decimal com precisão
Query
SELECT toDateTime64(1735689600.000, 3) AS value, toTypeName(value);
-- sem o separador decimal, o valor ainda é tratado como Unix Timestamp em segundos
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);
Response
┌───────────────────value─┬─toTypeName(toDateTime64(1735689600.000, 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                            │
└─────────────────────────┴──────────────────────────────────────────┘
┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ 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(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, '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(toDateTime64('2025-01-01 00:00:00.000', 3))─┐
│ 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);
-- Sem o separador decimal, o valor ainda é interpretado como timestamp Unix em segundos
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);
Response
┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ 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(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 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
2000-12-31 23: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. Sintaxe 
toDateTime64OrNull(x)
Argumentos
  • x — Uma representação textual de uma data e hora com precisão de frações de segundo. 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 limite inferior de DateTime64 se receber um argumento inválido. Igual a toDateTime64, mas retorna o limite inferior de DateTime64 se receber um argumento inválido. Veja também: Sintaxe 
toDateTime64OrZero(x)
Argumentos
  • x — Uma representação textual de uma data com hora e precisão de frações de segundo. String
Valor retornado Retorna um valor DateTime64 em caso de sucesso; caso contrário, o limite inferior de DateTime64 (1970-01-01 00:00:00.000). DateTime64 Exemplos Exemplo de uso
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. Sintaxe 
toDateTimeOrNull(x)
Argumentos
  • x — Uma representação textual de uma data com hora. 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 │                        ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘

​
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
Linha 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: 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.70 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

​
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.70 │                             0.00 │
└───────────────────────────────┴──────────────────────────────────┘

​
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
Linha 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: 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.70 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

​
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: 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.70 │                             0.00 │
└───────────────────────────────┴──────────────────────────────────┘

​
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
Linha 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: 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.70 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

​
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.70 │                            0.00 │
└──────────────────────────────┴─────────────────────────────────┘

​
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
Linha 1:
──────
a:      2.0
type_a: Decimal(18, 1)
b:      4.20
type_b: Decimal(18, 2)
c:      4.200
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: 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.70 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

​
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: 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.70 │                            0.00 │
└──────────────────────────────┴─────────────────────────────────┘

​
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
SELECT toFixedString('foo', 8) AS s;
Response
┌─s─────────────┐
│ foo\0\0\0\0\0 │
└───────────────┘

​
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: 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
8
Falha na conversão
Query
SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))
Response
0

​
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: 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
Linha 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  \N

​
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: 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: 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
8
Falha na conversão
Query
SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))
Response
0

​
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: 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
Linha 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'):  nan
toFloat64OrNull('abc'):  \N

​
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: 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: 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
Linha 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: 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
Linha 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'):  \N

​
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: Sintaxe 
toInt128OrZero(x)
Argumentos 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
123
Conversões com falha retornam zero
Query
SELECT toInt128OrZero('abc')
Response
0

​
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: 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
Linha 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: 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
Linha 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): \N

​
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: 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
Linha 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: 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
Linha 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: 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
Linha 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'):  \N

​
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: Sintaxe 
toInt256OrZero(x)
Argumentos 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
123
Conversões com falha retornam zero
Query
SELECT toInt256OrZero('abc')
Response
0

​
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: 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
Linha 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: 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
Linha 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): \N

​
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: 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
Linha 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: 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: 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
Linha 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): \N

​
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: Sintaxe 
toInt64OrZero(x)
Argumentos 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
123
Em caso de falha na conversão, retorna zero
Query
SELECT toInt64OrZero('abc')
Response
0

​
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: 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
Linha 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: 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
Linha 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): \N

​
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: 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
Linha 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 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 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 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 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 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 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 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 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 textual. 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 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: v1.1.0 Converte um valor de entrada para o tipo Time. Suporta conversão de String, FixedString, DateTime ou tipos numéricos que representam segundos desde a meia-noite. Sintaxe 
toTime(x)
Argumentos Valor retornado Retorna o valor convertido. Time Exemplos Conversão de String em Time
Query
SELECT toTime('14:30:25')
Response
14:30:25
Conversão de DateTime para Time
Query
SELECT toTime(toDateTime('2025-04-15 14:30:25'))
Response
14:30:25
Conversão de inteiro em Time
Query
SELECT toTime(52225)
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 microssegundos desde a meia-noite. Fornece precisão de microssegundos para valores de hora. Sintaxe 
toTime64(x)
Argumentos Valor retornado Retorna o valor de entrada convertido com precisão de microssegundos. Time64(6) Exemplos Conversão de String em Time64
Query
SELECT toTime64('14:30:25.123456')
Response
14:30:25.123456
Conversão de DateTime64 para Time64
Query
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))
Response
14:30:25.123456
Conversão de inteiro para Time64
Query
SELECT toTime64(52225123456)
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 gerar uma exceção em caso de erro de conversão. Veja também: Sintaxe 
toTime64OrNull(x)
Argumentos
  • x — Uma representação textual de um horário com precisão de subsegundos. String
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 00:00:00.000 em caso de erro. Semelhante a toTime64, mas retorna 00:00:00.000 em vez de lançar uma exceção em caso de erro de conversão. Sintaxe 
toTime64OrZero(x)
Argumentos
  • x — Uma representação textual de um horário com precisão de subsegundos. String
Valor retornado Retorna um valor Time64 em caso de sucesso; caso contrário, 00:00:00.000. 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: v1.1.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: 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: v1.1.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: 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
Linha 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
128
Conversão malsucedida
Query
SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))
Response
0

​
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 nos limites de UInt128, ocorre overflow ou underflow no resultado. Isso não é considerado um erro.
Veja também: 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
Linha 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

​
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: 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
Linha 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: 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
Linha 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
16
Falha na conversão
Query
SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))
Response
0

​
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: 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
Linha 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): \N

​
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: 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
Linha 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: 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
Linha 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
0
Conversão malsucedida
Query
SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))
Response
0

​
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: 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
Linha 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

​
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: 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
Linha 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: 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
Linha 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
32
Falha na conversão
Query
SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))
Response
0

​
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: 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
Linha 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

​
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: 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
Linha 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: 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
Linha 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
64
Falha na conversão
Query
SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))
Response
0

​
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: 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
Linha 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

​
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: 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
Linha 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: 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
Linha 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
8
Falha na conversão
Query
SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))
Response
0

​
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: 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
Linha 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

​
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: 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
Linha 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 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 10 de junho de 2026