Движок таблицы для хранения временных рядов, то есть набора значений, связанных с временными метками и тегами (или метками):

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

Это экспериментальная возможность, которая в будущих релизах может измениться с нарушением обратной совместимости. Включите использование движка таблицы TimeSeries с помощью настройки allow_experimental_time_series_table. Введите команду set allow_experimental_time_series_table = 1.

Синтаксис

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

У ключевого слова SAMPLES есть псевдоним DATA, сохранённый для обратной совместимости.

Использование

Проще начать с параметров по умолчанию (таблицу TimeSeries можно создать, не указывая список столбцов):

CREATE TABLE my_table ENGINE=TimeSeries

Затем эту таблицу можно использовать со следующими протоколами (в конфигурации сервера должен быть назначен порт):

Внешние столбцы

Столбцы таблицы TimeSeries создаются автоматически. Это внешние столбцы: они не хранят данные, а лишь предоставляют интерфейс для SELECT/INSERT. Сами данные хранятся в целевых таблицах. Вот список внешних столбцов:

Имя	Тип	Описание
`metric_name`	`String`	Имя метрики
`tags`	`Map(String, String)`	Карта тегов (меток) для временного ряда
`time_series`	`Array(Tuple(DateTime64(3), Float64))` по умолчанию	Массив пар (временная метка, значение) для временного ряда. Тип временной метки в кортеже и тип его скалярного элемента можно определить по объявлению `INNER COLUMNS` для samples (см. Указание внешних столбцов)
`metric_family`	`String`	Имя семейства метрик (для метаданных метрик)
`type`	`String`	Тип метрики (например, “counter”, “gauge”)
`unit`	`String`	Единица измерения метрики
`help`	`String`	Описание метрики

Пример:

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 может быть пустым при вставке — это означает, что имя метрики задаётся в tags, в поле __name__, например:

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

Чтобы вставить метаданные метрик, вставьте значения в столбцы metric_family, type, unit и 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')

Указание внешних столбцов

Внешний столбец time_series можно явно указать в операторе CREATE TABLE, чтобы переопределить его тип по умолчанию Array(Tuple(DateTime64(3), Float64)). ClickHouse извлекает из кортежа тип временной метки и скалярный тип и использует их во внутренней таблице samples:

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

Это равносильно прямому объявлению типов столбцов временной метки и значения в предложении INNER COLUMNS для samples:

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

Если обе формы используются в одном операторе CREATE TABLE, объявленные типы должны совпадать.

Целевые таблицы

У таблицы TimeSeries нет собственных данных — всё хранится в её целевых таблицах. Это похоже на то, как работает materialized view, с той разницей, что у materialized view одна целевая таблица, тогда как у таблицы TimeSeries их три: samples, tags и metrics. Целевые таблицы можно либо явно указать в запросе CREATE TABLE, либо движок таблицы TimeSeries может автоматически сгенерировать внутренние целевые таблицы. Строки, вставленные в таблицу TimeSeries, преобразуются, разбиваются на блоки и вставляются в эти три целевые таблицы. Целевые таблицы бывают следующими:

Таблица samples

Таблица samples содержит временные ряды, связанные с определённым идентификатором. Таблица samples должна содержать следующие столбцы:

Имя	Обязательно?	Тип по умолчанию	Возможные типы	Описание
`id`	[x]	`UUID`	любой	Идентифицирует комбинацию имени метрики и тегов
`timestamp`	[x]	`DateTime64(3)`	`DateTime64(X)`	Момент времени
`value`	[x]	`Float64`	`Float32` или `Float64`	Значение, связанное с `timestamp`

Таблица tags

Таблица tags содержит идентификаторы, вычисляемые для каждой комбинации имени метрики и тегов. Таблица tags должна содержать следующие столбцы:

Имя	Обязательный?	Тип по умолчанию	Возможные типы	Описание
`id`	[x]	`UUID`	any (must match the type of `id` in the samples table)	`id` идентифицирует комбинацию имени метрики и тегов. Выражение DEFAULT задаёт способ вычисления такого идентификатора
`metric_name`	[x]	`LowCardinality(String)`	`String` or `LowCardinality(String)`	Имя метрики
`<tag_value_column>`	[ ]	`String`	`String` or `LowCardinality(String)` or `LowCardinality(Nullable(String))`	Значение конкретного тега; имя тега и имя соответствующего столбца задаются в настройке tags_to_columns
`tags`	[x]	`Map(LowCardinality(String), String)`	`Map(String, String)` or `Map(LowCardinality(String), String)` or `Map(LowCardinality(String), LowCardinality(String))`	Карта тегов, за исключением тега `__name__`, содержащего имя метрики, а также тегов с именами, перечисленными в настройке tags_to_columns
`all_tags`	[ ]	`Map(String, String)`	`Map(String, String)` or `Map(LowCardinality(String), String)` or `Map(LowCardinality(String), LowCardinality(String))`	Эфемерный столбец: каждая строка содержит карту всех тегов, за исключением только тега `__name__`, содержащего имя метрики. Этот столбец используется только при вычислении `id`
`min_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` or `Nullable(DateTime64(X))`	Минимальная временная метка временного ряда с данным `id`. Столбец создаётся, если store_min_time_and_max_time имеет значение `true`
`max_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` or `Nullable(DateTime64(X))`	Максимальная временная метка временного ряда с данным `id`. Столбец создаётся, если store_min_time_and_max_time имеет значение `true`

