一种用于存储时间序列的表引擎，即一组与时间戳和标签 (或标记) 关联的值：

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

这是一个私有预览功能，未来的发行版中可能会发生不向后兼容的变更。使用 enable_time_series_table 设置启用 TimeSeries 表引擎。输入命令 set enable_time_series_table = 1。

TimeSeries 表引擎在 ClickHouse Cloud 中作为私有预览功能提供。已参与私有预览的服务已配置 enable_time_series_table 设置。其他 ClickHouse Cloud 服务没有此配置，且您无法自行在此类服务上启用该引擎。

语法

CREATE TABLE name [(columns)] ENGINE=TimeSeries
[SETTINGS var1=value1, ...]
[SAMPLES db.samples_table_name | [SAMPLES INNER COLUMNS (...)] [SAMPLES INNER ENGINE engine(arguments)]]
[RECENT SAMPLES db.recent_samples_table_name | [RECENT SAMPLES INNER COLUMNS (...)] [RECENT SAMPLES INNER ENGINE engine(arguments)]]
[TAGS db.tags_table_name | [TAGS INNER COLUMNS (...)] [TAGS INNER ENGINE engine(arguments)]]
[METRIC FAMILIES db.metric_families_table_name | [METRIC FAMILIES INNER COLUMNS (...)] [METRIC FAMILIES INNER ENGINE engine(arguments)]]

关键字 SAMPLES 有一个别名 DATA，关键字 METRIC FAMILIES 有一个别名 METRICS，保留它们都是为了保持向后兼容性。版本低于 4 的表定义使用 METRICS 写入，以便较旧的 server 能够读取它。

用法

一开始先使用默认设置会更简单 (可以在不指定列列表的情况下创建 TimeSeries 表) ：

CREATE TABLE my_table ENGINE=TimeSeries

随后，该表可与以下协议配合使用 (必须在服务器配置中分配端口) ：

外部列

TimeSeries 表的列会自动生成。这些列属于外部列，不存储任何数据，只为 SELECT/INSERT 提供接口。实际数据存储在目标端表中。以下是外部列列表：

Name	Type	Description
`metric_name`	`String`	指标名称
`tags`	`Map(String, String)`	时间序列的标签映射 (标记)
`samples`	`Array(Tuple(DateTime64(3), Float64))` (默认)	时间序列的 (timestamp, value) 对数组。该 Tuple 的 timestamp 和 scalar 元素类型可从 samples `INNER COLUMNS` 声明中推导得出 (参见指定外部列)。在 version 2 及更早版本的表中，该列名为 `time_series`
`metric_family`	`String`	指标族名称 (用于指标元数据)
`type`	`String`	指标类型 (例如 “counter”、“gauge”)
`unit`	`String`	指标单位
`help`	`String`	指标说明

示例：

INSERT INTO my_table (metric_name, tags, samples) 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, samples) 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, samples, metric_family, type, unit, help) VALUES
    ('http_requests_total', {'method': 'GET'}, [(now64(), 100.0)],
     'http_requests_total', 'counter', 'requests', 'Total HTTP requests')

指定外部列

可以在 CREATE TABLE 语句中显式列出外部 samples 列，以覆盖其默认的 Array(Tuple(DateTime64(3), Float64)) 类型 (其旧名称 time_series 同样可用) 。ClickHouse 会从该元组中提取时间戳类型和 scalar 类型，并将它们传递到内部samples表：

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

这相当于直接在 samples 的 INNER COLUMNS 子句中声明时间戳列和值列的类型：

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp UInt32 CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3)))

如果在同一条 CREATE TABLE 语句中同时使用这两种形式，则声明的类型必须一致。

目标端表

TimeSeries 表本身不存储数据，所有数据都保存在其目标端表中。这与 materialized view 的工作方式类似，区别在于 materialized view 只有一个目标端表，而 TimeSeries 表有三个必需的目标端表，分别名为 samples、标签和指标族，以及一个默认启用的可选最近样本目标端表 (请参阅 recent_samples_ttl_seconds 设置) 。这些目标端表既可以在 CREATE TABLE 查询中显式指定，也可以由 TimeSeries 表引擎自动生成内部目标端表。插入 TimeSeries 表的行会被转换、拆分为块，并写入这些目标端表。目标端表如下：

样本表

样本表包含与某个标识符关联的时间序列。样本表必须包含以下列：

