Это возможность в статусе закрытой предварительной версии, которая в будущих релизах может измениться с нарушением обратной совместимости.
Включите использование движка таблицы TimeSeries
с помощью настройки
enable_time_series_table.
Введите команду set enable_time_series_table = 1.Движок таблицы
TimeSeries доступен в ClickHouse Cloud в статусе закрытой предварительной версии.
В сервисах, участвующих в закрытой предварительной версии, уже настроена
настройка enable_time_series_table. В других сервисах ClickHouse Cloud
эта конфигурация отсутствует, и вы не можете самостоятельно включить движок в
таком сервисе.Синтаксис
У ключевого слова
SAMPLES есть псевдоним DATA, а у ключевого слова METRIC FAMILIES — псевдоним METRICS; оба сохранены для обратной совместимости.
Определение таблицы версии ниже 4 записывается с METRICS, чтобы его мог прочитать более старый сервер.Таблицы версии 9 и ниже могли использовать в качестве целевых вместо внутренних таблиц таблицы, созданные вручную,
например
TAGS db.tags_table_name. Такие таблицы продолжают работать, однако новая таблица последней версии может иметь только внутренние целевые таблицы.Использование
Проще начать с параметров по умолчанию (таблицуTimeSeries можно создать, не указывая список столбцов):
Внешние столбцы
Столбцы таблицы TimeSeries создаются автоматически. Это внешние столбцы: они не хранят данные, а лишь предоставляют интерфейс для SELECT/INSERT. Сами данные хранятся в целевых таблицах. Вот список внешних столбцов:
Пример:
metric_name может быть пустым при вставке — это означает, что имя метрики задаётся в tags, в поле __name__, например:
metric_family, type, unit и help:
Указание внешних столбцов
Внешний столбецsamples можно явно указать в операторе CREATE TABLE, чтобы переопределить его тип по умолчанию Array(Tuple(DateTime64(3), Float64)) (его прежнее имя time_series также допускается). ClickHouse извлекает из кортежа тип временной метки и тип значения и использует их во внутренней таблице samples:
INNER COLUMNS для samples:
CREATE TABLE, объявленные типы должны совпадать.
Целевые таблицы
У таблицыTimeSeries нет собственных данных — всё хранится в её целевых таблицах.
Это похоже на то, как работает materialized view,
с той разницей, что у materialized view одна целевая таблица,
тогда как у таблицы TimeSeries есть три обязательные целевые таблицы: samples, tags и metric families,
а также две необязательные целевые таблицы, включённые по умолчанию: recent samples
(см. настройку recent_samples_ttl_seconds) и time ranges (см. настройку store_time_ranges).
Целевые таблицы можно либо явно указать в запросе CREATE TABLE,
либо движок таблицы TimeSeries может автоматически сгенерировать внутренние целевые таблицы.
Строки, вставленные в таблицу TimeSeries, преобразуются, разбиваются на блоки и вставляются в эти целевые таблицы.
Целевые таблицы бывают следующими:
Таблица samples
Таблица samples содержит временные ряды, связанные с определённым идентификатором. Таблица samples должна содержать следующие столбцы:
Столбцы, которые движок создаёт самостоятельно, используют кодеки сжатия временных рядов:
timestamp CODEC(Delta, T64, ZSTD(3)) и value CODEC(ALP, ZSTD(3)). Почти монотонные временные метки плохо
сжимаются универсальными кодеками и в противном случае могут составлять основную часть размера таблицы samples на диске.
Движок включает ALP для своих внутренних таблиц samples и recent samples, не требуя установки enable_alp_codec.
См. также Настройка типов столбцов.
Таблица recent samples
Таблица recent samples необязательна и включена по умолчанию (см. настройку recent_samples_ttl_seconds; при установке значения0 таблица отключается). Она содержит копию образцов, возраст которых меньше TTL, заданного этой настройкой,
и должна иметь те же столбцы, что и таблица samples.
Генерируемый столбец timestamp использует CODEC(Delta, T64, ZSTD(3)),
а генерируемый столбец value — CODEC(ALP, ZSTD(3)).
Каждый добавленный образец записывается как в таблицу samples, так и в таблицу recent samples.
Запросы, временной диапазон которых входит в окно TTL, читают данные из таблицы recent samples, а не из основной таблицы samples,
поскольку она значительно меньше (это можно отключить настройкой уровня запроса time_series_prefer_recent_samples_table).
TTL внутренней таблицы recent samples всегда определяется настройкой recent_samples_ttl_seconds.
Таблица tags
Таблица tags содержит идентификаторы, вычисляемые для каждой комбинации имени метрики и тегов. Таблица tags должна содержать следующие столбцы:
Новые внутренние таблицы тегов версии 5 и выше с движком семейства
MergeTree имеют инвертированный текстовый индекс по tags:
INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs'). Он ускоряет поиск точных совпадений меток, например
{job="api"} в PromQL, выполняя поиск одновременно по ключу и значению. Сравнения с пустой строкой также
срабатывают для отсутствующих меток и не используют этот индекс.
Индексы, явно объявленные в TAGS INNER COLUMNS, заменяют индекс по умолчанию. В существующих таблицах индексы сохраняются;
чтобы задействовать новый индекс, добавьте и материализуйте его в соответствующей таблице тегов.
Таблицы версии 7 и ниже хранят временной диапазон каждого временного ряда в столбцах
min_time и max_time
таблицы tags, а не в отдельной таблице временных диапазонов
(см. настройки store_min_time_and_max_time, aggregate_min_time_and_max_time и filter_by_min_time_and_max_time).Таблица time ranges
Таблица time ranges является необязательной и включена по умолчанию (см. настройку store_time_ranges; значениеfalse отключает таблицу).
Она содержит временной диапазон (минимальную и максимальную временные метки) каждого временного ряда и используется для фильтрации временных рядов по времени:
запрос за временной диапазон читает только те временные ряды, у которых есть образцы в этом диапазоне.
Таблица time ranges должна содержать следующие столбцы:
Каждая вставка записывает в эту таблицу временной диапазон вставленных образцов каждого временного ряда, а внутренняя таблица time ranges
использует движок AggregatingMergeTree, чтобы при слиянии объединять эти диапазоны в один для каждого временного ряда.
Таблица metric families
Таблица metric families содержит информацию о собираемых семействах метрик, их типах и описаниях. Семейство метрик — это группа метрик с одинаковым именем (тег__name__) и одинаковым типом; например, histogram — это семейство метрик, состоящее из нескольких метрик.
Таблица metric families должна иметь следующие столбцы:
Создание
Существует несколько способов создать таблицу с движкомTimeSeries.
Самый простой оператор
SHOW CREATE TABLE my_table):
INNER COLUMNS. Настройка recent_samples_ttl_seconds была записана в предложение SETTINGS
со значением по умолчанию: эта настройка определяет TTL таблицы recent samples, поэтому её фактическое значение фиксируется при создании.
Также последняя версия схемы была зафиксирована в настройке version (см. Версионирование схемы).
Внутренние целевые таблицы имеют имена вида .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
.inner_id.timeranges.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
и у каждой целевой таблицы есть собственный набор столбцов:
Создание таблицы AS на основе существующей таблицы
ОператорCREATE TABLE new_table AS existing_table создаёт таблицу TimeSeries с той же конфигурацией, что и у existing_table,
которая должна быть таблицей TimeSeries.
Из existing_table копируются:
- предложение
SETTINGS, кромеversion: новая таблица всегда получает последнюю версию. Настройки, указанные в самом операторе, объединяются со скопированными по имени, поэтому указанная настройка имеет приоритет над скопированной, аname = DEFAULTсбрасывает скопированную настройку к значению по умолчанию; - предложения
INNER COLUMNSиINNER ENGINEкаждой внутренней таблицы. Изменённые вручную столбцы (например, дополнительные столбцы, столбцы с кодеком или выражением DEFAULT) и изменённые вручную части движка (например, движок с аргументами, пользовательский ключ сортировки или настройка движка) сохраняются, остальные столбцы и части движка приводятся в соответствие настройкам новой таблицы — так, чтобы, например, указанные в оператореtags_to_columns,store_time_rangesилиtags_index_granularityвступили в силу.
id, временной метки и значения, а также тип репликации внутренних движков (MergeTree,
ReplicatedMergeTree или SharedMergeTree) также берутся из existing_table, если оператор не задаёт их явно.
Список внешних столбцов генерируется заново, а не копируется.
В качестве existing_table можно использовать таблицу, созданную более старой версией ClickHouse: новая таблица получит текущую
структуру, например текущий тип id и выражение идентификатора по умолчанию, а изменённые вручную части, скопированные из
existing_table, будут приведены в соответствие с ней.
Настройка типов столбцов
Вы можете настраивать типы столбцов во внутренних целевых таблицах с помощью предложенияINNER COLUMNS. Например, чтобы хранить временные метки в микросекундах, а значения — как Float32, используйте:
Столбец id
Столбец id содержит идентификаторы; каждый из них вычисляется для комбинации имени метрики и меток.
Тип и выражение DEFAULT, используемое для генерации идентификаторов, можно настроить с помощью предложения TAGS INNER COLUMNS:
id может иметь любой сопоставимый тип, кроме Nullable. Типы id, объявленные во внутренних таблицах samples и tags, должны совпадать.
Если для столбца id не указано выражение DEFAULT, ClickHouse автоматически выберет выражение DEFAULT на основе типа id, но только если тип id является одним из следующих: UUID, UInt64, UInt128, FixedString(16), те же типы, обёрнутые в LowCardinality, или кортежем из двух таких типов. Для такого кортежа автоматически выбранное выражение вычисляет хеш имени метрики в первом компоненте и хеш всех меток во втором компоненте.
Тип идентификатора LowCardinality, например Tuple(UInt64, LowCardinality(UUID)), хранит идентификаторы в словарной кодировке: таблица samples сохраняет небольшие словари для каждого блока с индексами словаря вместо повторения полного идентификатора в каждой строке, что уменьшает объём данных, считываемых запросами.
В таблицах версии 9 и более ранних тип и выражение можно было вместо этого объявить в параметрах id_type и id_generator
(см. Настройки более ранних версий). CREATE TABLE ... AS для такой таблицы не копирует эти параметры:
копия наследует тип id и получает автоматически выбранное для него выражение DEFAULT.
Столбец tags
Столбец tags содержит все теги временного ряда, включая тег __name__ с именем метрики.
Настройка tags_to_columns позволяет указать, что определённый тег также следует хранить в отдельном столбце
в дополнение к карте внутри столбца tags:
instance и job во внутреннюю целевую таблицу tags.
Значения тегов instance и job будут храниться как в этих столбцах, так и в столбце tags.
В таблицах, созданных более ранними версиями ClickHouse, столбец
tags содержит только теги без выделенных
столбцов и без имени метрики, а столбец all_tags является эфемерным столбцом, который при вставке заполнялся
всеми тегами, кроме имени метрики.Движки внутренних целевых таблиц
По умолчанию внутренние целевые таблицы используют следующие движки таблиц:- таблица образцов использует MergeTree;
- таблица недавних образцов использует MergeTree, разбитый на 5-часовые бакеты (см. настройку recent_samples_partition_by), с
TTL, определяемым настройкой recent_samples_ttl_seconds, и с включённымttl_only_drop_parts, поэтому устаревшие части удаляются целиком; - таблица tags использует ReplacingMergeTree, поскольку одни и те же данные часто вставляются в эту таблицу несколько раз, поэтому необходим способ
удалять дубликаты (таблицы версии 7 или более ранней вместо этого используют AggregatingMergeTree, поскольку агрегируют в этой таблице столбцы
min_timeиmax_time). Большинство дубликатов даже не попадает в таблицу: кэш дедупликации таблицыTimeSeriesпропускает недавно записанные временные ряды (см. настройкуtags_deduplication_cache_expiration_seconds; таблица версии 7 или более ранней использует этот кэш, только если не хранитmin_timeиmax_time, см. настройкуstore_min_time_and_max_time); - таблица time ranges использует AggregatingMergeTree, поскольку каждая вставка записывает временной диапазон вставленных образцов, а диапазоны одного и того же временного ряда должны сливаться в один;
- таблица metric families использует ReplacingMergeTree, поскольку одни и те же данные часто вставляются в эту таблицу несколько раз, поэтому необходим способ
удалять дубликаты. Большинство дубликатов даже не попадает в таблицу: кэш дедупликации таблицы
TimeSeriesпропускает недавно записанные семейства метрик (см. настройкуmetric_families_deduplication_cache_expiration_seconds).
default_table_engine:
при default_table_engine = ReplicatedMergeTree или SharedMergeTree внутренние таблицы используют соответствующие
движки Replicated или Shared. При default_table_engine = None (или любом другом значении) движки внутренних таблиц
должны быть указаны явно.
Все внутренние таблицы должны иметь одинаковый тип репликации: если одна из них реплицируемая (или общая), остальные внутренние
таблицы также должны быть реплицируемыми (или общими), иначе их содержимое будет различаться между репликами. Например,
объявление SAMPLES INNER ENGINE = ReplicatedMergeTree(...) требует, чтобы остальные внутренние движки также были реплицируемыми —
либо объявленными явно, либо созданными с default_table_engine = ReplicatedMergeTree.
Для внутренних целевых таблиц также можно использовать другие движки таблиц, если это указано:
tags) вне своего ключа сортировки,
что AggregatingMergeTree по умолчанию запрещает (см. allow_dimensions_outside_sorting_key).
Здесь это безопасно, потому что эти столбцы функционально зависят от id, который является частью ключа сортировки, поэтому все
строки, которые объединяются при фоновом слиянии, имеют одинаковые значения. Когда агрегирующий движок внутренней таблицы tags
генерируется (для таблиц версии 7 и более ранних) или задаётся непосредственно, TimeSeries автоматически устанавливает для неё allow_dimensions_outside_sorting_key = 1.
Срок хранения
По умолчанию у таблицы samples не заданTTL, поэтому образцы хранятся бессрочно.
Чтобы удалять устаревшие образцы, задайте TTL в движке внутренней таблицы samples:
ttl_only_drop_parts часть не перезаписывается, а удаляется целиком, когда срок хранения истёк у всех её образцов.
При партиционировании по дню в UTC образцы разных дней хранятся в разных частях, поэтому данные каждого дня удаляются, как только истекает срок хранения самого нового образца за этот день.
Настройка recent_samples_partition_by сохраняет стандартные 5-часовые партиции таблицы recent samples, но тоже вычисляет их в UTC.
Если ключ партиционирования зависит от часового пояса сервера, то после смены часового пояса запрос может пропускать части, содержащие подходящие образцы.
У таблицы recent samples есть собственный TTL, который задаётся настройкой recent_samples_ttl_seconds.
TTL таблицы samples должен быть больше этого значения, иначе запрос, временной диапазон которого укладывается в окно recent samples,
может вернуть образцы, уже удалённые из таблицы samples.
По умолчанию у таблицы tags нет TTL: временной ряд остаётся в ней даже после удаления всех его образцов.
Изменение настроек
Следующие настройки можно изменить после выполненияCREATE:
metric_families_deduplication_cache_size_bytes,metric_families_deduplication_cache_expiration_secondstags_deduplication_cache_size_bytes,tags_deduplication_cache_expiration_seconds
В таблицах более ранних версий можно также изменять те настройки этих версий, которые не влияют на сохранённые данные:
id_generator (версия 9 и ниже) и filter_by_min_time_and_max_time (версия 7 и ниже).
Если изменить id_generator, когда в таблице tags уже есть данные, одна и та же комбинация метрики и метки может получить разные ID: старые строки сохраняют прежние ID, а для новых используется новый генератор.
После такого изменения конечные точки HTTP API Prometheus /api/v1/series, /api/v1/labels и /api/v1/label/<name>/values
могут возвращать временные ряды, записанные с предыдущим генератором, даже если в запрошенном временном диапазоне у них нет ни одного образца.ALTER ... MODIFY SETTING: большинство из них фиксируется в схеме внутренних таблиц при выполнении CREATE,
а настройка version автоматически закрепляется при CREATE и определяет саму схему (см. Версионирование схемы).
Настройки
Ниже приведён список настроек, которые можно указать при определении таблицыTimeSeries:
Настройки более ранних версий
Следующие настройки применяются только к таблицам более ранних версий, поэтому у таблицы последней версии их быть не может:Версионирование схемы
Движок таблицыTimeSeries и слой выполнения PromQL активно развиваются:
набор целевых таблиц и их структура могут меняться от версии к версии ClickHouse.
Чтобы такие изменения можно было отследить, каждая таблица TimeSeries хранит свою версию в настройке version.
Версия автоматически фиксируется в запросе CREATE при создании таблицы — её значением становится последняя версия, известная серверу (сейчас 9), —
сохраняется в метаданных таблицы и не может быть изменена с помощью ALTER. Таблицы, созданные до появления этой настройки, считаются таблицами версии 0.
Обычно эту настройку достаточно просто не указывать в запросе CREATE TABLE — тогда таблица получит последнюю версию.
Явно заданное значение version принимается, если сервер поддерживает эту версию; в этом случае таблица определяется так, как это делает соответствующая версия (см. История версий).
CREATE TABLE ... AS other_table не копирует версию другой таблицы, см. Создание таблицы AS на основе существующей таблицы.
Сервер поддерживает диапазон версий, причём минимальная версия может отличаться для чтения через SELECT, для записи через INSERT
или по протоколу Prometheus remote-write, а также для вычисления PromQL (табличные функции prometheusQuery,
prometheusQueryRange,
и timeSeriesSelector,
диалект promql и HTTP query API Prometheus):
- Если версия таблицы
TimeSeriesслишком старая для PromQL, запросы PromQL к ней отклоняются. В тексте исключения предлагается пересоздать таблицу: создайте новую таблицуTimeSeries, скопируйте данные запросомINSERT ... SELECTи замените старую таблицу новой. - Если версия слишком старая для записи, запросы
INSERTи протокол Prometheus remote-write отклоняются, при этом запросыSELECTпродолжают работать. - Если версия слишком старая для сервера в принципе, отклоняется любой запрос к таблице (кроме
SHOW CREATE TABLE,DETACHиDROP).
История версий
Функции
Ниже приведён список функций, поддерживающих таблицуTimeSeries в качестве аргумента: