Moteur de table TimeSeries

Un moteur de table qui stocke des séries temporelles, c’est-à-dire un ensemble de valeurs associées à des horodatages et à des tags (ou labels).

Un moteur de table qui stocke des séries temporelles, c’est-à-dire un ensemble de valeurs associées à des horodatages et à des tags (ou labels) :

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

Il s’agit d’une fonctionnalité en private preview qui pourra, dans les versions ultérieures, évoluer de manière incompatible avec les versions précédentes. Activez l’utilisation du moteur de table TimeSeries à l’aide du paramètre enable_time_series_table. Saisissez la commande set enable_time_series_table = 1.

Le moteur de table TimeSeries est disponible dans ClickHouse Cloud en tant que fonctionnalité en private preview. Les services qui participent à la private preview disposent déjà du paramètre enable_time_series_table configuré. Les autres services ClickHouse Cloud ne possèdent pas cette configuration, et vous ne pouvez pas activer le moteur vous-même sur un tel service.

​

Syntaxe

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)]]

Le mot-clé SAMPLES a pour alias DATA, et le mot-clé METRIC FAMILIES a pour alias METRICS, tous deux étant maintenus pour assurer la rétrocompatibilité. La définition d’une table d’une version antérieure à 4 est écrite avec METRICS, afin qu’un serveur plus ancien puisse la lire.

​

Utilisation

Il est plus facile de commencer en laissant tous les paramètres par défaut (il est possible de créer une table TimeSeries sans préciser de liste de colonnes) :

CREATE TABLE my_table ENGINE=TimeSeries

Cette table peut ensuite être utilisée avec les protocoles suivants (un port doit être défini dans la configuration du serveur) :

• prometheus remote-write
• prometheus remote-read

​

Colonnes externes

Les colonnes d’une table TimeSeries sont générées automatiquement. Ce sont des colonnes externes : elles ne stockent aucune donnée et servent uniquement d’interface pour SELECT/INSERT. Les données réelles sont stockées dans les tables cibles. Voici la liste des colonnes externes :

Name	Type	Description
metric_name	String	Le nom de la métrique
tags	Map(String, String)	Map de tags (labels) pour la série temporelle
samples	Array(Tuple(DateTime64(3), Float64)) par défaut	Tableau de paires (horodatage, valeur) pour une série temporelle. Les types d’élément de l’horodatage et du scalaire du tuple peuvent être déduits de la déclaration INNER COLUMNS des échantillons (voir Spécification des colonnes externes). La colonne est nommée time_series dans les tables de version 2 et antérieures
metric_family	String	Le nom de la famille de métriques (pour les métadonnées de métriques)
type	String	Le type de la métrique (par ex. “counter”, “gauge”)
unit	String	L’unité de la métrique
help	String	La description de la métrique

Exemple :

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)])

metric_name peut être vide lors de l’insertion, ce qui signifie que le nom de la métrique est indiqué dans tags sous __name__, par exemple :

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

Pour insérer les métadonnées des métriques, insérez-les dans les colonnes metric_family, type, unit et 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')

​

Spécification des colonnes externes

La colonne externe samples peut être déclarée explicitement dans une instruction CREATE TABLE afin de remplacer son type par défaut Array(Tuple(DateTime64(3), Float64)) (son ancien nom time_series est également accepté). ClickHouse extrait du tuple le type d’horodatage et le type scalaire, puis les propage à la table samples interne :

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

Cela revient à déclarer directement les types des colonnes timestamp et value dans la clause INNER COLUMNS de samples :

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

Si les deux formes sont utilisées dans la même instruction CREATE TABLE, les types déclarés doivent être identiques.

​

Tables cibles

Une table TimeSeries ne possède pas ses propres données : tout est stocké dans ses tables cibles. Son fonctionnement est similaire à celui d’une vue matérialisée, à la différence qu’une vue matérialisée n’a qu’une seule table cible, tandis qu’une table TimeSeries a trois tables cibles obligatoires nommées samples, tags et familles de métriques, ainsi qu’une table cible facultative d’échantillons récents, activée par défaut (consultez le paramètre recent_samples_ttl_seconds).