名称	必填？	默认类型	可能的类型	描述
`id`	[x]	`Tuple(UInt64, LowCardinality(UUID))`	any	标识一组指标名称和标签的组合
`timestamp`	[x]	`DateTime64(3)`	`DateTime64(X)`	一个时间点
`value`	[x]	`Float64`	`Float32` 或 `Float64`	与 `timestamp` 关联的值

引擎自行创建的列会使用时间序列压缩编解码器： timestamp CODEC(Delta, T64, ZSTD(3)) 和 value CODEC(ALP, ZSTD(3))。近乎单调的时间戳使用通用编解码器时几乎无法压缩，因而可能会占据样本表磁盘存储空间的大部分。引擎会为其内部样本表和最近样本表启用 ALP，无需设置 enable_alp_codec。另请参阅调整列的类型。

标签表

tags 表包含针对每种指标名称与标签组合计算出的标识符。 tags 表必须包含以下列：

名称	必填？	默认类型	可能的类型	描述
`id`	[x]	`Tuple(UInt64, LowCardinality(UUID))`	any (必须与 samples 表中 `id` 的类型匹配)	`id` 用于标识一种指标名称与标签的组合。DEFAULT 表达式指定了如何计算该标识符
`metric_name`	[x]	`LowCardinality(String)`	`String` 或 `LowCardinality(String)`	指标名称
`<tag_value_column>`	[ ]	`String`	`String` 或 `LowCardinality(String)` 或 `LowCardinality(Nullable(String))`	特定标签的值；该标签的名称以及对应列的名称在 tags_to_columns 设置中指定
`tags`	[x]	`Map(LowCardinality(String), String)`	`Map(String, String)` 或 `Map(LowCardinality(String), String)` 或 `Map(LowCardinality(String), LowCardinality(String))`	所有标签的映射，包括表示指标名称的标签 `__name__`，以及 tags_to_columns 设置中枚举的标签名称。由旧版 ClickHouse 创建的表在此列中仅存储没有专用列且不含指标名称的标签；读取时会处理这两种情况
`min_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` 或 `Nullable(DateTime64(X))`	具有该 `id` 的时间序列的最小时间戳。如果 store_min_time_and_max_time 为 `true`，则会创建此列
`max_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` 或 `Nullable(DateTime64(X))`	具有该 `id` 的时间序列的最大时间戳。如果 store_min_time_and_max_time 为 `true`，则会创建此列

版本 5 及更高版本中，使用 MergeTree 家族引擎新建的内部 tags 表会在 tags 上建立倒排文本索引： INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs')。它通过同时查找键和值来加速 PromQL 中诸如 {job="api"} 这样的精确标记匹配。与空字符串的比较也会匹配缺失的标记，并且不会使用该索引。在 TAGS INNER COLUMNS 中显式声明的索引会替换默认索引。已有的表以及外部 tags 表会保留其原有索引；可在其 tags target table 上添加并 materialize 该索引以启用它。

指标族表

指标族 表包含有关正在采集的指标族、这些指标族的类型及其描述的信息。指标族是一组名称相同 (__name__ 标签) 且类型相同的指标，例如，直方图就是一个由多个指标组成的指标族。 指标族 表必须包含以下列：

名称	必需？	默认类型	可能的类型	描述
`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),
    `samples` Array(Tuple(DateTime64(3), Float64)),
    `metric_family` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
SETTINGS version = 5, recent_samples_ttl_seconds = 345600
SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, LowCardinality(UUID)),
    `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768
