DateTime

Documentação sobre o tipo de dado DateTime no ClickHouse, que armazena timestamps com precisão de segundos

Permite armazenar um instante no tempo, que pode ser expresso como uma data de calendário e uma hora do dia.

Sintaxe:

DateTime([timezone])

Faixa de valores suportada: [1970-01-01 00:00:00, 2106-02-07 06:28:15].

Resolução: 1 segundo.

​

Velocidade

O tipo de dados Date é mais rápido que DateTime na maioria dos casos.

O tipo Date requer 2 bytes de armazenamento, enquanto DateTime requer 4. No entanto, durante a compressão, a diferença de tamanho entre Date e DateTime se torna mais significativa. Isso ocorre porque os minutos e segundos em DateTime são menos compressíveis. Filtrar e agregar Date em vez de DateTime também é mais rápido.

​

Observações de uso

O instante no tempo é salvo como um Unix timestamp, independentemente do fuso horário ou do horário de verão. O fuso horário afeta como os valores do tipo DateTime são exibidos em formato de texto e como os valores especificados como strings são interpretados ('2020-01-01 05:00:01').

Um Unix timestamp independente de fuso horário é armazenado nas tabelas, e o fuso horário é usado para convertê-lo para o formato de texto ou de volta durante a importação/exportação de dados, ou para fazer cálculos de calendário com os valores (exemplo: funções toDate, toHour etc.). O fuso horário não é armazenado nas linhas da tabela (nem no conjunto de resultados), mas nos metadados da coluna.

Uma lista dos fusos horários compatíveis pode ser encontrada no IANA Time Zone Database e também pode ser consultada com SELECT * FROM system.time_zones. A lista também está disponível na Wikipedia.

Você pode definir explicitamente um fuso horário para colunas do tipo DateTime ao criar uma tabela. Exemplo: DateTime('UTC'). Se o fuso horário não for definido, o ClickHouse usa o valor do parâmetro timezone nas configurações do servidor ou nas configurações do sistema operacional no momento da inicialização do ClickHouse server.

O clickhouse-client aplica o fuso horário do servidor por padrão se um fuso horário não for explicitamente definido ao inicializar o tipo de dado. Para usar o fuso horário do cliente, execute clickhouse-client com o parâmetro --use_client_time_zone.

O ClickHouse gera valores de acordo com o valor da configuração date_time_output_format. O formato de texto YYYY-MM-DD hh:mm:ss é usado por padrão. Além disso, você pode alterar a saída com a função formatDateTime.

Ao inserir dados no ClickHouse, você pode usar diferentes formatos de strings de data e hora, dependendo do valor da configuração date_time_input_format.

​

Exemplos

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

CREATE TABLE dt
(
    `timestamp` DateTime('Asia/Istanbul'),
    `event_id` UInt8
)
ENGINE = TinyLog;

-- Parse DateTime
-- - from a string,
-- - from a number interpreted as the number of seconds since 1970-01-01 (a fractional part is truncated to whole seconds).
INSERT INTO dt VALUES ('2019-01-01 00:00:00', 1), (1546300800, 2);

SELECT * FROM dt;

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

• Ao inserir um datetime como número, ele é tratado como Unix timestamp (UTC) em segundos. 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'. Um número com parte fracionária ou expoente também é aceito e truncado para segundos inteiros, de forma consistente com CAST, toDateTime e o formato Values. (Antes da versão 26.8, esse número fracionário ou com expoente nos caminhos de entrada JSON e Values/Quoted — este último abrangendo todos os formatos que analisam campos com a regra de escaping Quoted: Values, MySQLDump e Template/CustomSeparated/Regexp configurados com escaping de campo Quoted — não era aceito pelo parser de streaming; defina input_format_read_datetime_number_as_raw_value = 1 para restaurar esse comportamento. No próprio formato Values, esse literal ainda funcionava — e continua funcionando no modo de compatibilidade — por meio do fallback de expressão SQL, que o lê como um número de segundos. Em JSONExtract e no tipo de dados JSON, um valor fracionário é convertido por meio de Float64, portanto, um valor próximo ao limite de um segundo inteiro pode ser arredondado para o segundo adjacente, diferentemente dos formatos de entrada por linha, que truncam exatamente o texto original. Os formatos de texto separados por tabulação, CSV e outros formatos de texto com escaping não são regidos por essa configuração.)
• 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 salvo como 1546290000.

2. Filtragem de valores DateTime

SELECT * FROM dt WHERE timestamp = toDateTime('2019-01-01 00:00:00', 'Asia/Istanbul')

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

Os valores da coluna DateTime podem ser filtrados usando um valor em formato de string no predicado WHERE. Ele será convertido automaticamente para DateTime:

SELECT * FROM dt WHERE timestamp = '2019-01-01 00:00:00'

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