Les tables cibles peuvent être spécifiées explicitement dans la requête CREATE TABLE, ou le moteur de table TimeSeries peut générer automatiquement des tables cibles internes.

Les lignes insérées dans une table TimeSeries sont transformées, découpées en blocs, puis insérées dans ces tables cibles.

Les tables cibles sont les suivantes :

​

Table samples

La table samples contient des séries temporelles associées à un certain identifiant.

La table samples doit comporter les colonnes suivantes :

Nom	Obligatoire ?	Type par défaut	Types possibles	Description
id	[x]	Tuple(UInt64, LowCardinality(UUID))	tout type	Identifie une combinaison de noms de métriques et de tags
timestamp	[x]	DateTime64(3)	DateTime64(X)	Un instant donné
value	[x]	Float64	Float32 ou Float64	Une valeur associée au timestamp

Les colonnes créées par le moteur lui-même reçoivent des codecs de compression pour séries temporelles : timestamp CODEC(Delta, T64, ZSTD(3)) et value CODEC(ALP, ZSTD(3)). Les horodatages quasi monotones se compressent très peu avec des codecs génériques et peuvent sinon représenter l’essentiel de la taille sur disque de la table samples. Le moteur active ALP pour ses tables internes samples et recent samples sans qu’il soit nécessaire de définir enable_alp_codec. Voir aussi Ajustement des types de colonnes.

​

Table des échantillons récents

La table des échantillons récents est facultative et activée par défaut (voir le paramètre recent_samples_ttl_seconds ; définir sa valeur sur zéro désactive la table). Elle contient une copie des échantillons dont l’ancienneté est inférieure à la TTL définie par ce paramètre et doit comporter les mêmes colonnes que la table samples. La colonne générée timestamp utilise CODEC(Delta, T64, ZSTD(3)), et la colonne générée value utilise CODEC(ALP, ZSTD(3)).

Chaque échantillon inséré est écrit à la fois dans la table samples et dans la table des échantillons récents. Les requêtes dont l’intervalle de temps est compris dans la fenêtre TTL lisent la table des échantillons récents plutôt que la table samples principale, car elle est bien plus petite (ce comportement peut être désactivé à l’aide du paramètre au niveau de la requête time_series_prefer_recent_samples_table).

La TTL de la table interne des échantillons récents est toujours dérivée du paramètre recent_samples_ttl_seconds.

​

Table des tags

La table tags contient des identifiants calculés pour chaque combinaison d’un nom de métrique et de tags.

La table tags doit contenir les colonnes suivantes :

Nom	Obligatoire ?	Type par défaut	Types possibles	Description
id	[x]	Tuple(UInt64, LowCardinality(UUID))	tout type (doit correspondre au type de id dans la table samples)	Un id identifie une combinaison d’un nom de métrique et de tags. L’expression DEFAULT indique comment calculer un tel identifiant
metric_name	[x]	LowCardinality(String)	String ou LowCardinality(String)	Le nom d’une métrique
<tag_value_column>	[ ]	String	String ou LowCardinality(String) ou LowCardinality(Nullable(String))	La valeur d’un tag spécifique ; le nom du tag et celui de la colonne correspondante sont indiqués dans le paramètre 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 tous les tags, y compris le tag __name__ qui contient le nom d’une métrique et les tags dont les noms sont énumérés dans le paramètre tags_to_columns. Les tables créées par des versions antérieures de ClickHouse ne stockaient dans cette colonne que les tags sans colonnes dédiées et sans le nom de la métrique ; la lecture gère les deux cas
min_time	[ ]	Nullable(DateTime64(3))	DateTime64(X) ou Nullable(DateTime64(X))	Horodatage minimal des séries temporelles associées à cet id. La colonne est créée si store_min_time_and_max_time vaut true
max_time	[ ]	Nullable(DateTime64(3))	DateTime64(X) ou Nullable(DateTime64(X))	Horodatage maximal des séries temporelles associées à cet id. La colonne est créée si store_min_time_and_max_time vaut true