RECENT SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
RECENT SAMPLES INNER ENGINE = MergeTree PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5)) ORDER BY (id, timestamp) TTL toDateTime(timestamp) + toIntervalSecond(345600) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1
TAGS INNER COLUMNS
(
    `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(reinterpretAsUUID(sipHash128(tags)))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3))),
    INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000
)
TAGS INNER ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id) SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192
METRIC FAMILIES INNER COLUMNS
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
METRIC FAMILIES INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name

因此，列会自动生成。此外，还有四个内部目标表，各自的列定义存储在 INNER COLUMNS 子句中。 recent_samples_ttl_seconds 设置以其默认值写入 SETTINGS 子句：该设置定义最近样本表的 TTL，因此其有效值在创建时便已固定。此外，最新的 schema 版本已固定写入 version 设置中 (参见 Schema 版本控制) 。内部目标表的名称类似于 .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.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx，并且每个目标表都有各自的一组列：

CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, LowCardinality(UUID)),
    `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
ENGINE = MergeTree
ORDER BY (id, timestamp)
SETTINGS index_granularity = 32768

CREATE TABLE default.`.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
ENGINE = MergeTree
PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))
ORDER BY (id, timestamp)
TTL toDateTime(timestamp) + toIntervalSecond(345600)
SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1

CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(reinterpretAsUUID(sipHash128(tags)))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3))),
    INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000
)
ENGINE = AggregatingMergeTree
PRIMARY KEY metric_name
ORDER BY (metric_name, id)
SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192

CREATE TABLE default.`.inner_id.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
ENGINE = ReplacingMergeTree
ORDER BY metric_family_name
SETTINGS index_granularity = 8192

基于现有表创建表

语句 CREATE TABLE new_table AS existing_table 会创建一个配置与 existing_table 相同的 TimeSeries 表，其中 existing_table 必须是 TimeSeries 表。existing_table 的外部目标不会被复制：该语句必须自行声明这些目标。该语句会从 existing_table 复制：

SETTINGS 子句，但不包括 version：新表始终使用最新版本。语句中指定的设置会按名称与复制的设置合并，因此语句中指定的设置优先于复制的设置，而 name = DEFAULT 会将复制的设置重置为默认值；
每个内部表的 INNER COLUMNS 和 INNER ENGINE 子句。会保留自定义列 (例如额外列、带有 codec 或 DEFAULT 表达式的列) 和自定义引擎部分 (例如带参数的引擎、自定义排序键或引擎设置) ；其他列和引擎部分会根据新表的设置进行调整，因此例如语句中指定的 tags_to_columns、aggregate_min_time_and_max_time 或 tags_index_granularity 会生效。

除非语句自行声明，否则 id、时间戳和值列的类型，以及内部引擎的复制类型 (MergeTree、 ReplicatedMergeTree 或 SharedMergeTree) 也会从 existing_table 继承。外部列列表会重新生成，不会被复制。由较早版本的 ClickHouse 创建的表可以用作 existing_table：新表会采用当前的结构，例如当前的 id 类型和默认标识符表达式。

调整列类型

你可以使用 INNER COLUMNS 子句来调整内部目标表中各列的类型。例如，要将时间戳以微秒存储，并将值存储为 Float32，请使用：

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6) CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3)))

未指定内部列的编解码器时，将使用默认编解码器：

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

`id` 列

id 列包含标识符；每个标识符都是根据某个指标名称与标签的组合计算得出的。用于生成标识符的类型和 DEFAULT 表达式可通过 TAGS INNER COLUMNS 子句自定义：

CREATE TABLE my_table ENGINE=TimeSeries
TAGS INNER COLUMNS (id UInt64 DEFAULT sipHash64(tags))

id 列可以是任何可比较的非 Nullable 类型。samples 和标签内部表中声明的 id 类型必须保持一致。如果未为 id 列提供 DEFAULT 表达式且未设置 id_generator 设置，ClickHouse 会根据 id 类型自动选择 DEFAULT 表达式，但仅当 id 类型为 UUID、UInt64、UInt128、FixedString(16)、这些类型包裹在 LowCardinality 中的形式，或由其中两种类型组成的元组时才会这样做。对于此类元组，自动选择的表达式会在第一个组件中计算指标名称的哈希值，并在第二个组件中计算所有标签的哈希值。使用 LowCardinality 标识符类型 (例如 Tuple(UInt64, LowCardinality(UUID))) 可使标识符保持字典编码：samples 表会按块存储小型字典并配合 dictionary indexes，而不是在每一行中重复完整的标识符，从而减少查询读取的数据量。 id_generator 设置也支持相同的自定义，而无需使用 INNER COLUMNS 子句：

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_generator = 'sipHash64(tags)'

如果设置了此项，即使该列的 DEFAULT 包含其他表达式，也会用它来生成 id。 id 列的类型也可以通过 id_type 设置指定，而无需使用 INNER COLUMNS 子句：

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_type = 'UInt64', id_generator = 'sipHash64(tags)'

设置了 id_generator 时，id_type 设置会在 CREATE 时自动记录，因此该定义会保留此表达式所针对的类型。

`tags` 列

