Функции

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

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

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, ...]
[DATA db.data_table_name | DATA ENGINE data_table_engine(arguments)]
[TAGS db.tags_table_name | TAGS ENGINE tags_table_engine(arguments)]
[METRICS db.metrics_table_name | METRICS ENGINE metrics_table_engine(arguments)]

​

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

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

CREATE TABLE my_table ENGINE=TimeSeries

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

• prometheus remote-write
• prometheus remote-read

​

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

У таблицы TimeSeries нет собственных данных — всё хранится в её целевых таблицах. Это похоже на то, как работает materialized view, с той разницей, что у materialized view одна целевая таблица, тогда как у таблицы TimeSeries их три: данные, tags и metrics.

Целевые таблицы можно либо явно указать в запросе CREATE TABLE, либо движок таблицы TimeSeries может автоматически сгенерировать внутренние целевые таблицы.

Целевые таблицы бывают следующими:

​

Таблица data

Таблица data содержит временные ряды, связанные с определённым идентификатором.

Таблица data должна содержать следующие столбцы:

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

Любая строка, вставленная в таблицу TimeSeries, фактически будет сохранена в этих трёх целевых таблицах. Таблица TimeSeries содержит все эти столбцы из таблиц данных, tags, metrics.

​

Создание

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

CREATE TABLE my_table ENGINE=TimeSeries

в результате будет создана следующая таблица (это можно увидеть, выполнив SHOW CREATE TABLE my_table):

CREATE TABLE my_table
(
    `id` UUID DEFAULT reinterpretAsUUID(sipHash128(metric_name, all_tags)),
    `timestamp` DateTime64(3),
    `value` Float64,
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `all_tags` Map(String, String),
    `min_time` Nullable(DateTime64(3)),
    `max_time` Nullable(DateTime64(3)),
    `metric_family_name` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
DATA ENGINE = MergeTree ORDER BY (id, timestamp)
DATA INNER UUID '01234567-89ab-cdef-0123-456789abcdef'
TAGS ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id)
TAGS INNER UUID '01234567-89ab-cdef-0123-456789abcdef'
METRICS ENGINE = ReplacingMergeTree ORDER BY metric_family_name
METRICS INNER UUID '01234567-89ab-cdef-0123-456789abcdef'

Итак, столбцы были сгенерированы автоматически, и в этом операторе также есть три внутренних UUID — по одному для каждой созданной внутренней целевой таблицы. (Внутренние UUID обычно не отображаются, пока не задан параметр show_table_uuid_in_table_create_query_if_not_nil .)

Внутренние целевые таблицы имеют имена вида .inner_id.data.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, и каждая целевая таблица содержит столбцы, представляющие собой подмножество столбцов основной таблицы TimeSeries:

CREATE TABLE default.`.inner_id.data.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` String,
    `unit` String,
    `help` String
)
ENGINE = ReplacingMergeTree
ORDER BY metric_family_name

​

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

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

CREATE TABLE my_table
(
    timestamp DateTime64(6)
) ENGINE=TimeSeries

приведёт к тому, что внутренняя таблица данные будет хранить временную метку в микросекундах вместо миллисекунд:

CREATE TABLE default.`.inner_id.data.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` UUID,
    `timestamp` DateTime64(6),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp)

​

Столбец id

Столбец id содержит идентификаторы; каждый идентификатор вычисляется для комбинации имени метрики и тегов. Выражение DEFAULT для столбца id используется для вычисления таких идентификаторов. Как тип столбца id, так и это выражение можно настроить, явно указав их:

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

​

Столбцы 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` String,
`job` String

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

Типы столбцов можно изменить, явно указав их:

CREATE TABLE my_table (
  instance LowCardinality(String),
  job LowCardinality(Nullable(String))
)
ENGINE=TimeSeries
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}

​

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

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

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

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

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

​

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

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

CREATE TABLE data_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 DATA data_for_my_table TAGS tags_for_my_table METRICS metrics_for_my_table;

​

Настройки

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

Имя	Тип	По умолчанию	Описание
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 в качестве аргумента:

• timeSeriesData
• timeSeriesTags
• timeSeriesMetrics