Les nouvelles tables internes de tags de version 5 et ultérieures, dotées d’un moteur de la famille MergeTree, possèdent un index de texte inversé sur tags : INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs'). Il accélère les correspondances exactes de labels, telles que {job="api"} dans PromQL, en recherchant simultanément la clé et la valeur. Les comparaisons avec une chaîne vide correspondent également aux labels manquants et n’utilisent pas cet index.

Les index explicites déclarés dans TAGS INNER COLUMNS remplacent l’index par défaut. Les tables existantes et les tables de tags externes conservent leurs index ; ajoutez et matérialisez l’index sur leur table de tags cible pour l’activer.

​

Table familles de métriques

La table familles de métriques contient des informations sur les familles de métriques collectées, leurs types et leurs descriptions. Une famille de métriques est un groupe de métriques portant le même nom (le tag __name__) et ayant le même type. Par exemple, un histogramme est une famille de métriques composée de plusieurs métriques.

La table familles de métriques doit comporter les colonnes suivantes :

Nom	Obligatoire ?	Type par défaut	Types possibles	Description
metric_family_name	[x]	String	String ou LowCardinality(String)	Le nom d’une famille de métriques
type	[x]	LowCardinality(String)	String ou LowCardinality(String)	Le type d’une famille de métriques : « counter », « gauge », « summary », « stateset », « histogram » ou « gaugehistogram »
unit	[x]	LowCardinality(String)	String ou LowCardinality(String)	L’unité utilisée pour une métrique
help	[x]	String	String ou LowCardinality(String)	La description d’une métrique

​

Création

Il existe plusieurs façons de créer une table avec le moteur de table TimeSeries. L’instruction la plus simple

CREATE TABLE my_table ENGINE=TimeSeries