tags 列包含时间序列的所有标签，其中包括带有指标名称的 __name__ 标签。 tags_to_columns 设置允许指定将某个特定标签也存储在单独的列中，作为 tags 列中 Map 的补充：

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

该语句将把 instance 和 job 列添加到内部标签目标表中。标签 instance 和 job 的值将同时存储在这些列和 tags 列中。

在由旧版 ClickHouse 创建的表中，tags 列仅包含未存储在专用列中且不含指标名称的标签，而 all_tags 列是一个临时列，会在插入时填充除指标名称外的所有标签。

内部目标端表的表引擎

默认情况下，内部目标端表使用以下表引擎：

samples 表使用 MergeTree；
最近样本表使用 MergeTree，按 5 小时分桶进行分区 (请参见 recent_samples_partition_by 设置)，其 TTL 源自 recent_samples_ttl_seconds 设置，并启用 ttl_only_drop_parts，因此会整体删除过期的 parts；
标签表使用 AggregatingMergeTree，因为相同的数据通常会多次插入该表，因此需要一种去重方式，同时还需要对列 min_time 和 max_time 进行聚合；
指标族表使用 ReplacingMergeTree，因为相同的数据通常会多次插入该表，因此需要一种去重方式。

生成的内部表的引擎家族遵循 default_table_engine 查询级别设置：当 default_table_engine = ReplicatedMergeTree 或 SharedMergeTree 时，内部表使用相应的 Replicated 或 Shared 引擎。当 default_table_engine = None (或任何其他值) 时，内部表的引擎必须显式指定。所有内部表必须具有相同的复制类型：如果其中一个表采用复制 (或共享) 机制，其他内部表也必须采用复制 (或共享) 机制，否则其内容会在副本之间出现差异。例如，声明 SAMPLES INNER ENGINE = ReplicatedMergeTree(...) 要求其他内部引擎也使用复制引擎 - 要么显式声明，要么通过 default_table_engine = ReplicatedMergeTree 生成。如果指定了其他表引擎，内部目标端表也可以使用它们：

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES ENGINE=ReplicatedMergeTree
RECENT SAMPLES ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRIC FAMILIES ENGINE=ReplicatedReplacingMergeTree

标签表将标签列 (以及 tags Map) 放在其排序键之外，而 AggregatingMergeTree 默认会拒绝这种做法 (请参见 allow_dimensions_outside_sorting_key) 。这在这里是安全的，因为这些列在函数上依赖于 id，而 id 是排序键的一部分，因此后台合并折叠到一起的所有行都具有相同的值。当内部标签表被生成，或者其引擎像上面那样以内联方式指定时， TimeSeries 会自动为其设置 allow_dimensions_outside_sorting_key = 1；对于手动创建的外部聚合标签表，则必须自行设置。

外部目标端表

可以让 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 metric_families_for_my_table ...

CREATE TABLE my_table ENGINE=TimeSeries SAMPLES samples_for_my_table TAGS tags_for_my_table METRIC FAMILIES metric_families_for_my_table;

外部表也可用作最近样本目标 (RECENT SAMPLES my_recent_samples_table 子句) 。此类表必须与外部样本表具有相同的列，并且必须至少保留 recent_samples_ttl_seconds 秒的数据，这由用户负责。外部表的列类型 (id、timestamp、value，以及 tags_to_columns 中列出的各个 <tag_value_column>) 必须与 TimeSeries 表原本会在内部生成的类型一致 (类型约束请参见 Samples 表、标签表和指标族表) 。类型不匹配会在 CREATE 时报告。外部标签表的 id 列类型以及生成标识符的表达式会在 CREATE 时记录到 id_type 和 id_generator 设置中 (从 version 2 开始) ，因此 TimeSeries 表的定义会保留它们：例如，CREATE TABLE ... AS my_table 会从 my_table 的定义中读取 id 类型，而无需读取其外部目标端表。如果未指定 id_generator 设置，则会将其设置为外部表 id 列上声明的 DEFAULT (如果有) ，否则设置为根据 id 类型派生出的规范生成器。即使外部表的 DEFAULT 之后发生变化，也仍会使用已记录的表达式来生成 id——详见 id 列。

修改设置

执行 CREATE 后，可更改以下两个设置：

id_generator
filter_by_min_time_and_max_time

