> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Движок таблицы, хранящий временные ряды, то есть набор значений, связанных с временными метками и тегами (или метками). # Функции export const CloudNotSupportedBadge = () => { return
Not supported in ClickHouse Cloud
; }; export const ExperimentalBadge = () => { return
Experimental feature. Learn more.
; }; Движок таблицы для хранения временных рядов, то есть набора значений, связанных с временными метками и тегами (или метками): ```sql theme={null} metric_name1[tag1=value1, tag2=value2, ...] = {timestamp1: value1, timestamp2: value2, ...} metric_name2[...] = ... ``` Это экспериментальная возможность, которая в будущих релизах может измениться с нарушением обратной совместимости. Включите использование движка таблицы TimeSeries с помощью настройки [allow\_experimental\_time\_series\_table](/ru/reference/settings/session-settings#allow_experimental_time_series_table). Введите команду `set allow_experimental_time_series_table = 1`.
## Синтаксис
```sql theme={null} 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` можно создать, не указывая список столбцов): ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries ``` Затем эту таблицу можно использовать со следующими протоколами (в конфигурации сервера должен быть назначен порт): * [prometheus remote-write](/ru/concepts/features/interfaces/prometheus#remote-write) * [prometheus remote-read](/ru/concepts/features/interfaces/prometheus#remote-read)
## Целевые таблицы
У таблицы `TimeSeries` нет собственных данных — всё хранится в её целевых таблицах. Это похоже на то, как работает [materialized view](/ru/reference/statements/create/view#materialized-view), с той разницей, что у materialized view одна целевая таблица, тогда как у таблицы `TimeSeries` их три: [данные](#data-table), [tags](#tags-table) и [metrics](#metrics-table). Целевые таблицы можно либо явно указать в запросе `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 [данные](#data-table) table) | `id` идентифицирует комбинацию имени метрики и тегов. Выражение DEFAULT задаёт способ вычисления такого идентификатора | | `metric_name` | \[x] | `LowCardinality(String)` | `String` or `LowCardinality(String)` | Имя метрики | | `` | \[ ] | `String` | `String` or `LowCardinality(String)` or `LowCardinality(Nullable(String))` | Значение конкретного тега; имя тега и имя соответствующего столбца задаются в настройке [tags\_to\_columns](#settings) | | `tags` | \[x] | `Map(LowCardinality(String), String)` | `Map(String, String)` or `Map(LowCardinality(String), String)` or `Map(LowCardinality(String), LowCardinality(String))` | Карта тегов, за исключением тега `__name__`, содержащего имя метрики, а также тегов с именами, перечисленными в настройке [tags\_to\_columns](#settings) | | `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](#settings) имеет значение `true` | | `max_time` | \[ ] | `Nullable(DateTime64(3))` | `DateTime64(X)` or `Nullable(DateTime64(X))` | Максимальная временная метка временного ряда с данным `id`. Столбец создаётся, если [store\_min\_time\_and\_max\_time](#settings) имеет значение `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` содержит все эти столбцы из таблиц [данных](#data-table), [tags](#tags-table), [metrics](#metrics-table).
## Создание
Таблицу с движком таблицы `TimeSeries` можно создать несколькими способами. Самый простой оператор ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries ``` в результате будет создана следующая таблица (это можно увидеть, выполнив `SHOW CREATE TABLE my_table`): ```sql theme={null} 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](/ru/reference/settings/session-settings#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`: ```sql theme={null} CREATE TABLE default.`.inner_id.data.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` String, `unit` String, `help` String ) ENGINE = ReplacingMergeTree ORDER BY metric_family_name ```
## Настройка типов столбцов
Вы можете изменить типы почти любых столбцов во внутренних целевых таблицах, явно указав их при определении основной таблицы. Например, ```sql theme={null} CREATE TABLE my_table ( timestamp DateTime64(6) ) ENGINE=TimeSeries ``` приведёт к тому, что внутренняя таблица [данные](#data-table) будет хранить временную метку в микросекундах вместо миллисекунд: ```sql theme={null} 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`, так и это выражение можно настроить, явно указав их: ```sql theme={null} CREATE TABLE my_table ( id UInt64 DEFAULT sipHash64(metric_name, all_tags) ) ENGINE=TimeSeries ```
## Столбцы `tags` и `all_tags`
Есть два столбца, содержащих карты тегов, — `tags` и `all_tags`. В этом примере они означают одно и то же, однако могут различаться, если используется настройка `tags_to_columns`. Эта настройка позволяет указать, что определённый тег следует хранить в отдельном столбце, а не в карте внутри столбца `tags`: ```sql theme={null} CREATE TABLE my_table ENGINE = TimeSeries SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'} ``` Этот оператор добавит столбцы: ```sql theme={null} `instance` String, `job` String ``` к определениям как `my_table`, так и её внутренней целевой [таблицы `tags`](#tags-table). В этом случае столбец `tags` не будет содержать теги `instance` и `job`, но столбец `all_tags` будет их содержать. Столбец `all_tags` является эфемерным, и его единственное назначение — использоваться в выражении DEFAULT для столбца `id`. Типы столбцов можно изменить, явно указав их: ```sql theme={null} CREATE TABLE my_table ( instance LowCardinality(String), job LowCardinality(Nullable(String)) ) ENGINE=TimeSeries SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'} ```
## Движки внутренних целевых таблиц
По умолчанию внутренние целевые таблицы используют следующие движки таблиц: * таблица [данные](#data-table) использует [MergeTree](/ru/reference/engines/table-engines/mergetree-family/mergetree); * таблица [tags](#tags-table) использует [AggregatingMergeTree](/ru/reference/engines/table-engines/mergetree-family/aggregatingmergetree), поскольку одни и те же данные часто вставляются в эту таблицу несколько раз, поэтому необходим способ удалять дубликаты, а также потому, что для столбцов `min_time` и `max_time` требуется выполнять агрегацию; * таблица [metrics](#metrics-table) использует [ReplacingMergeTree](/ru/reference/engines/table-engines/mergetree-family/replacingmergetree), поскольку одни и те же данные часто вставляются в эту таблицу несколько раз, поэтому необходим способ удалять дубликаты. Для внутренних целевых таблиц также можно использовать другие движки таблиц, если это указано: ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries DATA ENGINE=ReplicatedMergeTree TAGS ENGINE=ReplicatedAggregatingMergeTree METRICS ENGINE=ReplicatedReplacingMergeTree ```
## Внешние целевые таблицы
Можно настроить таблицу `TimeSeries` так, чтобы она использовала таблицу, созданную вручную: ```sql theme={null} 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](#tags-table). Синтаксис: `{'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](/ru/reference/functions/table-functions/timeSeriesData) * [timeSeriesTags](/ru/reference/functions/table-functions/timeSeriesTags) * [timeSeriesMetrics](/ru/reference/functions/table-functions/timeSeriesMetrics)