créera en fait la table suivante (vous pouvez le vérifier en exécutant 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

Les colonnes ont donc été générées automatiquement, et il existe également quatre tables cibles internes, chacune avec ses propres définitions de colonnes stockées dans les clauses INNER COLUMNS. Le paramètre recent_samples_ttl_seconds a été écrit dans la clause SETTINGS avec sa valeur par défaut : il définit le TTL de la table des échantillons récents, et sa valeur effective est donc fixée lors de la création. De plus, la dernière version du schéma a été fixée dans le paramètre version (voir Versionnement du schéma).

Les tables cibles internes portent des noms tels que .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 et chaque table cible possède son propre ensemble de colonnes :

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

​

Créer une table AS une table existante

L’instruction CREATE TABLE new_table AS existing_table crée une table TimeSeries configurée comme existing_table, qui doit elle-même être une table TimeSeries. Les cibles externes d’existing_table ne sont pas copiées : l’instruction doit déclarer ces cibles elle-même.

L’instruction reprend d’existing_table :

• la clause SETTINGS, à l’exception de version : la nouvelle table reçoit toujours la dernière version. Les paramètres indiqués dans l’instruction elle-même sont fusionnés par nom avec ceux qui sont copiés, si bien qu’un paramètre indiqué explicitement prime sur le paramètre copié, et que name = DEFAULT réinitialise un paramètre copié à sa valeur par défaut ;
• les clauses INNER COLUMNS et INNER ENGINE de chaque table interne. Les colonnes personnalisées (par exemple des colonnes supplémentaires, des colonnes dotées d’un codec ou d’une expression DEFAULT) ainsi que les éléments de moteur personnalisés (par exemple un moteur avec des arguments, une clé de tri personnalisée ou un paramètre de moteur) sont conservés ; les autres colonnes et éléments de moteur sont alignés sur les paramètres de la nouvelle table, de sorte que tags_to_columns, aggregate_min_time_and_max_time ou tags_index_granularity indiqués dans l’instruction prennent effet.

Les types des colonnes id, timestamp et valeur, ainsi que le type de replication des moteurs internes (MergeTree, ReplicatedMergeTree ou SharedMergeTree), sont également repris d’existing_table, sauf si l’instruction les déclare elle-même. La liste des colonnes externes est régénérée et non copiée.

Une table créée par une version plus ancienne de ClickHouse peut servir d’existing_table : la nouvelle table adopte la structure actuelle, par exemple le type id actuel et l’expression d’identifiant par défaut.

​

Ajustement des types de colonnes

Vous pouvez modifier le type des colonnes dans les tables cibles internes à l’aide de la clause INNER COLUMNS. Par exemple, pour stocker les horodatages en microsecondes et les valeurs en Float32, utilisez :

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

Spécifier des colonnes internes sans codec revient à utiliser le codec par défaut pour celles-ci :

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

​

La colonne id

La colonne id contient des identifiants ; chacun d’eux est calculé à partir d’une combinaison d’un nom de métrique et de tags. Le type et l’expression DEFAULT utilisés pour générérer les identifiants peuvent être personnalisés via la clause TAGS INNER COLUMNS :

CREATE TABLE my_table ENGINE=TimeSeries
TAGS INNER COLUMNS (id UInt64 DEFAULT sipHash64(tags))

La colonne id peut être de tout type comparable non-Nullable. Les types de id déclarés dans les tables internes samples et tags doivent correspondre.

Si aucune expression DEFAULT n’est définie pour la colonne id et que le paramètre id_generator n’est pas défini, ClickHouse choisira automatiquement l’expression DEFAULT en fonction du type de id, mais uniquement si celui-ci est UUID, UInt64, UInt128, FixedString(16), ces mêmes types encapsulés dans LowCardinality ou un tuple de deux de ces types. Pour un tel tuple, l’expression choisie automatiquement calcule un hash du nom de métrique dans le premier composant et un hash de tous les tags dans le second composant.

Un type d’identifiant LowCardinality, par exemple Tuple(UInt64, LowCardinality(UUID)), conserve les identifiants encodés par dictionnaire : la table samples stocke de petits dictionnaires par bloc avec des index de dictionnaire au lieu de répéter l’identifiant complet dans chaque ligne, ce qui réduit la quantité de données lues par les requêtes.

Le paramètre id_generator offre la même possibilité de personnalisation sans utiliser la clause INNER COLUMNS :

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

Si ce paramètre est défini, il est utilisé pour générer id, même si le DEFAULT de la colonne contient une expression différente.

Le type de la colonne id peut également être spécifié dans le paramètre id_type au lieu de la clause INNER COLUMNS :

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

Lorsque le paramètre id_generator est défini, le paramètre id_type est enregistré automatiquement au moment du CREATE, de sorte que la définition conserve le type pour lequel l’expression a été écrite.

​

La colonne tags

La colonne tags contient tous les tags d’une série temporelle, y compris le tag __name__ avec le nom d’une métrique.

Le paramètre tags_to_columns permet de spécifier qu’un tag donné doit également être stocké dans une colonne distincte en plus de la map au sein de la colonne tags :

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

Cette instruction ajoute les colonnes instance et job à la table cible interne des tags. Les valeurs des tags instance et job seront stockées à la fois dans ces colonnes et dans la colonne tags.

Dans les tables créées par d’anciennes versions de ClickHouse, la colonne tags contient uniquement les tags sans colonnes dédiées et sans le nom de la métrique, et la colonne all_tags est une colonne éphémère qui était remplie lors de l’insertion avec tous les tags à l’exception du nom de la métrique.

​

Moteurs des tables cibles internes

Par défaut, les tables cibles internes utilisent les moteurs de table suivants :

• la table samples utilise MergeTree ;
• la table recent samples utilise MergeTree, partitionné en compartiments de 5 heures (voir le paramètre recent_samples_partition_by), avec un TTL dérivé du paramètre recent_samples_ttl_seconds et avec ttl_only_drop_parts activé, de sorte que les parties expirées sont supprimées dans leur intégralité ;
• la table tags utilise AggregatingMergeTree, car les mêmes données sont souvent insérées plusieurs fois dans cette table ; il faut donc un moyen de supprimer les doublons, et ce moteur est également nécessaire pour effectuer une agrégation sur les colonnes min_time et max_time ;
• la table familles de métriques utilise ReplacingMergeTree, car les mêmes données sont souvent insérées plusieurs fois dans cette table ; il faut donc un moyen de supprimer les doublons.

La famille de moteurs des tables internes générées suit le paramètre default_table_engine au niveau de la requête : avec default_table_engine = ReplicatedMergeTree ou SharedMergeTree, les tables internes utilisent les moteurs Replicated ou Shared correspondants. Avec default_table_engine = None (ou toute autre valeur), les moteurs des tables internes doivent être spécifiés explicitement.

Toutes les tables internes doivent avoir le même type de réplication : si l’une d’elles est répliquée (ou partagée), les autres tables internes doivent également être répliquées (ou partagées), sans quoi leur contenu divergerait entre les répliques. Par exemple, déclarer SAMPLES INNER ENGINE = ReplicatedMergeTree(...) exige que les autres moteurs internes soient également répliqués - soit déclarés explicitement, soit générés avec default_table_engine = ReplicatedMergeTree.

D’autres moteurs de table peuvent également être utilisés pour les tables cibles internes si cela est explicitement spécifié :

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES ENGINE=ReplicatedMergeTree
RECENT SAMPLES ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRIC FAMILIES ENGINE=ReplicatedReplacingMergeTree

La table tags conserve les colonnes de tag (et le Map tags) en dehors de sa clé de tri, ce que AggregatingMergeTree refuse par défaut (voir allow_dimensions_outside_sorting_key). C’est sans danger ici, car ces colonnes dépendent fonctionnellement de id, qui fait partie de la clé de tri, de sorte que toutes les lignes qu’une fusion en arrière-plan regroupe partagent les mêmes valeurs. Lorsque la table interne de tags est générée ou que son moteur est spécifié en intégré comme ci-dessus, TimeSeries y définit automatiquement allow_dimensions_outside_sorting_key = 1 ; pour une table de tags d’agrégation externe créée manuellement, vous devez le définir vous-même.

​

Tables cibles externes

Il est possible de faire en sorte qu’une table TimeSeries utilise une table créée manuellement :

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;

Une table externe peut également servir de cible pour les échantillons récents (la clause RECENT SAMPLES my_recent_samples_table). Une telle table doit comporter les mêmes colonnes qu’une table samples externe et doit conserver au moins recent_samples_ttl_seconds secondes de données, ce qui relève de la responsabilité de l’utilisateur.

Les types de colonnes des tables externes (id, timestamp, value et les <tag_value_column> répertoriées dans tags_to_columns) doivent correspondre à ceux que la table TimeSeries générerait sinon en interne (voir table samples, table des tags et table des familles de métriques pour les contraintes de type). Les incompatibilités de type sont signalées lors de CREATE.

Le type de la colonne id d’une table tags externe et l’expression générant les identifiants sont enregistrés dans les paramètres id_type et id_generator lors de CREATE (à partir de la version 2), de sorte que la définition de la table TimeSeries les conserve : par exemple, CREATE TABLE ... AS my_table lit le type de id depuis la définition de my_table sans lire ses tables cibles externes. Si le paramètre id_generator n’est pas spécifié, il prend la valeur DEFAULT déclarée sur la colonne id de la table externe (le cas échéant), sinon celle du générateur canonique dérivé du type de id. L’expression enregistrée est utilisée pour générer id même si la valeur DEFAULT de la table externe change par la suite — voir la colonne id pour plus de détails.

​

Modifier les paramètres

Deux paramètres peuvent être modifiés aprè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;

Notez que la modification de id_generator alors que des données sont déjà présentes dans la table Tags peut produire des ID différents pour la même combinaison métrique+tag — les anciennes lignes conservent leurs anciens ID, les nouvelles lignes utilisent le nouveau générateur.

Les autres paramètres ne peuvent pas être modifiés avec ALTER ... MODIFY SETTING : la plupart sont figés dans le schéma des tables internes au moment du CREATE, et le paramètre version est fixé automatiquement au moment du CREATE et identifie le schéma lui-même (voir versionnement du schéma).

​

Paramètres

Voici la liste des paramètres qui peuvent être spécifiés lors de la définition d’une table TimeSeries :

Nom	Type	Par défaut	Description
id_type	Type de données	dépend de la colonne id	Le type de la colonne id des tables cibles. Normalement, le type est déclaré dans les clauses INNER COLUMNS des tables internes ou dans une table tags externe ; le paramètre est enregistré automatiquement lors du CREATE si le type n’est pas conservé autrement dans la définition : si la cible tags est une table externe, ou si le paramètre id_generator est défini. Le paramètre peut aussi être spécifié explicitement à la place de TAGS INNER COLUMNS (id <type>). Nécessite que version soit au moins égale à 2
id_generator	Expression	dépend du type de id	Expression qui calcule l’identifiant (empreinte) d’une série temporelle à partir de ses tags. Si elle n’est pas définie, l’expression par défaut de la colonne id est utilisée. Si l’expression par défaut de la colonne id n’est pas définie non plus, l’expression est choisie automatiquement. Pour une table tags externe, le paramètre est enregistré automatiquement lors du CREATE si version vaut au moins 2 (voir Tables cibles externes)
tags_to_columns	Map		Map indiquant quels tags doivent être placés dans des colonnes distinctes de la table tags. Syntaxe : {'tag1': 'column1', 'tag2' : column2, ...}
use_all_tags_column_to_generate_id	Bool	false	Paramètre obsolète, ne fait rien
store_min_time_and_max_time	Bool	true	Si la valeur est true, la table stocke min_time et max_time pour chaque série temporelle
aggregate_min_time_and_max_time	Bool	true	Lors de la création de la table cible interne tags, ce paramètre active l’utilisation de SimpleAggregateFunction(min, Nullable(DateTime64(3))) au lieu de Nullable(DateTime64(3)) comme type de la colonne min_time, et de même pour la colonne max_time
filter_by_min_time_and_max_time	Bool	true	Si la valeur est true, la table utilise les colonnes min_time et max_time pour filtrer les séries temporelles
samples_index_granularity	UInt64	32768	Définit index_granularity de la table interne samples. Lorsqu’il est défini explicitement, il surcharge index_granularity de la déclaration du moteur. Ignoré pour une table samples externe et un moteur autre que MergeTree
recent_samples_ttl_seconds	UInt64	345600	Durée de conservation de la table cible supplémentaire échantillon récent, dans laquelle chaque échantillon inséré est également écrit. Une table interne échantillon récent reçoit toujours le TTL toDateTime(timestamp) + toIntervalSecond(recent_samples_ttl_seconds) dérivé de ce paramètre (surchargeant tout TTL de la déclaration du moteur) ; une table externe échantillon récent doit conserver au moins ce nombre de secondes de données. Les requêtes dont l’intervalle de temps tient dans la fenêtre TTL privilégient la table échantillon récent à la table samples principale (voir le paramètre au niveau de la requête time_series_prefer_recent_samples_table). La valeur par défaut est de 4 jours ; la valeur effective est figée dans la définition de la table lors de CREATE. Définissez la valeur sur 0 pour désactiver la table échantillon récent
recent_samples_partition_by	Expression	toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))	Clé de partition de la table interne échantillon récent, par exemple toStartOfHour(timestamp). Lorsqu’elle est définie explicitement, elle surcharge la clé de partition de la déclaration du moteur ; si aucune des deux n’est définie, une partition par tranche de 5 heures est utilisée. Ignoré pour une table externe échantillon récent. Nécessite que recent_samples_ttl_seconds soit différent de zéro
recent_samples_index_granularity	UInt64	8192	Définit index_granularity de la table interne échantillon récent. Lorsqu’il est défini explicitement, il surcharge index_granularity de la déclaration du moteur. Ignoré pour une table externe échantillon récent et un moteur autre que MergeTree. Nécessite que recent_samples_ttl_seconds soit différent de zéro
tags_index_granularity	UInt64	8192	Définit index_granularity de la table interne tags. Lorsqu’il est défini explicitement, il surcharge index_granularity de la déclaration du moteur. Ignoré pour une table tags externe et un moteur autre que MergeTree
version	UInt64	5	La version de la table : elle identifie l’ensemble des tables cibles et leur structure. La version est figée automatiquement lors de la création d’une table et ne peut pas être modifiée ensuite ; normalement, elle doit être omise dans la requête CREATE TABLE (voir Versionnement du schéma)