ALTER TABLE my_table MODIFY SETTING id_generator = 'sipHash64(tags)';
ALTER TABLE my_table MODIFY SETTING filter_by_min_time_and_max_time = 0;
ALTER TABLE my_table RESET SETTING filter_by_min_time_and_max_time;

请注意，如果在标签表中已有数据后更改 id_generator，同一指标+标签组合可能会生成不同的 ID——旧行会保留原来的 ID，新行则会使用新的生成器。其他设置不能通过 ALTER ... MODIFY SETTING 更改：其中大多数在 CREATE 时就已经固化在内部表的 schema 中，而 version 设置会在 CREATE 时自动固定，并用于标识 schema 本身 (参见 Schema 版本控制) 。

设置

以下列出了在定义 TimeSeries 表时可指定的设置：

名称	类型	默认值	说明
`id_type`	数据类型	取决于 `id` 列	目标端表中 `id` 列的类型。通常该类型在内部表的 `INNER COLUMNS` 子句中声明，或在外部标签表中声明；如果类型未以其他方式保留在定义中，则该设置会在 `CREATE` 时自动记录：即当标签目标为外部表时，或设置了 `id_generator` 设置时。该设置也可以显式指定，以替代 `TAGS INNER COLUMNS (id <type>)`。要求 `version` 至少为 2
`id_generator`	表达式	取决于 `id` 类型	根据时间序列的标签计算其标识符 (指纹) 的表达式。如果未设置，则使用 `id` 列的默认表达式。如果 `id` 列的默认表达式也未设置，则会自动选择该表达式。对于外部标签表，如果 `version` 至少为 2，则该设置会在 `CREATE` 时自动记录 (请参阅外部目标端表)
`tags_to_columns`	Map		指定哪些标签应映射到标签表中的独立列。语法：`{'tag1': 'column1', 'tag2' : column2, ...}`
`use_all_tags_column_to_generate_id`	Bool	false	已废弃设置，不执行任何操作
`store_min_time_and_max_time`	Bool	true	如果设置为 true，则该表会为每个时间序列存储 `min_time` 和 `max_time`
`aggregate_min_time_and_max_time`	Bool	true	创建内部目标 `tags` 表时，此标志会启用将 `min_time` 列的类型设为 `SimpleAggregateFunction(min, Nullable(DateTime64(3)))`，而不是仅使用 `Nullable(DateTime64(3))`；`max_time` 列同样如此
`filter_by_min_time_and_max_time`	Bool	true	如果设置为 true，则该表会使用 `min_time` 和 `max_time` 列来过滤时间序列
`samples_index_granularity`	UInt64	32768	设置内部 samples 表的 `index_granularity`。显式设置时，会覆盖引擎声明中的 `index_granularity`。对于外部 samples 表和非 MergeTree 引擎，此设置会被忽略
`recent_samples_ttl_seconds`	UInt64	345600	附加 `最近样本` 目标表的保留期，每个插入的样本也会写入该表。内部最近样本表始终会根据此设置获得 `TTL toDateTime(timestamp) + toIntervalSecond(recent_samples_ttl_seconds)` (覆盖引擎声明中的任何生存时间 (TTL)) ；外部最近样本表必须至少保留这么多秒的数据。时间范围落在生存时间 (TTL) 窗口内的查询会优先使用最近样本表，而非主 samples 表 (请参阅查询级别设置 `time_series_prefer_recent_samples_table`) 。默认值为 4 天；有效值会在 CREATE 时固定写入表定义。设置为 0 可禁用最近样本表
`recent_samples_partition_by`	表达式	`toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))`	内部 `最近样本` 表的分区键，例如 `toStartOfHour(timestamp)`。显式设置时，会覆盖引擎声明中的分区键；如果两者均未设置，则每 5 小时使用一个分区。对于外部最近样本表，此设置会被忽略。要求 `recent_samples_ttl_seconds` 非零
`recent_samples_index_granularity`	UInt64	8192	设置内部 `最近样本` 表的 `index_granularity`。显式设置时，会覆盖引擎声明中的 `index_granularity`。对于外部最近样本表和非 MergeTree 引擎，此设置会被忽略。要求 `recent_samples_ttl_seconds` 非零
`tags_index_granularity`	UInt64	8192	设置内部标签表的 `index_granularity`。显式设置时，会覆盖引擎声明中的 `index_granularity`。对于外部标签表和非 MergeTree 引擎，此设置会被忽略
`version`	UInt64	5	表的版本：它标识目标端表的集合及其结构。版本会在创建表时自动固定，之后无法更改，通常应在 `CREATE TABLE` 查询中省略 (请参阅 Schema 版本控制)

