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 em visualização privada 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 enable_time_series_table. Execute o comando set enable_time_series_table = 1.

O motor de tabela TimeSeries está disponível no ClickHouse Cloud como um recurso em visualização privada. Os serviços que participam da visualização privada já possuem a configuração enable_time_series_table definida. Outros serviços do ClickHouse Cloud não têm essa configuração, e você não pode habilitar o motor por conta própria em um serviço desse tipo.

Sintaxe

CREATE TABLE name [(columns)] ENGINE=TimeSeries
[SETTINGS var1=value1, ...]
[SAMPLES db.samples_table_name | [SAMPLES INNER COLUMNS (...)] [SAMPLES INNER ENGINE engine(arguments)]]
[RECENT SAMPLES db.recent_samples_table_name | [RECENT SAMPLES INNER COLUMNS (...)] [RECENT SAMPLES INNER ENGINE engine(arguments)]]
[TAGS db.tags_table_name | [TAGS INNER COLUMNS (...)] [TAGS INNER ENGINE engine(arguments)]]
[METRIC FAMILIES db.metric_families_table_name | [METRIC FAMILIES INNER COLUMNS (...)] [METRIC FAMILIES INNER ENGINE engine(arguments)]]

A palavra-chave SAMPLES tem um alias DATA, e a palavra-chave METRIC FAMILIES tem um alias METRICS, ambos mantidos por compatibilidade com versões anteriores. A definição de uma tabela de uma version anterior à 4 é gravada com METRICS, para que um servidor mais antigo possa lê-la.

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
`samples`	`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). A coluna é denominada `time_series` nas tabelas da versão 2 e anteriores
`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, samples) 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, samples) 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, samples, 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 samples pode ser listada explicitamente em uma instrução CREATE TABLE para substituir seu tipo padrão Array(Tuple(DateTime64(3), Float64)) (seu nome antigo, time_series, também é aceito). O ClickHouse extrai, da tupla, os tipos de timestamp e do valor escalar e os propaga para a tabela samples:

CREATE TABLE my_table (samples 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 CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3)))

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 obrigatórias chamadas samples, tags e metric families, e uma tabela de destino opcional amostras recentes, que vem habilitada por padrão (consulte a configuração recent_samples_ttl_seconds). 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 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]	`Tuple(UInt64, LowCardinality(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`

As colunas que o motor cria por conta própria recebem codecs de compressão de séries temporais: timestamp CODEC(Delta, T64, ZSTD(3)) e value CODEC(ALP, ZSTD(3)). Timestamps quase monotônicos mal são comprimidos por codecs genéricos e podem, caso contrário, dominar o tamanho em disco da tabela samples. O motor habilita ALP para suas tabelas internas samples e amostras recentes sem exigir que enable_alp_codec seja definido. Consulte também Ajustando os tipos das colunas.

Tabela de amostras recentes

A tabela de amostras recentes é opcional e está habilitada por padrão (consulte a configuração recent_samples_ttl_seconds; defini-la como zero desabilita a tabela). Ela contém uma cópia das amostras mais recentes que o TTL definido por essa configuração e deve ter as mesmas colunas que a tabela samples. A coluna timestamp gerada usa CODEC(Delta, T64, ZSTD(3)), e a coluna value gerada usa CODEC(ALP, ZSTD(3)). Toda amostra inserida é gravada tanto na tabela samples quanto na tabela de amostras recentes. As consultas cujo intervalo de tempo se encaixa na janela do TTL leem da tabela de amostras recentes em vez da tabela samples principal, já que ela é muito menor (esse comportamento pode ser desabilitado com a configuração de nível de consulta time_series_prefer_recent_samples_table). O TTL da tabela interna de amostras recentes é sempre derivado da configuração recent_samples_ttl_seconds.

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]	`Tuple(UInt64, LowCardinality(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 todas as tags, incluindo a tag `__name__`, que contém o nome de uma métrica, e as tags com nomes listados na configuração tags_to_columns. As tabelas criadas por versões mais antigas do ClickHouse armazenavam nesta coluna apenas as tags sem colunas dedicadas e sem o nome da métrica; a leitura lida com ambos os casos
`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`

Novas tabelas internas de tags da versão 5 e posteriores com um motor da família MergeTree têm um índice de texto invertido em tags: INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs'). Ele acelera correspondências exatas de rótulos, como {job="api"} em PromQL, consultando a chave e o valor em conjunto. Comparações com uma string vazia também correspondem a rótulos ausentes e não usam esse índice. Índices explícitos declarados em TAGS INNER COLUMNS substituem o índice padrão. As tabelas existentes e as tabelas de tags externas mantêm seus índices; adicione e materialize o índice na tabela de destino das tags para habilitá-lo.

Tabela de famílias de métricas

A tabela metric families contém algumas informações sobre as famílias de métricas coletadas, os tipos dessas famílias de métricas e suas descrições. Uma família de métricas é um grupo de métricas com o mesmo nome (a tag __name__) e o mesmo tipo; por exemplo, um histograma é uma família de métricas composta por várias métricas. A tabela metric families 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

Existem 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 seguinte tabela (você pode verificar isso executando SHOW CREATE TABLE my_table):

CREATE TABLE my_table
(
    `metric_name` String,
    `tags` Map(String, String),
    `samples` Array(Tuple(DateTime64(3), Float64)),
    `metric_family` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
SETTINGS version = 5, recent_samples_ttl_seconds = 345600
SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, LowCardinality(UUID)),
    `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768