​

versionnement du schéma

Le moteur de table TimeSeries et la couche d’exécution PromQL sont en cours de développement actif : l’ensemble des tables cibles et leur structure peuvent évoluer d’une version de ClickHouse à l’autre. Afin de détecter ces changements, chaque table TimeSeries stocke sa version dans le paramètre version. La version est automatiquement inscrite dans la requête CREATE lors de la création d’une table ; sa valeur correspond à la dernière version connue du serveur (actuellement 5), elle est conservée dans les métadonnées de la table et ne peut pas être modifiée par ALTER. Les tables créées avant l’introduction du paramètre sont considérées comme étant en version 0. En règle générale, il suffit d’omettre le paramètre dans la requête CREATE TABLE : la table reçoit alors la dernière version. Une version explicite est acceptée si le serveur la prend en charge ; la table est alors définie selon les règles de cette version (voir Historique des versions). CREATE TABLE ... AS other_table ne copie pas la version de l’autre table, voir Créer une table AS une table existante.

Un serveur prend en charge une plage de versions, et la version minimale peut différer selon qu’il s’agit de lire avec SELECT, d’écrire avec INSERT, d’utiliser le protocole remote-write de Prometheus ou d’évaluer des requêtes PromQL (les fonctions de table prometheusQuery, prometheusQueryRange et timeSeriesSelector, le dialecte promql et l’API HTTP de requêtes de Prometheus) :

