Um motor de tabela que armazena séries temporais, ou seja, um conjunto de valores associados a timestamps e tags (ou labels):

metric_name1[tag1=value1, tag2=value2, ...] = {timestamp1: value1, timestamp2: value2, ...}
metric_name2[...] = ...

Este é um recurso experimental que pode mudar de formas incompatíveis com versões anteriores em lançamentos futuros. Habilite o uso do motor de tabela TimeSeries com a configuração allow_experimental_time_series_table. Execute o comando set allow_experimental_time_series_table = 1.

Sintaxe

CREATE TABLE name [(columns)] ENGINE=TimeSeries
[SETTINGS var1=value1, ...]
[SAMPLES db.samples_table_name | [SAMPLES INNER COLUMNS (...)] [SAMPLES INNER ENGINE engine(arguments)]]
[TAGS db.tags_table_name | [TAGS INNER COLUMNS (...)] [TAGS INNER ENGINE engine(arguments)]]
[METRICS db.metrics_table_name | [METRICS INNER COLUMNS (...)] [METRICS INNER ENGINE engine(arguments)]]

A palavra-chave SAMPLES tem um alias DATA, mantido por compatibilidade com versões anteriores.

Uso

É mais fácil começar com tudo configurado com os valores padrão (é permitido criar uma tabela TimeSeries sem especificar uma lista de colunas):

CREATE TABLE my_table ENGINE=TimeSeries

Essa tabela pode ser usada com os seguintes protocolos (uma porta deve ser atribuída na configuração do servidor):

Colunas externas

As colunas de uma tabela TimeSeries são geradas automaticamente. São colunas externas: não armazenam dados, apenas fornecem a interface para SELECT/INSERT. Os dados reais são armazenados em tabelas de destino. Aqui está a lista das colunas externas:

Nome	Tipo	Descrição
`metric_name`	`String`	O nome da métrica
`tags`	`Map(String, String)`	map de tags (labels) da série temporal
`time_series`	`Array(Tuple(DateTime64(3), Float64))` por padrão	Array de pares (timestamp, valor) de uma série temporal. Os tipos de elemento do timestamp e do escalar da tupla podem ser derivados da declaração `INNER COLUMNS` das amostras (consulte Especificando colunas externas)
`metric_family`	`String`	O nome da família de métricas (para os metadados das métricas)
`type`	`String`	O tipo da métrica (por exemplo, “counter”, “gauge”)
`unit`	`String`	A unidade da métrica
`help`	`String`	A descrição da métrica

Exemplo:

INSERT INTO my_table (metric_name, tags, time_series) VALUES
    ('cpu_usage', {'job': 'node_exporter', 'instance': 'host1:9100'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5), (toDateTime64('2024-01-01 00:01:00', 3), 0.7)])

É permitido que metric_name fique vazio na inserção; isso significa que o nome da métrica é especificado em tags, em __name__, por exemplo:

INSERT INTO my_table (tags, time_series) VALUES
    ({'__name__': 'cpu_usage', 'job': 'test'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5)])

Para inserir os metadados das métricas, insira nas colunas metric_family, type, unit e help:

INSERT INTO my_table (metric_name, tags, time_series, metric_family, type, unit, help) VALUES
    ('http_requests_total', {'method': 'GET'}, [(now64(), 100.0)],
     'http_requests_total', 'counter', 'requests', 'Total HTTP requests')

Especificando colunas externas

A coluna externa time_series pode ser listada explicitamente em uma instrução CREATE TABLE para substituir seu tipo padrão Array(Tuple(DateTime64(3), Float64)). O ClickHouse extrai, da tupla, os tipos de timestamp e do valor escalar e os propaga para a tabela interna de amostras:

CREATE TABLE my_table (time_series Array(Tuple(UInt32, Float32))) ENGINE=TimeSeries

Isso equivale a declarar diretamente, na cláusula INNER COLUMNS de samples, os tipos das colunas de timestamp e valor:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp UInt32, value Float32)

Se ambas as formas forem usadas na mesma instrução CREATE TABLE, os tipos declarados deverão coincidir.

Tabelas de destino