RECENT SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
RECENT SAMPLES INNER ENGINE = MergeTree PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5)) ORDER BY (id, timestamp) TTL toDateTime(timestamp) + toIntervalSecond(345600) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1
TAGS INNER COLUMNS
(
    `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(reinterpretAsUUID(sipHash128(tags)))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3))),
    INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000
)
TAGS INNER ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id) SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192
METRIC FAMILIES INNER COLUMNS
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
METRIC FAMILIES INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name

Portanto, as colunas foram geradas automaticamente e também existem quatro tabelas de destino internas com suas próprias definições de colunas armazenadas nas cláusulas INNER COLUMNS. A configuração recent_samples_ttl_seconds foi gravada na cláusula SETTINGS com seu valor padrão: essa configuração define o TTL da tabela de amostras recentes, de modo que seu valor efetivo é fixado na criação. Além disso, a versão de schema mais recente foi fixada na configuração version (consulte Versionamento de schema). As tabelas de destino internas têm nomes como .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metricfamilies.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` Tuple(UInt64, LowCardinality(UUID)),
    `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
ENGINE = MergeTree
ORDER BY (id, timestamp)
SETTINGS index_granularity = 32768

CREATE TABLE default.`.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
ENGINE = MergeTree
PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))
ORDER BY (id, timestamp)
TTL toDateTime(timestamp) + toIntervalSecond(345600)
SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1

CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(reinterpretAsUUID(sipHash128(tags)))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3))),
    INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000
)
ENGINE = AggregatingMergeTree
PRIMARY KEY metric_name
ORDER BY (metric_name, id)
SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192

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

Criar uma tabela AS a partir de uma tabela existente

A instrução CREATE TABLE new_table AS existing_table cria uma tabela TimeSeries configurada como existing_table, que deve ser uma tabela TimeSeries. Os destinos externos de existing_table não são copiados: a própria instrução deve declarar esses destinos. A instrução copia de existing_table:

a cláusula SETTINGS, exceto version: a nova tabela sempre recebe a versão mais recente. As configurações especificadas na instrução são mescladas às copiadas pelo nome; portanto, uma configuração especificada prevalece sobre a copiada, e name = DEFAULT redefine uma configuração copiada para o valor padrão;
as cláusulas INNER COLUMNS e INNER ENGINE de cada tabela interna. Colunas personalizadas (por exemplo, colunas extras ou colunas com um codec ou uma expressão DEFAULT) e partes personalizadas do motor (por exemplo, um motor com argumentos, uma chave de ordenação personalizada ou uma configuração do motor) são mantidas; as demais colunas e partes do motor são ajustadas às configurações da nova tabela para que, por exemplo, tags_to_columns, aggregate_min_time_and_max_time ou tags_index_granularity especificadas na instrução tenham efeito.

Os tipos das colunas id, de timestamp e de valor, bem como o tipo de replicação dos motores internos (MergeTree, ReplicatedMergeTree ou SharedMergeTree), também são obtidos de existing_table, a menos que a própria instrução os declare. A lista de colunas externas é regenerada, não copiada. Uma tabela criada por uma versão mais antiga do ClickHouse pode ser usada como existing_table: a nova tabela recebe a estrutura atual, por exemplo, o tipo id atual e a expressão padrão de identificador.

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, use:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6) CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3)))

Especificar colunas internas sem codecs significa usar o codec padrão para elas:

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

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(tags))

