Функции - ClickHouse Documentation

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

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

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

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

У таблицы 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 в качестве аргумента:

​Синтаксис

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

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

​Таблица data

​Таблица tags

​Таблица metrics

​Создание

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

​Столбец id

​Столбцы tags и all_tags

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

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

​Настройки

Синтаксис

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

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

Таблица data

Таблица tags

Таблица metrics

Создание

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

Столбец `id`

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

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

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

Настройки