> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > 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). # Moteur de table TimeSeries export const CloudNotSupportedBadge = () => { return
Non pris en charge par ClickHouse Cloud
; }; export const ExperimentalBadge = () => { return
Fonctionnalité expérimentale. En savoir plus.
; }; 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) : ```sql theme={null} 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](/fr/reference/settings/session-settings#allow_experimental_time_series_table). Saisissez la commande `set allow_experimental_time_series_table = 1`.
## Syntaxe
```sql theme={null} 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) : ```sql theme={null} 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](/fr/concepts/features/interfaces/prometheus#remote-write) * [prometheus remote-read](/fr/concepts/features/interfaces/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](#target-tables). 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](#specifying-outer-columns)) | | `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 : ```sql theme={null} 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 : ```sql theme={null} 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` : ```sql theme={null} 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 : ```sql theme={null} 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` : ```sql theme={null} 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](/fr/reference/statements/create/view#materialized-view), à 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](#samples-table), [tags](#tags-table) et [metrics](#metrics-table). 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](#samples-table)) | 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 | | `` | \[ ] | `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](#settings) | | `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](#settings) | | `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](#settings) 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](#settings) 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 ```sql theme={null} 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`) : ```sql theme={null} 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 : ```sql theme={null} CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` ( `id` UUID, `timestamp` DateTime64(3), `value` Float64 ) ENGINE = MergeTree ORDER BY (id, timestamp) ``` ```sql theme={null} 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) ``` ```sql theme={null} 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` : ```sql theme={null} 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 : ```sql theme={null} 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` : ```sql theme={null} 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` : ```sql theme={null} 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` : ```sql theme={null} 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](#tags-table). 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](#samples-table) utilise [MergeTree](/fr/reference/engines/table-engines/mergetree-family/mergetree) ; * la table [tags](#tags-table) utilise [AggregatingMergeTree](/fr/reference/engines/table-engines/mergetree-family/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](#metrics-table) utilise [ReplacingMergeTree](/fr/reference/engines/table-engines/mergetree-family/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é : ```sql theme={null} 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 : ```sql theme={null} 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 `` répertoriées dans [`tags_to_columns`](#settings)) doivent correspondre à ceux que la table `TimeSeries` générerait sinon en interne (voir [Samples table](#samples-table), [Tags table](#tags-table) et [Metrics table](#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`](#settings) (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`](#id-column) 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` ```sql theme={null} 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](#tags-table). 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](/fr/reference/functions/table-functions/timeSeriesSamples) * [timeSeriesTags](/fr/reference/functions/table-functions/timeSeriesTags) * [timeSeriesMetrics](/fr/reference/functions/table-functions/timeSeriesMetrics)