A coluna id pode ser de qualquer tipo comparável que não seja Nullable. Os tipos de id declarados nas tabelas internas samples e tags devem corresponder. Se nenhuma expressão DEFAULT for fornecida para a coluna id e a configuração id_generator não estiver definida, ClickHouse escolherá a expressão DEFAULT automaticamente com base no tipo de id, mas apenas se o tipo de id for um dos seguintes: UUID, UInt64, UInt128, FixedString(16), os mesmos tipos encapsulados em LowCardinality ou uma tupla de dois desses tipos. Para essa tupla, a expressão escolhida automaticamente calcula um hash do nome de métrica no primeiro componente e um hash de todas as tags no segundo componente. Um tipo de identificador LowCardinality, por exemplo Tuple(UInt64, LowCardinality(UUID)), mantém os identificadores codificados por dicionário: a tabela samples armazena pequenos dicionários por bloco com dictionary indexes em vez de repetir o identificador completo em cada linha, o que reduz a quantidade de dados lidos pelas consultas. 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(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. O tipo da coluna id também pode ser especificado na configuração id_type em vez da cláusula INNER COLUMNS:

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_type = 'UInt64', id_generator = 'sipHash64(tags)'

Quando a configuração id_generator está definida, a configuração id_type é registrada automaticamente no momento do CREATE, de modo que a definição preserva o tipo para o qual a expressão foi escrita.

A coluna `tags`

A coluna tags contém todas as tags de uma série temporal, incluindo a tag __name__ com o nome de uma métrica. A configuração tags_to_columns permite especificar que uma tag específica também deve ser armazenada em uma coluna separada além do 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. Os valores das tags instance e job serão armazenados tanto nessas colunas quanto na coluna tags.

Nas tabelas criadas por versões mais antigas do ClickHouse, a coluna tags contém apenas as tags sem colunas dedicadas e sem o nome da métrica, e a coluna all_tags é uma coluna efêmera preenchida na inserção com todas as tags, exceto o nome da métrica.

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 amostras recentes usa MergeTree particionada em buckets de 5 horas (consulte a configuração recent_samples_partition_by) com um TTL derivado da configuração recent_samples_ttl_seconds e com ttl_only_drop_parts habilitado, de modo que as partes expiradas são removidas por inteiro;
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 famílias de métricas usa ReplacingMergeTree porque os mesmos dados costumam ser inseridos várias vezes nessa tabela, então precisamos de uma forma de remover duplicatas.

A família de motores das tabelas internas geradas segue a configuração de nível de consulta default_table_engine: com default_table_engine = ReplicatedMergeTree ou SharedMergeTree, as tabelas internas usam os motores Replicated ou Shared correspondentes. Com default_table_engine = None (ou qualquer outro valor), os motores das tabelas internas devem ser especificados explicitamente. Todas as tabelas internas devem ter o mesmo tipo de replicação: se uma delas for replicada (ou compartilhada), as demais tabelas internas também devem ser replicadas (ou compartilhadas); caso contrário, seus conteúdos divergiriam entre as réplicas. Por exemplo, declarar SAMPLES INNER ENGINE = ReplicatedMergeTree(...) exige que os demais motores internos também sejam replicados — seja declarados explicitamente ou gerados com default_table_engine = ReplicatedMergeTree. 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
RECENT SAMPLES ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRIC FAMILIES ENGINE=ReplicatedReplacingMergeTree

A tabela tags mantém as colunas de tag (e o Map tags) fora de sua chave de ordenação, o que AggregatingMergeTree rejeita por padrão (consulte allow_dimensions_outside_sorting_key). Isso é seguro aqui porque essas colunas dependem funcionalmente de id, que faz parte da chave de ordenação, portanto todas as linhas que uma mesclagem em segundo plano combina compartilham os mesmos valores. Quando a tabela interna de tags é gerada ou seu motor é especificado inline, como acima, TimeSeries define allow_dimensions_outside_sorting_key = 1 nela automaticamente; para uma tabela externa de tags com agregação criada manualmente, você deve definir isso por conta própria.

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 metric_families_for_my_table ...

CREATE TABLE my_table ENGINE=TimeSeries SAMPLES samples_for_my_table TAGS tags_for_my_table METRIC FAMILIES metric_families_for_my_table;

Uma tabela externa também pode ser usada como destino de amostras recentes (a cláusula RECENT SAMPLES my_recent_samples_table). Essa tabela deve ter as mesmas colunas de uma tabela samples externa e deve reter pelo menos recent_samples_ttl_seconds segundos de dados, o que é responsabilidade do usuário. 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 famílias de métricas para as restrições de tipo). Incompatibilidades de tipo são informadas no momento do CREATE. O tipo da coluna id de uma tabela de tags externa e a expressão que gera os identificadores são registrados nas configurações id_type e id_generator no momento do CREATE (a partir da versão 2), de modo que a definição da tabela TimeSeries os mantém: por exemplo, CREATE TABLE ... AS my_table lê o tipo de id a partir da definição de my_table sem ler suas tabelas de destino externas. Se a configuração id_generator não for especificada, ela é definida como o DEFAULT declarado na coluna id da tabela externa (se houver) ou, caso contrário, como o gerador canônico derivado do tipo de id. A expressão registrada é usada para gerar o id mesmo que o DEFAULT da tabela externa mude posteriormente — 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(tags)';
ALTER TABLE my_table MODIFY SETTING filter_by_min_time_and_max_time = 0;
ALTER TABLE my_table RESET SETTING filter_by_min_time_and_max_time;

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: a maioria delas é incorporada ao esquema das tabelas internas no momento do CREATE, e a configuração version é fixada automaticamente no momento do CREATE e identifica o próprio esquema (consulte Versionamento de schema).

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_type`	Tipo de dado	depende da coluna `id`	O tipo da coluna `id` das tabelas de destino. Normalmente o tipo é declarado nas cláusulas `INNER COLUMNS` das tabelas internas ou em uma tabela tags externa; a configuração é registrada automaticamente no momento do `CREATE` caso o tipo não seja mantido na definição de outra forma: se o destino de tags for uma tabela externa, ou se a configuração `id_generator` estiver definida. A configuração também pode ser especificada explicitamente em vez de `TAGS INNER COLUMNS (id <type>)`. Requer que `version` seja pelo menos 2
`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. Para uma tabela tags externa, a configuração é registrada automaticamente no momento do `CREATE` se `version` for pelo menos 2 (consulte Tabelas de destino externas)
`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	false	Configuração obsoleta, não faz nada
`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
`samples_index_granularity`	UInt64	32768	Define `index_granularity` da tabela samples interna. Quando definido explicitamente, substitui `index_granularity` da declaração do motor. Ignorado para uma tabela samples externa e um motor que não seja MergeTree
`recent_samples_ttl_seconds`	UInt64	345600	Retenção da tabela de destino adicional `amostras recentes`, na qual cada amostra inserida também é gravada. Uma tabela interna de amostras recentes sempre recebe `TTL toDateTime(timestamp) + toIntervalSecond(recent_samples_ttl_seconds)` derivado desta configuração (substituindo qualquer TTL da declaração do motor); uma tabela externa de amostras recentes deve reter pelo menos essa quantidade de segundos de dados. Consultas cujo intervalo de tempo está dentro da janela de TTL priorizam a tabela de amostras recentes em vez da tabela principal de amostras (consulte a configuração no nível da consulta `time_series_prefer_recent_samples_table`). O padrão é de 4 dias; o valor efetivo é fixado na definição da tabela no momento do CREATE. Defina como 0 para desabilitar a tabela de amostras recentes
`recent_samples_partition_by`	Expression	`toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))`	Chave de partição da tabela interna `amostras recentes`, por exemplo, `toStartOfHour(timestamp)`. Quando definida explicitamente, substitui a chave de partição da declaração do motor; se nenhuma das duas for definida, é usada uma partição a cada 5 horas. Ignorado para uma tabela externa de amostras recentes. Requer que `recent_samples_ttl_seconds` seja diferente de zero
`recent_samples_index_granularity`	UInt64	8192	Define `index_granularity` da tabela interna `amostras recentes`. Quando definido explicitamente, substitui `index_granularity` da declaração do motor. Ignorado para uma tabela externa de amostras recentes e um motor que não seja MergeTree. Requer que `recent_samples_ttl_seconds` seja diferente de zero
`tags_index_granularity`	UInt64	8192	Define `index_granularity` da tabela tags interna. Quando definido explicitamente, substitui `index_granularity` da declaração do motor. Ignorado para uma tabela tags externa e um motor que não seja MergeTree
`version`	UInt64	5	A versão da tabela: identifica o conjunto de tabelas de destino e sua estrutura. A versão é fixada automaticamente quando uma tabela é criada e não pode ser alterada depois; normalmente ela deve ser omitida na consulta `CREATE TABLE` (consulte Versionamento de schema)