Таблица metrics

Таблица metrics содержит информацию о собираемых метриках, их типах и описаниях. Таблица metrics должна иметь следующие столбцы:

Имя	Обязательный?	Тип по умолчанию	Возможные типы	Описание
`metric_family_name`	[x]	`String`	`String` или `LowCardinality(String)`	Имя семейства метрик
`type`	[x]	`LowCardinality(String)`	`String` или `LowCardinality(String)`	Тип семейства метрик: один из “counter”, “gauge”, “summary”, “stateset”, “histogram”, “gaugehistogram”
`unit`	[x]	`LowCardinality(String)`	`String` или `LowCardinality(String)`	Единица измерения, используемая в метрике
`help`	[x]	`String`	`String` или `LowCardinality(String)`	Описание метрики

Создание

Таблицу с движком таблицы TimeSeries можно создать несколькими способами. Самый простой оператор

CREATE TABLE my_table ENGINE=TimeSeries

в результате будет создана следующая таблица (это можно увидеть, выполнив 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) SETTINGS allow_dimensions_outside_sorting_key = 1
METRICS INNER COLUMNS
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
METRICS INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name

Итак, столбцы были сгенерированы автоматически, и при этом есть три внутренние целевые таблицы с собственными определениями столбцов, сохранёнными в предложениях INNER COLUMNS. Внутренние целевые таблицы имеют имена вида .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, и каждая целевая таблица имеет собственный набор столбцов:

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)
SETTINGS allow_dimensions_outside_sorting_key = 1

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

Создание таблицы AS на основе существующей таблицы

Оператор CREATE TABLE new_table AS existing_table копирует из existing_table:

SETTINGS
INNER COLUMNS для каждого вида
INNER ENGINE для каждого вида

Этот оператор недопустим, если у existing_table есть внешние цели. Внешний список столбцов формируется заново, а не копируется.

Настройка типов столбцов

Вы можете настраивать типы столбцов во внутренних целевых таблицах с помощью предложения INNER COLUMNS. Например, чтобы хранить временные метки в микросекундах, а значения — как Float32:

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

То же выражение можно использовать, чтобы указать кодеки и другие атрибуты столбца:

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

Столбец `id`

Столбец id содержит идентификаторы; каждый из них вычисляется для комбинации имени метрики и тегов. Тип и выражение DEFAULT, используемое для генерации идентификаторов, можно настроить с помощью конструкции TAGS INNER COLUMNS:

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

Тип столбца id должен быть одним из следующих: UUID, UInt64, UInt128 или FixedString(16). Если выражение DEFAULT не указано, ClickHouse автоматически выберет его на основе типа id. Типы id, объявленные во внутренних таблицах samples и tags, должны совпадать. Параметр id_generator позволяет выполнить ту же настройку без использования конструкции INNER COLUMNS:

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

Если этот параметр задан, для генерации id используется именно он, даже если DEFAULT столбца содержит другое выражение.

Столбцы `tags` и `all_tags`

Есть два столбца, содержащих карты тегов, — tags и all_tags. В этом примере они означают одно и то же, однако могут различаться, если используется настройка tags_to_columns. Эта настройка позволяет указать, что определённый тег следует хранить в отдельном столбце, а не в карте внутри столбца tags:

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

Этот оператор добавит столбцы instance и job во внутреннюю целевую таблицу tags. В этом случае столбец tags не будет содержать теги instance и job, но столбец all_tags будет их содержать. Столбец all_tags является эфемерным, и его единственное назначение — использоваться в выражении DEFAULT для столбца id.

Движки внутренних целевых таблиц

По умолчанию внутренние целевые таблицы используют следующие движки таблиц:

таблица samples использует MergeTree;
таблица tags использует AggregatingMergeTree, поскольку одни и те же данные часто вставляются в эту таблицу несколько раз, поэтому необходим способ удалять дубликаты, а также потому, что для столбцов min_time и max_time требуется выполнять агрегацию;
таблица metrics использует ReplacingMergeTree, поскольку одни и те же данные часто вставляются в эту таблицу несколько раз, поэтому необходим способ удалять дубликаты.

Для внутренних целевых таблиц также можно использовать другие движки таблиц, если это указано:

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

