DateTime64 | ClickHouse Docs

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

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.

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.

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

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