DateTime64

Documentação do tipo de dado DateTime64 no ClickHouse, que armazena timestamps com precisão de frações de segundo

Permite armazenar um instante, que pode ser expresso como uma data de calendário e uma hora do dia, com precisão de frações de segundo definida

Tamanho do tick (precisão): 10^-precision segundos. Intervalo válido: [ 0 : 9 ]. Normalmente, usam-se 3 (milissegundos), 6 (microssegundos) e 9 (nanossegundos).

Valor padrão: 3 (milissegundos).

Sintaxe:

DateTime64(precision, [timezone])

Internamente, armazena os dados como uma quantidade de ‘ticks’ desde o início da epoch (1970-01-01 00:00:00 UTC) como Int64. A resolução dos ticks é determinada pelo parâmetro de precisão. Além disso, o tipo DateTime64 pode armazenar um fuso horário que é o mesmo para toda a coluna, o que afeta como os valores do tipo DateTime64 são exibidos em formato de texto e como os valores especificados como strings são analisados (‘2020-01-01 05:00:01.000’). O fuso horário não é armazenado nas linhas da tabela (ou no conjunto de resultados), mas nos metadados da coluna. Veja os detalhes em DateTime.

Intervalo de valores compatível: [0000-01-01 00:00:00, 9999-12-31 23:59:59.999999999]

O número de dígitos após o separador decimal depende do parâmetro de precisão.

Observação: o intervalo completo acima está disponível para precisões de até 7. Como os ticks são armazenados em um Int64, precisões mais altas abrangem um intervalo mais estreito: com precisão 8, o valor máximo é aproximadamente 4892-10-07, e com a precisão máxima de 9 dígitos (nanossegundos), o intervalo compatível é de 1677-09-21 00:12:44 a 2262-04-11 23:47:16 em UTC.

​

Exemplos

1. Criando uma tabela com uma coluna do tipo DateTime64 e inserindo dados nela:

CREATE TABLE dt64
(
    `timestamp` DateTime64(3, 'Asia/Istanbul'),
    `event_id` UInt8
)
ENGINE = MergeTree;

-- Parse DateTime64
-- - from an integer interpreted as the number of seconds since 1970-01-01 (like DateTime),
-- - from a decimal interpreted as the number of seconds, the fractional part giving sub-second precision,
-- - from a string.

INSERT INTO dt64
VALUES
(1546300800, 1),
(1546300800.123, 2),
('2019-01-01 00:00:00', 3);

SELECT * FROM dt64;

┌───────────────timestamp─┬─event_id─┐
│ 2019-01-01 03:00:00.000 │        1 │
│ 2019-01-01 03:00:00.123 │        2 │
│ 2019-01-01 00:00:00.000 │        3 │
└─────────────────────────┴──────────┘

• Ao inserir um datetime como número, ele é tratado como um Unix Timestamp (UTC) em segundos, como DateTime. 1546300800 representa '2019-01-01 00:00:00' UTC. No entanto, como a coluna timestamp tem o fuso horário Asia/Istanbul (UTC+3) especificado, ao ser exibido como string, o valor será mostrado como '2019-01-01 03:00:00'. Inserir um número com uma parte fracionária funciona da mesma forma: a parte antes do separador decimal é o Unix Timestamp em segundos, e a parte após ele fornece precisão de frações de segundo de acordo com a precisão da coluna. (Antes da versão 26.8, um inteiro simples sem aspas nos caminhos de entrada JSON e Values/Quoted — este último abrangendo todos os formatos que analisam campos com a regra de escape Quoted: Values, MySQLDump e Template/CustomSeparated/Regexp configurados com escape de campo Quoted — era interpretado como o valor bruto subjacente na precisão da coluna; portanto, 1546300800000 com precisão 3 significava '2019-01-01 00:00:00'. Para restaurar o comportamento anterior nesses caminhos, defina input_format_read_datetime_number_as_raw_value = 1 (ou SET compatibility = '26.7'); isso também afeta a função JSONExtract e o tipo de dados JSON. A configuração de compatibilidade rege apenas um inteiro simples: no formato Values, um número fracionário, que o parser de streaming legado rejeita, recorre à avaliação de expressão SQL e é lido como segundos — da mesma forma que nas versões anteriores a 26.8. Em JSONExtract e no tipo de dados JSON, um valor fracionário é analisado por meio de Float64; portanto, um timestamp com mais dígitos do que Float64 consegue preservar pode ser arredondado para o valor adjacente, diferentemente dos formatos de entrada baseados em linhas, que analisam o texto original exatamente. Os formatos de entrada de texto separados por tabulação, CSV e outros formatos de texto com escape não são regidos por essa configuração e mantêm sua interpretação atual de um número sem aspas: um valor grande é lido como ticks.)
• Ao inserir um valor em string como datetime, ele é tratado como estando no fuso horário da coluna. '2019-01-01 00:00:00' será tratado como estando no fuso horário Asia/Istanbul e armazenado como 1546290000000.

2. Filtragem por valores DateTime64

SELECT * FROM dt64 WHERE timestamp = toDateTime64('2019-01-01 00:00:00', 3, 'Asia/Istanbul');

┌───────────────timestamp─┬─event_id─┐
│ 2019-01-01 00:00:00.000 │        3 │
└─────────────────────────┴──────────┘

Diferentemente de DateTime, os valores DateTime64 não são convertidos automaticamente a partir de String.

SELECT * FROM dt64 WHERE timestamp = toDateTime64(1546300800.123, 3);

┌───────────────timestamp─┬─event_id─┐
│ 2019-01-01 03:00:00.123 │        1 │
│ 2019-01-01 03:00:00.123 │        2 │
└─────────────────────────┴──────────┘

Assim como ao inserir um número, a função toDateTime64 trata um argumento numérico como um número de segundos, portanto, a precisão de subsegundos deve ser informada após o separador decimal.

3. Obtendo o fuso horário de um valor do tipo DateTime64:

SELECT toDateTime64(now(), 3, 'Asia/Istanbul') AS column, toTypeName(column) AS x;

┌──────────────────column─┬─x──────────────────────────────┐
│ 2023-06-05 00:09:52.000 │ DateTime64(3, 'Asia/Istanbul') │
└─────────────────────────┴────────────────────────────────┘

4. Conversão de fuso horário

SELECT
toDateTime64(timestamp, 3, 'Europe/London') AS lon_time,
toDateTime64(timestamp, 3, 'Asia/Istanbul') AS istanbul_time
FROM dt64;

┌────────────────lon_time─┬───────────istanbul_time─┐
│ 2019-01-01 00:00:00.123 │ 2019-01-01 03:00:00.123 │
│ 2019-01-01 00:00:00.123 │ 2019-01-01 03:00:00.123 │
│ 2018-12-31 21:00:00.000 │ 2019-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

Veja também

• Funções de conversão de tipos
• Funções para trabalhar com datas e horas
• A configuração date_time_input_format
• A configuração date_time_output_format
• O parâmetro timezone da configuração do servidor
• A configuração session_timezone
• Operadores para trabalhar com datas e horas
• Tipo de dado Date
• Tipo de dado DateTime