Uma tabela TimeSeries não armazena dados próprios; tudo é armazenado em suas tabelas de destino. Isso é semelhante ao funcionamento de uma visão materializada, com a diferença de que uma visão materializada tem uma tabela de destino, enquanto uma tabela TimeSeries tem três tabelas de destino chamadas samples, tags e metrics. As tabelas de destino podem ser especificadas explicitamente na consulta CREATE TABLE ou o motor de tabela TimeSeries pode gerar automaticamente tabelas de destino internas. As linhas inseridas em uma tabela TimeSeries são transformadas, divididas em blocos e inseridas nessas três tabelas de destino. As tabelas de destino são as seguintes:

Tabela samples

A tabela samples contém séries temporais associadas a um identificador. A tabela samples deve ter as seguintes colunas:

Nome	Obrigatória?	Tipo padrão	Tipos possíveis	Descrição
`id`	[x]	`UUID`	qualquer	Identifica uma combinação de nomes de métricas e tags
`timestamp`	[x]	`DateTime64(3)`	`DateTime64(X)`	Um ponto no tempo
`value`	[x]	`Float64`	`Float32` ou `Float64`	Um valor associado ao `timestamp`

Tabela de tags

A tabela tags contém identificadores calculados para cada combinação de nome de métrica e tags. A tabela tags deve ter as colunas:

Nome	Obrigatório?	Tipo padrão	Tipos possíveis	Descrição
`id`	[x]	`UUID`	qualquer tipo (deve corresponder ao tipo de `id` na tabela samples)	Um `id` identifica uma combinação de nome de métrica e tags. A expressão DEFAULT especifica como calcular esse identificador
`metric_name`	[x]	`LowCardinality(String)`	`String` ou `LowCardinality(String)`	O nome de uma métrica
`<tag_value_column>`	[ ]	`String`	`String` ou `LowCardinality(String)` ou `LowCardinality(Nullable(String))`	O valor de uma tag específica; o nome da tag e o nome da coluna correspondente são especificados na configuração tags_to_columns
`tags`	[x]	`Map(LowCardinality(String), String)`	`Map(String, String)` ou `Map(LowCardinality(String), String)` ou `Map(LowCardinality(String), LowCardinality(String))`	map de tags, excluindo a tag `__name__`, que contém o nome de uma métrica, e excluindo as tags com nomes listados na configuração tags_to_columns
`all_tags`	[ ]	`Map(String, String)`	`Map(String, String)` ou `Map(LowCardinality(String), String)` ou `Map(LowCardinality(String), LowCardinality(String))`	Coluna efêmera; cada linha é um map de todas as tags, excluindo apenas a tag `__name__`, que contém o nome de uma métrica. O único propósito dessa coluna é ser usada no cálculo de `id`
`min_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` ou `Nullable(DateTime64(X))`	timestamp mínimo da série temporal com esse `id`. A coluna é criada se store_min_time_and_max_time for `true`
`max_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` ou `Nullable(DateTime64(X))`	timestamp máximo da série temporal com esse `id`. A coluna é criada se store_min_time_and_max_time for `true`

Tabela de métricas

A tabela metrics contém algumas informações sobre as métricas coletadas, os tipos dessas métricas e suas descrições. A tabela metrics deve conter as colunas:

Nome	Obrigatória?	Tipo padrão	Tipos possíveis	Descrição
`metric_family_name`	[x]	`String`	`String` ou `LowCardinality(String)`	O nome de uma família de métricas
`type`	[x]	`LowCardinality(String)`	`String` ou `LowCardinality(String)`	O tipo de uma família de métricas, um de “counter”, “gauge”, “summary”, “stateset”, “histogram”, “gaugehistogram”
`unit`	[x]	`LowCardinality(String)`	`String` ou `LowCardinality(String)`	A unidade usada em uma métrica
`help`	[x]	`String`	`String` ou `LowCardinality(String)`	A descrição de uma métrica

Criação

Há várias maneiras de criar uma tabela com o motor de tabela TimeSeries. A instrução mais simples

CREATE TABLE my_table ENGINE=TimeSeries

na verdade, criará a tabela a seguir (você pode verificar isso executando SHOW CREATE TABLE my_table):