Таблица tags хранит столбцы тегов (и Map tags/all_tags) вне своего ключа сортировки, что AggregatingMergeTree по умолчанию запрещает (см. allow_dimensions_outside_sorting_key). Здесь это безопасно, потому что эти столбцы функционально зависят от id, который является частью ключа сортировки, поэтому все строки, которые объединяются при фоновом слиянии, имеют одинаковые значения. Когда внутренняя таблица tags создаётся или её движок задаётся непосредственно, как показано выше, TimeSeries автоматически устанавливает для неё allow_dimensions_outside_sorting_key = 1; для созданной вручную агрегирующей внешней таблицы tags вы должны установить этот параметр самостоятельно.

Внешние целевые таблицы

Таблицу TimeSeries можно настроить так, чтобы она использовала таблицу, созданную вручную:

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;

Типы столбцов внешних таблиц (id, timestamp, value и <tag_value_column>, перечисленные в tags_to_columns) должны совпадать с теми, которые таблица TimeSeries в противном случае сгенерировала бы внутри системы (ограничения на типы см. в разделах таблица Samples, таблица Tags и таблица Metrics). О несоответствии типов сообщается во время CREATE. Выражение генератора id для внешней целевой таблицы tags вычисляется во время INSERT в следующем порядке: сначала настройка id_generator (если она задана), затем DEFAULT, объявленный для столбца id внешней таблицы (если он есть), и затем канонический генератор, определяемый типом id. Таким образом, эта настройка имеет приоритет над любым DEFAULT, объявленным для внешней таблицы — подробности см. в разделе Столбец id.

Изменение настроек

После 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;

Обратите внимание: если изменить id_generator, когда данные уже есть в таблице tags, для одной и той же комбинации metric+tag могут создаваться разные идентификаторы — старые строки сохранят прежние идентификаторы, а новые будут использовать новый генератор. Другие настройки нельзя изменить с помощью ALTER ... MODIFY SETTING, потому что они закладываются в схему внутренних таблиц во время CREATE.

Настройки

Ниже приведён список настроек, которые можно указать при определении таблицы TimeSeries:

Имя	Тип	По умолчанию	Описание
`id_generator`	Expression	зависит от типа `id`	Выражение, вычисляющее идентификатор (fingerprint) временного ряда по его тегам. Если не задано, используется выражение по умолчанию для столбца `id`. Если выражение по умолчанию для столбца `id` также не задано, выражение выбирается автоматически
`tags_to_columns`	Map	Map, задающий, какие теги следует вынести в отдельные столбцы таблицы tags. Синтаксис: `{'tag1': 'column1', 'tag2' : column2, ...}`
`use_all_tags_column_to_generate_id`	Bool	true	При формировании выражения для вычисления идентификатора временного ряда этот флаг включает использование в вычислении столбца `all_tags`
`store_min_time_and_max_time`	Bool	true	Если установлено значение true, таблица будет хранить `min_time` и `max_time` для каждого временного ряда
`aggregate_min_time_and_max_time`	Bool	true	При создании внутренней целевой таблицы `tags` этот флаг включает использование `SimpleAggregateFunction(min, Nullable(DateTime64(3)))` вместо просто `Nullable(DateTime64(3))` в качестве типа столбца `min_time`; то же самое относится и к столбцу `max_time`
`filter_by_min_time_and_max_time`	Bool	true	Если установлено значение true, таблица будет использовать столбцы `min_time` и `max_time` для фильтрации временных рядов

Функции

Ниже приведён список функций, поддерживающих таблицу TimeSeries в качестве аргумента:

Справочник по ClickHouse SQL

Движок таблицы TimeSeries

Синтаксис

Использование

Внешние столбцы

Указание внешних столбцов

Целевые таблицы

Таблица samples

Таблица tags

Таблица metrics

Создание

Создание таблицы AS на основе существующей таблицы

Настройка типов столбцов

Столбец `id`

Столбцы `tags` и `all_tags`

Движки внутренних целевых таблиц

Внешние целевые таблицы

Изменение настроек

Настройки

Функции

​Синтаксис

​Использование

​Внешние столбцы

​Указание внешних столбцов

​Целевые таблицы

​Таблица samples

​Таблица tags

​Таблица metrics

​Создание

​Создание таблицы AS на основе существующей таблицы

​Настройка типов столбцов

​Столбец id

​Столбцы tags и all_tags

​Движки внутренних целевых таблиц

​Внешние целевые таблицы

​Изменение настроек

​Настройки

​Функции

Синтаксис

Использование

Внешние столбцы

Указание внешних столбцов

Целевые таблицы

Таблица samples

Таблица tags

Таблица metrics

Создание

Создание таблицы AS на основе существующей таблицы

Настройка типов столбцов

Столбец `id`

Столбцы `tags` и `all_tags`

Движки внутренних целевых таблиц

Внешние целевые таблицы

Изменение настроек

Настройки

Функции