Versionamento de schema

O motor de tabela TimeSeries e a camada de execução de PromQL estão em desenvolvimento ativo: o conjunto de tabelas de destino e sua estrutura podem mudar entre versões do ClickHouse. Para tornar essas mudanças detectáveis, cada tabela TimeSeries armazena sua versão na configuração version. A versão é fixada automaticamente na consulta CREATE no momento da criação da tabela — seu valor é a versão mais recente conhecida pelo servidor (atualmente 5) —, persiste nos metadados da tabela e não pode ser alterada por ALTER. Tabelas criadas antes da introdução dessa configuração são consideradas como versão 0. Normalmente, basta omitir a configuração na consulta CREATE TABLE — assim a tabela recebe a versão mais recente. Um version explícito é aceito se o servidor der suporte a essa versão; nesse caso, a tabela é definida da forma como aquela versão a define (consulte Histórico de versões). CREATE TABLE ... AS other_table não copia a versão da outra tabela; consulte Criar uma tabela AS a partir de uma tabela existente. Um servidor dá suporte a um intervalo de versões, e a versão mínima pode variar conforme a operação: leitura com SELECT, gravação com INSERT ou com o protocolo remote-write do Prometheus, e avaliação de PromQL (as funções de tabela prometheusQuery, prometheusQueryRange e timeSeriesSelector, o dialect promql e a API HTTP de consulta do Prometheus):