CREATE TABLE my_table
(
    `metric_name` String,
    `tags` Map(String, String),
    `time_series` Array(Tuple(DateTime64(3), Float64)),
    `metric_family` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
SAMPLES INNER COLUMNS
(
    `id` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp)
TAGS INNER COLUMNS
(
    `id` UUID DEFAULT reinterpretAsUUID(sipHash128(metric_name, all_tags)),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `all_tags` Map(String, String) EPHEMERAL,
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3)))
)
TAGS INNER ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id)
METRICS INNER COLUMNS
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
METRICS INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name

Assim, as colunas foram geradas automaticamente, e também há três tabelas de destino internas com suas próprias definições de colunas armazenadas nas cláusulas INNER COLUMNS. As tabelas de destino internas têm nomes como .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx e cada tabela de destino tem seu próprio conjunto de colunas:

CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp)

CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` UUID DEFAULT reinterpretAsUUID(sipHash128(metric_name, all_tags)),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `all_tags` Map(String, String) EPHEMERAL,
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3)))
)
ENGINE = AggregatingMergeTree
PRIMARY KEY metric_name
ORDER BY (metric_name, id)

CREATE TABLE default.`.inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
ENGINE = ReplacingMergeTree
ORDER BY metric_family_name

Criando uma tabela AS com base em uma tabela existente

A instrução CREATE TABLE new_table AS existing_table copia da existing_table:

SETTINGS
INNER COLUMNS para cada tipo
INNER ENGINE para cada tipo

A instrução não é permitida se a existing_table tiver alvos externos. A lista externa de colunas é regenerada, e não copiada.

Ajustando os tipos das colunas

Você pode ajustar os tipos das colunas nas tabelas de destino internas usando a cláusula INNER COLUMNS. Por exemplo, para armazenar timestamps em microssegundos e valores como Float32:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6), value Float32)

A mesma cláusula pode ser usada para especificar codecs e outros atributos da coluna:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(3) CODEC(DoubleDelta))

A coluna `id`

A coluna id contém identificadores; cada identificador é calculado com base em uma combinação de nome de métrica e tags. O tipo e a expressão DEFAULT usados para gerar identificadores podem ser personalizados por meio da cláusula TAGS INNER COLUMNS:

CREATE TABLE my_table ENGINE=TimeSeries
TAGS INNER COLUMNS (id UInt64 DEFAULT sipHash64(metric_name, all_tags))

O tipo da coluna id deve ser um dos seguintes: UUID, UInt64, UInt128 ou FixedString(16). Se nenhuma expressão DEFAULT for fornecida, ClickHouse a escolherá automaticamente com base no tipo de id. Os tipos de id declarados nas tabelas internas samples e tags devem corresponder. A configuração id_generator oferece a mesma personalização sem usar a cláusula INNER COLUMNS:

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_generator = 'sipHash64(metric_name, all_tags)'

Se essa configuração estiver definida, ela será usada para gerar o id, mesmo que o DEFAULT da coluna contenha uma expressão diferente.

As colunas `tags` e `all_tags`

Há duas colunas que contêm maps de tags: tags e all_tags. Neste exemplo, elas são equivalentes, mas podem ser diferentes se a configuração tags_to_columns for usada. Essa configuração permite especificar que uma tag específica deve ser armazenada em uma coluna separada, em vez de ficar armazenada em um map dentro da coluna tags:

CREATE TABLE my_table
ENGINE = TimeSeries 
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}

Esta instrução adicionará as colunas instance e job à tabela de destino interna de tags. Nesse caso, a coluna tags não conterá as tags instance e job, mas a coluna all_tags conterá. A coluna all_tags é efêmera e serve apenas para ser usada na expressão DEFAULT da coluna id.

Motores de tabela das tabelas de destino internas

Por padrão, as tabelas de destino internas usam os seguintes motores de tabela:

a tabela samples usa MergeTree;
a tabela tags usa AggregatingMergeTree porque os mesmos dados costumam ser inseridos várias vezes nessa tabela, então precisamos de uma forma de remover duplicatas, além de ser necessário fazer agregação para as colunas min_time e max_time;
a tabela metrics usa ReplacingMergeTree porque os mesmos dados costumam ser inseridos várias vezes nessa tabela, então precisamos de uma forma de remover duplicatas.

Outros motores de tabela também podem ser usados nas tabelas de destino internas, caso isso seja especificado:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRICS ENGINE=ReplicatedReplacingMergeTree

Tabelas de destino externas

É possível fazer com que uma tabela TimeSeries use uma tabela criada manualmente:

CREATE TABLE samples_for_my_table
(
    `id` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp);

CREATE TABLE tags_for_my_table ...

CREATE TABLE metrics_for_my_table ...

CREATE TABLE my_table ENGINE=TimeSeries SAMPLES samples_for_my_table TAGS tags_for_my_table METRICS metrics_for_my_table;

Os tipos de coluna das tabelas externas (id, timestamp, value e os <tag_value_column> listados em tags_to_columns) devem corresponder aos que a tabela TimeSeries geraria internamente (consulte Tabela samples, Tabela de Tags e Tabela de métrica para as restrições de tipo). Incompatibilidades de tipo são informadas no momento do CREATE. A expressão do gerador de ID para um destino externo de tags é resolvida no momento do INSERT, na seguinte ordem: a configuração id_generator (se definida), depois o DEFAULT declarado na coluna id da tabela externa (se houver) e, por fim, o gerador canônico derivado do tipo de id. Portanto, a configuração substitui qualquer DEFAULT declarado na tabela externa — consulte A coluna id para mais detalhes.

Alterando configurações

Duas configurações podem ser alteradas após CREATE:

id_generator
filter_by_min_time_and_max_time

ALTER TABLE my_table MODIFY SETTING id_generator = 'sipHash64(metric_name, all_tags)';
ALTER TABLE my_table MODIFY SETTING filter_by_min_time_and_max_time = 0;

Observe que alterar id_generator quando já existem dados na tabela de tags pode gerar IDs diferentes para a mesma combinação de métrica+tag — as linhas antigas mantêm seus IDs antigos, e as linhas novas usam o novo gerador. As outras configurações não podem ser alteradas com ALTER ... MODIFY SETTING porque são incorporadas ao esquema das tabelas internas no momento do CREATE.

Configurações

Aqui está uma lista de configurações que podem ser especificadas ao definir uma tabela TimeSeries:

Nome	Tipo	Padrão	Descrição
`id_generator`	Expression	depende do tipo de `id`	Expressão que calcula o identificador (fingerprint) de uma série temporal a partir de suas tags. Se não for definida, a expressão padrão da coluna `id` será usada. Se a expressão padrão da coluna `id` também não estiver definida, a expressão será escolhida automaticamente
`tags_to_columns`	Map	Map que especifica quais tags devem ser colocadas em colunas separadas na tabela tags. Sintaxe: `{'tag1': 'column1', 'tag2' : column2, ...}`
`use_all_tags_column_to_generate_id`	Bool	true	Ao gerar uma expressão para calcular o identificador de uma série temporal, esta opção permite usar a coluna `all_tags` nesse cálculo
`store_min_time_and_max_time`	Bool	true	Se definido como true, a tabela armazenará `min_time` e `max_time` para cada série temporal
`aggregate_min_time_and_max_time`	Bool	true	Ao criar uma tabela `tags` interna de destino, esta opção permite usar `SimpleAggregateFunction(min, Nullable(DateTime64(3)))` em vez de apenas `Nullable(DateTime64(3))` como tipo da coluna `min_time`, e o mesmo para a coluna `max_time`
`filter_by_min_time_and_max_time`	Bool	true	Se definido como true, a tabela usará as colunas `min_time` e `max_time` para filtrar séries temporais

Funções

Aqui está uma lista de funções que aceitam uma tabela TimeSeries como argumento:

​Sintaxe

​Uso

​Colunas externas

​Especificando colunas externas

​Tabelas de destino

​Tabela samples

​Tabela de tags

​Tabela de métricas

​Criação

​Criando uma tabela AS com base em uma tabela existente

​Ajustando os tipos das colunas

​A coluna id

​As colunas tags e all_tags

​Motores de tabela das tabelas de destino internas

​Tabelas de destino externas

​Alterando configurações

​Configurações

​Funções

Sintaxe

Uso

Colunas externas

Especificando colunas externas

Tabelas de destino

Tabela samples

Tabela de tags

Tabela de métricas

Criação

Criando uma tabela AS com base em uma tabela existente

Ajustando os tipos das colunas

A coluna `id`

As colunas `tags` e `all_tags`

Motores de tabela das tabelas de destino internas

Tabelas de destino externas

Alterando configurações

Configurações

Funções