• Si la version d’une table TimeSeries est trop ancienne pour PromQL, les requêtes PromQL qui l’utilisent sont rejetées. L’exception suggère de recréer la table : créez une nouvelle table TimeSeries, copiez les données à l’aide d’une requête INSERT ... SELECT, puis remplacez l’ancienne table par la nouvelle.
• Si la version est trop ancienne pour permettre l’écriture, les requêtes INSERT et le protocole remote-write de Prometheus sont rejetés, tandis que les requêtes SELECT continuent de fonctionner.
• Si la version est trop ancienne pour le serveur, toute requête sur la table (à l’exception de SHOW CREATE TABLE, DETACH et DROP) est rejetée.

​

Historique des versions

Version	Changements
0	Tables créées avant l’introduction du paramètre version, y compris les tables « prealpha » (qui déclaraient les colonnes des tables cibles comme colonnes externes) et les tables dépourvues de la table échantillon récent
1	Introduction du paramètre version
2	Introduction du paramètre id_type : une table associée à une table des tags externe enregistre le type de la colonne id dans id_type et l’expression générant les identifiants dans id_generator, de sorte que sa définition ne dépend pas de la table externe. id_type est également enregistré lorsque id_generator est défini (voir La colonne id)
3	La colonne externe time_series a été renommée samples (voir Colonnes externes). Les tables des versions antérieures conservent l’ancien nom de la colonne, et les fonctions de table prometheusQuery et prometheusQueryRange renvoient la colonne sous le nom utilisé par la table. Les données stockées restent inchangées
4	La target table metrics a été renommée famille de métriques : la table interne est nommée .inner_id.metricfamilies.<uuid> au lieu de .inner_id.metrics.<uuid>, et la définition utilise le mot-clé METRIC FAMILIES au lieu de METRICS. Les données stockées restent inchangées
5	Les nouvelles tables internes de tags utilisant un moteur de la famille MergeTree reçoivent par défaut un index de texte keyValuePairs sur la map tags (voir Table des tags)

​

Fonctions

Voici une liste de fonctions qui acceptent une table TimeSeries comme argument :

• timeSeriesSamples
• timeSeriesTags
• timeSeriesMetricFamilies