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é expérimentale 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 allow_experimental_time_series_table. Saisissez la commande set allow_experimental_time_series_table = 1.

​

Syntaxe

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

Le mot-clé SAMPLES a pour alias DATA, maintenu pour assurer la rétrocompatibilité.

​

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

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, time_series) 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, time_series, 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 time_series peut être déclarée explicitement dans une instruction CREATE TABLE afin de remplacer son type par défaut Array(Tuple(DateTime64(3), Float64)). ClickHouse extrait du tuple le type d’horodatage et le type scalaire, puis les propage à la table d’échantillons interne :

CREATE TABLE my_table (time_series 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, value Float32)

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 nommées samples, tags et metrics.

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

​

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]	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 des tags, à l’exclusion du tag __name__ qui contient le nom d’une métrique, ainsi que des tags dont les noms sont énumérés dans le paramètre tags_to_columns
all_tags	[ ]	Map(String, String)	Map(String, String) ou Map(LowCardinality(String), String) ou Map(LowCardinality(String), LowCardinality(String))	Colonne éphémère : chaque ligne est une map de tous les tags, à l’exclusion du seul tag __name__ qui contient le nom d’une métrique. Cette colonne sert uniquement au calcul de id
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

​

Table metrics

La table metrics contient des informations sur les métriques collectées, leurs types et leurs descriptions.

La table metrics 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),
    `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

Les colonnes ont donc été générées automatiquement, et il existe également trois tables cibles internes avec leurs propres définitions de colonnes stockées dans les clauses INNER COLUMNS.

Les tables cibles internes portent des noms tels que .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx et chaque table cible possède son propre jeu de colonnes :

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

​

Création d’une table à partir d’une table existante

L’instruction CREATE TABLE new_table AS existing_table copie les éléments suivants de existing_table :

• SETTINGS
• INNER COLUMNS pour chaque type
• INNER ENGINE pour chaque type

L’instruction n’est pas autorisée si existing_table comporte des cibles externes. La liste des colonnes externes est régénérée et non copiée.

​

Modifier le type des 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 :

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

La même clause peut être utilisée pour spécifier des codecs et d’autres attributs de colonne :

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

​

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é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(metric_name, all_tags))

Le type de la colonne id doit être l’un des suivants : UUID, UInt64, UInt128 ou FixedString(16). Si aucune expression DEFAULT n’est définie, ClickHouse la choisira automatiquement en fonction du type de id. Les types de id déclarés dans les tables internes samples et tags doivent correspondre.

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(metric_name, all_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.

​

Les colonnes tags et all_tags

Il existe deux colonnes contenant des maps de tags : tags et all_tags. Dans cet exemple, elles ont la même signification, mais elles peuvent être différentes si le paramètre tags_to_columns est utilisé. Ce paramètre permet de spécifier qu’un tag donné doit être stocké dans une colonne distincte plutôt que dans une 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. Dans ce cas, la colonne tags ne contiendra pas les tags instance et job, mais la colonne all_tags, si. La colonne all_tags est éphémère et sert uniquement à être utilisée dans l’expression DEFAULT de la colonne id.

​

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

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
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRICS ENGINE=ReplicatedReplacingMergeTree

​

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 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;

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 Samples table, Tags table et Metrics table pour les contraintes de type). Les incompatibilités de type sont signalées lors de CREATE.

L’expression du générateur d’identifiant pour une cible de tags externe est évaluée au moment de l’INSERT, dans l’ordre suivant : le paramètre id_generator (s’il est défini), puis la valeur DEFAULT déclarée sur la colonne id de la table externe (le cas échéant), puis le générateur canonique dérivé du type de id. Le paramètre remplace donc toute valeur DEFAULT déclarée sur la table externe — 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(metric_name, all_tags)';
ALTER TABLE my_table MODIFY SETTING filter_by_min_time_and_max_time = 0;

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, car ils sont figés dans le schéma des tables internes au moment du CREATE.

​

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_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
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	true	Lors de la génération d’une expression pour calculer l’identifiant d’une série temporelle, ce paramètre active l’utilisation de la colonne all_tags dans ce calcul
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

​

Fonctions

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

• timeSeriesSamples
• timeSeriesTags
• timeSeriesMetrics