3. Como obter o fuso horário de uma coluna do tipo DateTime:

SELECT toDateTime(now(), 'Asia/Istanbul') AS column, toTypeName(column) AS x

┌──────────────column─┬─x─────────────────────────┐
│ 2019-10-16 04:12:04 │ DateTime('Asia/Istanbul') │
└─────────────────────┴───────────────────────────┘

4. Conversão de fusos horários

SELECT
toDateTime(timestamp, 'Europe/London') AS lon_time,
toDateTime(timestamp, 'Asia/Istanbul') AS istanbul_time
FROM dt

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

Como a conversão de fuso horário altera apenas os metadados, a operação não tem custo computacional.

​

Limitações no suporte a fusos horários

Alguns fusos horários podem não ter suporte completo. Há alguns casos:

Se o deslocamento em relação a UTC não for um múltiplo de 15 minutos, o cálculo de horas e minutos pode ficar incorreto. Por exemplo, o fuso horário de Monrovia, na Libéria, tinha deslocamento de UTC -0:44:30 antes de 7 Jan 1972. Se você estiver fazendo cálculos com horários históricos no fuso horário de Monrovia, as funções de processamento de tempo poderão retornar resultados incorretos. Ainda assim, os resultados após 7 Jan 1972 estarão corretos.

Se a transição de horário (devido ao horário de verão ou por outros motivos) tiver ocorrido em um instante que não seja múltiplo de 15 minutos, você também poderá obter resultados incorretos nesse dia específico.

Datas de calendário não monotônicas. Por exemplo, em Happy Valley - Goose Bay, o horário foi atrasado em uma hora às 00:01:00 de 7 Nov 2010 (um minuto após a meia-noite). Assim, depois que 6 Nov terminou, houve um minuto inteiro de 7 Nov, depois o horário voltou para 23:01 de 6 Nov e, após mais 59 minutos, 7 Nov começou novamente. O ClickHouse ainda não oferece suporte a esse tipo de situação curiosa. Durante esses dias, os resultados das funções de processamento de tempo podem ficar ligeiramente incorretos.

Existe um problema semelhante na estação antártica Casey no ano de 2010. O horário foi atrasado em três horas em 5 Mar, às 02:00. Se você estiver trabalhando nessa estação antártica, não tenha receio de usar o ClickHouse. Apenas certifique-se de definir o fuso horário como UTC ou esteja ciente das imprecisões.

Mudanças de horário de vários dias. Algumas ilhas do Pacífico mudaram seu deslocamento de fuso horário de UTC+14 para UTC-12. Isso não é um problema, mas pode haver algumas imprecisões se você fizer cálculos com esse fuso horário para momentos históricos nos dias da mudança.

​

Como lidar com o horário de verão (DST)

O tipo DateTime do ClickHouse com fusos horários pode apresentar comportamentos inesperados durante as transições de horário de verão (DST), principalmente quando:

• date_time_output_format está definido como simple.
• Os relógios são atrasados (“Fall Back”), causando uma sobreposição de uma hora.
• Os relógios são adiantados (“Spring Forward”), causando um intervalo de uma hora.

Por padrão, o ClickHouse sempre escolhe a primeira ocorrência de um horário sobreposto e pode interpretar horários inexistentes durante os adiantamentos do relógio.

Por exemplo, considere a seguinte transição do horário de verão (DST) para a hora padrão.

• Em 29 de outubro de 2023, às 02:00:00, os relógios voltam para 01:00:00 (BST → GMT).
• A hora 01:00:00 – 01:59:59 aparece duas vezes (uma em BST e outra em GMT)
• O ClickHouse sempre escolhe a primeira ocorrência (BST), o que causa resultados inesperados ao adicionar intervalos de tempo.

SELECT '2023-10-29 01:30:00'::DateTime('Europe/London') AS time, time + toIntervalHour(1) AS one_hour_later

┌────────────────time─┬──────one_hour_later─┐
│ 2023-10-29 01:30:00 │ 2023-10-29 01:30:00 │
└─────────────────────┴─────────────────────┘

Da mesma forma, durante a transição do horário padrão para o horário de verão, pode parecer que uma hora foi ignorada.

Por exemplo:

• Em 26 de março de 2023, às 00:59:59, os relógios avançam para 02:00:00 (GMT → BST).
• O intervalo entre 01:00:00 e 01:59:59 não existe.

SELECT '2023-03-26 01:30:00'::DateTime('Europe/London') AS time, time + toIntervalHour(1) AS one_hour_later

┌────────────────time─┬──────one_hour_later─┐
│ 2023-03-26 00:30:00 │ 2023-03-26 02:30:00 │
└─────────────────────┴─────────────────────┘

Nesse caso, o ClickHouse retrocede o horário inexistente 2023-03-26 01:30:00 para 2023-03-26 00:30:00.

​

Veja também

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