Se a versão de uma tabela TimeSeries for antiga demais para PromQL, as consultas PromQL sobre ela são rejeitadas. A exceção sugere recriar a tabela: crie uma nova tabela TimeSeries, copie os dados com uma consulta INSERT ... SELECT e substitua a tabela antiga pela nova.
Se a versão for antiga demais para gravação, as consultas INSERT e o protocolo remote-write do Prometheus são rejeitados, enquanto as consultas SELECT continuam funcionando.
Se a versão for antiga demais para o servidor como um todo, toda consulta sobre a tabela (exceto SHOW CREATE TABLE, DETACH e DROP) é rejeitada.

Histórico de versões

Versão	Alterações
0	Tabelas criadas antes da introdução da configuração `version`, incluindo tabelas “prealpha” (que declaravam as colunas das tabelas de destino como colunas externas) e tabelas sem a tabela de amostras recentes
1	A configuração `version` foi introduzida
2	A configuração `id_type` foi introduzida: uma tabela com uma tabela de tags externa registra o tipo da coluna `id` em `id_type` e a expressão que gera identificadores em `id_generator`, de modo que sua definição não dependa da tabela externa. `id_type` também é registrado quando `id_generator` é definido (consulte A coluna `id`)
3	A coluna externa `time_series` foi renomeada para `samples` (consulte Colunas externas). As tabelas de versões anteriores mantêm o nome antigo da coluna, e as funções de tabela prometheusQuery e prometheusQueryRange retornam a coluna com o nome usado pela tabela. Os dados armazenados não foram alterados
4	A tabela de destino `metrics` foi renomeada para `metric families`: a tabela interna é chamada de `.inner_id.metricfamilies.<uuid>` em vez de `.inner_id.metrics.<uuid>`, e a definição é gravada com a palavra-chave `METRIC FAMILIES` em vez de `METRICS`. Os dados armazenados não foram alterados
5	Novas tabelas internas de tags com um motor da família `MergeTree` recebem, por padrão, um índice de texto `keyValuePairs` no map `tags` (consulte Tabela de tags)

Funções

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

Referência de SQL

Tipos de dados

Motores

Funções

Formatos

Configurações

Tabelas do sistema

Lagos de dados

motor de tabela TimeSeries

Sintaxe

Uso

Colunas externas

Especificando colunas externas

Tabelas de destino

Tabela samples

Tabela de amostras recentes

Tabela de tags

Tabela de famílias de métricas

Criação

Criar uma tabela AS a partir de uma tabela existente

Ajustando os tipos das colunas

A coluna `id`

A coluna `tags`

Motores de tabela das tabelas de destino internas

Tabelas de destino externas

Alterando configurações

Configurações

Versionamento de schema

Histórico de versões

Funções

​Sintaxe

​Uso

​Colunas externas

​Especificando colunas externas

​Tabelas de destino

​Tabela samples

​Tabela de amostras recentes

​Tabela de tags

​Tabela de famílias de métricas

​Criação

​Criar uma tabela AS a partir de uma tabela existente

​Ajustando os tipos das colunas

​A coluna id

​A coluna tags

​Motores de tabela das tabelas de destino internas

​Tabelas de destino externas

​Alterando configurações

​Configurações

​Versionamento de schema

​Histórico de versões

​Funções

Sintaxe

Uso

Colunas externas

Especificando colunas externas

Tabelas de destino

Tabela samples

Tabela de amostras recentes

Tabela de tags

Tabela de famílias de métricas

Criação

Criar uma tabela AS a partir de uma tabela existente

Ajustando os tipos das colunas

A coluna `id`

A coluna `tags`

Motores de tabela das tabelas de destino internas

Tabelas de destino externas

Alterando configurações

Configurações

Versionamento de schema

Histórico de versões

Funções