函数 - ClickHouse Documentation

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

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

这是一个 Experimental 功能，未来的发行版中可能会发生不向后兼容的变更。使用 allow_experimental_time_series_table 设置启用 TimeSeries 表引擎。输入命令 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 表有三个目标表，分别名为 data、标签和 metrics。这些目标表既可以在 CREATE TABLE 查询中显式指定，也可以由 TimeSeries 表引擎自动生成内部目标表。目标表如下：

Data 表

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

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

标签表

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

名称	必填？	默认类型	可能的类型	描述
`id`	[x]	`UUID`	any (必须与 data 表中 `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 设置中枚举的标签名称
`all_tags`	[ ]	`Map(String, String)`	`Map(String, String)` 或 `Map(LowCardinality(String), String)` 或 `Map(LowCardinality(String), LowCardinality(String))`	临时列，每一行都是一个包含所有标签的映射，仅排除表示指标名称的标签 `__name__`。该列的唯一用途是在计算 `id` 时使用
`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`，则会创建此列

指标表

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、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

这会使内部的 data 表以微秒而非毫秒存储时间戳：

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 列包含标识符，每个标识符都是根据某个指标名称与标签组合计算得出的。 id 列的 DEFAULT 表达式用于计算这类标识符。 id 列的类型和该表达式都可以通过显式指定进行调整：

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

`tags` 和 `all_tags` 列

有两列包含标签的 Map：tags 和 all_tags。在这个示例中，它们的含义相同；但如果使用 tags_to_columns 设置，它们也可能不同。此设置允许指定将某个特定标签存储在单独的列中，而不是存储在 tags 列中的 Map 内：

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

该语句将添加以下列：

`instance` String,
`job` String

加入到 my_table 及其内部标签目标表的定义中。在这种情况下，tags 列将不包含 instance 和 job 这两个标签，但 all_tags 列会包含它们。all_tags 列是临时列，其唯一用途是用于 id 列的 DEFAULT 表达式中。可以通过显式指定列类型来进行调整：

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

内部目标表的表引擎

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

data 表使用 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	指定哪些标签应映射到标签表中的独立列。语法：`{'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` 表时，此标志会启用将 `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` 列来过滤时间序列

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

​语法

​用法

​目标表

​Data 表

​标签表

​指标表

​创建

​调整列类型

​id 列

​tags 和 all_tags 列

​内部目标表的表引擎

​外部目标表

​设置

语法

用法

目标表

Data 表

标签表

指标表

创建

调整列类型

`id` 列

`tags` 和 `all_tags` 列

内部目标表的表引擎

外部目标表

设置