Schema 版本控制

TimeSeries 表引擎与 PromQL 执行层仍处于活跃开发阶段：目标端表的集合及其结构可能在不同 ClickHouse 版本之间发生变化。为了让此类变化可被检测，每个 TimeSeries 表都会将自身版本记录在 version 设置中。建表时，该版本会自动固化到 CREATE 查询中——其取值为服务器已知的最新版本 (当前为 5) —— 并持久化在表的元数据中，且无法通过 ALTER 修改。在该设置引入之前创建的表被视为版本 0。通常在 CREATE TABLE 查询中省略该设置即可——此时表会自动采用最新版本。如果服务器支持所指定的版本，也可以显式指定 version；此时该表会按照该版本的方式来定义 (请参阅版本历史) 。 CREATE TABLE ... AS other_table 不会复制另一个表的版本，请参阅基于现有表创建表。服务器支持一个版本范围，且不同场景所要求的最低版本可能不同：使用 SELECT 读取、使用 INSERT 或 Prometheus 远程写入协议写入、以及执行 PromQL (prometheusQuery、 prometheusQueryRange 和 timeSeriesSelector 表函数、 promql dialect 以及 Prometheus HTTP 查询 API) ，三者的最低版本要求各不相同：

如果 TimeSeries 表的版本对 PromQL 而言过旧，则针对该表的 PromQL 查询会被拒绝。异常信息会建议重建该表：创建一个新的 TimeSeries 表，通过 INSERT ... SELECT 查询复制数据，再用新表替换旧表。
如果版本过旧而无法写入，则 INSERT 查询和 Prometheus 远程写入协议会被拒绝，但 SELECT 查询仍可正常工作。
如果版本对服务器而言完全过旧，则针对该表的所有查询 (SHOW CREATE TABLE、DETACH 和 DROP 除外) 都会被拒绝。

版本历史

版本	变更
0	在引入 `version` 设置之前创建的表，包括 “prealpha” 表 (这类表将目标端表的列声明为外部列) 以及没有最近样本表的表
1	引入了 `version` 设置
2	引入了 `id_type` 设置：使用外部标签表的表会在 `id_type` 中记录 `id` 列的类型，并在 `id_generator` 中记录生成标识符的表达式，因此其定义不再依赖于外部表。设置了 `id_generator` 时同样会记录 `id_type` (参见 `id` 列)
3	外部列 `time_series` 更名为 `samples` (参见外部列) 。早期版本的表仍沿用该列的旧名称，prometheusQuery 与 prometheusQueryRange 表函数也会按表所使用的名称返回该列。存储的数据没有变化
4	`metrics` 目标端表更名为 `metric families`：内部表命名为 `.inner_id.metricfamilies.<uuid>`，而非 `.inner_id.metrics.<uuid>`，并且定义使用关键字 `METRIC FAMILIES` 而非 `METRICS` 编写。存储的数据没有变化
5	使用 `MergeTree` 家族引擎的新建内部标签表，默认会在 `tags` map 上创建 `keyValuePairs` 文本索引 (参见 Tags table)

函数

以下列出了支持将 TimeSeries 表作为参数的函数：

SQL 参考文档

数据类型

引擎

函数

格式

设置

系统表

数据湖

TimeSeries 表引擎

语法

用法

外部列

指定外部列

目标端表

样本表

最近样本表

标签表

指标族表

创建

基于现有表创建表

调整列类型

`id` 列

`tags` 列

内部目标端表的表引擎

外部目标端表

修改设置

设置

Schema 版本控制

版本历史

函数

​语法

​用法

​外部列

​指定外部列

​目标端表

​样本表

​最近样本表

​标签表

​指标族表

​创建

​基于现有表创建表

​调整列类型

​id 列

​tags 列

​内部目标端表的表引擎

​外部目标端表

​修改设置

​设置

​Schema 版本控制

​版本历史

​函数

语法

用法

外部列

指定外部列

目标端表

样本表

最近样本表

标签表

指标族表

创建

基于现有表创建表

调整列类型

`id` 列

`tags` 列

内部目标端表的表引擎

外部目标端表

修改设置

设置

Schema 版本控制

版本历史

函数