这是一个私有预览功能,未来的发行版中可能会发生不向后兼容的变更。
使用
enable_time_series_table 设置
启用 TimeSeries 表引擎。
输入命令 set enable_time_series_table = 1。TimeSeries 表引擎在 ClickHouse Cloud 中作为私有预览功能提供。
已参与私有预览的服务已配置
enable_time_series_table 设置。其他 ClickHouse Cloud 服务
没有此配置,且您无法自行在此类服务上启用该引擎。语法
关键字
SAMPLES 有一个别名 DATA,关键字 METRIC FAMILIES 有一个别名 METRICS,保留它们都是为了保持向后兼容性。
版本低于 4 的表定义使用 METRICS 写入,以便较旧的 server 能够读取它。版本 9 及更早版本的表可以使用手动创建的表 (而非内部表) 作为目标端表,
例如
TAGS db.tags_table_name。此类表仍可正常使用,但以最新版本新建的表只能使用内部目标端表。用法
一开始先使用默认设置会更简单 (可以在不指定列列表的情况下创建TimeSeries 表) :
外部列
TimeSeries 表的列会自动生成。这些列属于外部列,不存储任何数据,只为 SELECT/INSERT 提供接口。实际数据存储在目标端表中。以下是外部列列表:
示例:
metric_name 可以为空,这表示指标名称是在 tags 的 __name__ 中指定的,例如:
metric_family、type、unit 和 help 列:
指定外部列
可以在CREATE TABLE 语句中显式列出外部 samples 列,以覆盖其默认的 Array(Tuple(DateTime64(3), Float64)) 类型 (其旧名称 time_series 同样可用) 。ClickHouse 会从该元组中提取时间戳类型和值类型,并将它们传递到内部samples表:
INNER COLUMNS 子句中声明时间戳列和值列的类型:
CREATE TABLE 语句中同时使用这两种形式,则声明的类型必须一致。
目标端表
TimeSeries 表本身不存储数据,所有数据都保存在其目标端表中。
这与 materialized view 的工作方式类似,
区别在于 materialized view 只有一个目标端表,
而 TimeSeries 表有三个必需的目标端表,分别名为 samples、标签 和 指标族,
以及两个默认启用的可选目标端表:最近样本
(请参阅 recent_samples_ttl_seconds 设置) 和 时间范围 (请参阅 store_time_ranges 设置) 。
这些目标端表既可以在 CREATE TABLE 查询中显式指定,
也可以由 TimeSeries 表引擎自动生成内部目标端表。
插入 TimeSeries 表的行会被转换、拆分为块,并写入这些目标端表。
目标端表如下:
样本表
样本 表包含与某个标识符关联的时间序列。 样本 表必须包含以下列:
引擎自行创建的列会使用时间序列压缩编解码器:
timestamp CODEC(Delta, T64, ZSTD(3)) 和 value CODEC(ALP, ZSTD(3))。近乎单调的时间戳使用通用编解码器时几乎无法
压缩,因而可能会占据样本表磁盘存储空间的大部分。
引擎会为其内部样本表和最近样本表启用 ALP,无需设置 enable_alp_codec。
另请参阅调整列的类型。
最近样本表
_最近样本_表是可选的,默认启用 (请参阅 recent_samples_ttl_seconds 设置;将其设为零可禁用该表) 。该表包含 TTL 未超过该设置所定义时长的样本副本,并且必须与样本表具有相同的列。 生成的timestamp 列使用 CODEC(Delta, T64, ZSTD(3)),
生成的 value 列使用 CODEC(ALP, ZSTD(3))。
每个插入的样本都会同时写入样本表和最近样本表。
时间范围落在 TTL 窗口内的查询会从最近样本表而非主样本表读取数据,
因为前者小得多 (可通过查询级别设置 time_series_prefer_recent_samples_table 禁用此行为) 。
内部最近样本表的 TTL 始终由 recent_samples_ttl_seconds 设置决定。
标签表
标签 表包含针对每种指标名称与标签组合计算出的标识符。 标签 表必须包含以下列:
版本 5 及更高版本中新建的、使用
MergeTree 系列引擎的内部标签表会在 tags 上创建倒排文本索引:
INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs')。该索引通过同时查找键和值,加速 PromQL 中诸如
{job="api"} 之类的精确标记匹配。与空字符串的比较还会
匹配缺失的标记,且不会使用此索引。
在 TAGS INNER COLUMNS 中显式声明的索引会替换默认索引。现有表会保留其原有索引;
如需启用该索引,请在其标签表上添加并物化该索引。
时间范围表
时间范围 表是可选的,默认启用 (参见 store_time_ranges 设置;将其设为false 即可禁用该表) 。
该表存储每个时间序列的时间范围 (最小时间戳和最大时间戳) ,用于按时间筛选时间序列:
针对某个时间范围的查询只会读取在该范围内有样本的时间序列。
时间范围 表必须包含以下列:
每次插入时,都会将各时间序列中已插入样本的时间范围写入此表;内部 时间范围 表
使用 AggregatingMergeTree 引擎,将这些范围合并为每个时间序列仅保留一条。
指标族表
指标族 表包含有关正在采集的指标族、这些指标族的类型及其描述的信息。 指标族是一组名称相同 (__name__ 标签) 且类型相同的指标,例如,直方图就是一个由多个指标组成的指标族。
指标族 表必须包含以下列:
创建
可以通过多种方式创建使用TimeSeries 表引擎的表。
最简单的语句是
SHOW CREATE TABLE my_table 查看) :
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.timeranges.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、.inner_id.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
并且每个目标端表都有各自的一组列:
基于现有表创建表
语句CREATE TABLE new_table AS existing_table 会创建一个配置与 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 继承。
外部列列表会重新生成,不会被复制。
由较早版本的 ClickHouse 创建的表可以用作 existing_table:新表会采用当前的
结构,例如当前的 id 类型和默认标识符表达式,而从
existing_table 复制的自定义部分也会随之调整。
调整列类型
你可以使用INNER COLUMNS 子句来调整内部目标表中各列的类型。例如,要将时间戳以微秒存储,并将值存储为 Float32,请使用:
id 列
id 列包含标识符;每个标识符都是根据某个指标名称与标签的组合计算得出的。
用于生成标识符的类型和 DEFAULT 表达式可通过 TAGS INNER COLUMNS 子句自定义:
id 列可以是任何可比较的非 Nullable 类型。samples 和 标签 内部表中声明的 id 类型必须保持一致。
如果未为 id 列提供 DEFAULT 表达式,ClickHouse 会根据 id 类型自动选择 DEFAULT 表达式,但仅当 id 类型为 UUID、UInt64、UInt128、FixedString(16)、这些类型包裹在 LowCardinality 中的形式,或由其中两种类型组成的元组时才会这样做。对于此类元组,自动选择的表达式会在第一个组件中计算指标名称的哈希值,并在第二个组件中计算所有标签的哈希值。
使用 LowCardinality 标识符类型 (例如 Tuple(UInt64, LowCardinality(UUID))) 可使标识符保持字典编码:samples 表会按块存储小型字典并配合 dictionary indexes,而不是在每一行中重复完整的标识符,从而减少查询读取的数据量。
版本 9 或更早版本的表也可以改为在 id_type 和 id_generator 设置中声明类型和表达式
(参见早期版本的设置) 。对此类表执行 CREATE TABLE ... AS 时不会复制这些设置:
副本会继承 id 类型,并获得为该类型自动选择的 DEFAULT 表达式。
tags 列
tags 列包含时间序列的所有标签,其中包括带有指标名称的 __name__ 标签。
tags_to_columns 设置允许指定将某个特定标签也存储在单独的列中,
作为 tags 列中 Map 的补充:
instance 和 job 列添加到内部标签目标表中。
标签 instance 和 job 的值将同时存储在这些列和 tags 列中。
在由旧版 ClickHouse 创建的表中,
tags 列仅包含未存储在专用
列中且不含指标名称的标签,而 all_tags 列是一个临时列,会在插入时填充
除指标名称外的所有标签。内部目标端表的表引擎
默认情况下,内部目标端表使用以下表引擎:- 样本 表使用 MergeTree;
- 最近样本 表使用 MergeTree,按 5 小时分桶进行分区 (请参见 recent_samples_partition_by 设置),其
TTL源自 recent_samples_ttl_seconds 设置,并启用ttl_only_drop_parts,因此会整体删除过期的 parts; - 标签 表使用 ReplacingMergeTree,因为相同的数据通常会多次插入该表,因此需要一种去重方式
(版本 7 或更早版本的表改用 AggregatingMergeTree,因为它们需要在该表中对列
min_time和max_time进行聚合)。 大多数重复数据甚至不会进入该表:TimeSeries表的去重缓存会跳过最近写入的时间序列 (请参见tags_deduplication_cache_expiration_seconds设置;版本 7 或更早版本的表仅在不存储min_time和max_time时才使用该缓存,请参见store_min_time_and_max_time设置); - 时间范围 表使用 AggregatingMergeTree,因为每次插入都会写入所插入样本的时间范围, 而同一时间序列的多个范围必须合并为一个;
- 指标族 表使用 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 Map) 放在其排序键之外,
而 AggregatingMergeTree 默认会拒绝这种做法 (请参见 allow_dimensions_outside_sorting_key) 。
这在这里是安全的,因为这些列在函数上依赖于 id,而 id 是排序键的一部分,因此后台合并折叠到一起的所有
行都具有相同的值。当内部 标签 表的聚合引擎是自动生成的 (适用于第 7 版或更早版本的表) 或以内联方式指定时,
TimeSeries 会自动为其设置 allow_dimensions_outside_sorting_key = 1。
数据保留
默认情况下,样本表未设置TTL,因此样本会永久保留。
如需删除旧样本,请在内部样本表的引擎中声明 TTL:
ttl_only_drop_parts 后,当一个 part 中的所有样本均已过期时,该 part 会被整体删除,而不会被重写。
按 UTC 日期分区可使不同日期的样本存放在不同的 parts 中,这样每一天的数据都会在其最新样本过期后被一次性删除。
recent_samples_partition_by 设置沿用了最近样本表默认的 5 小时分区,但同样按 UTC 计算这些分区。
如果分区键依赖于服务器时区,那么在该时区变更后,查询可能会跳过包含匹配样本的 parts。
最近样本表有自己独立的 TTL,由 recent_samples_ttl_seconds 设置指定。
请确保样本表的 TTL 长于该值,否则对于时间范围落在最近样本窗口内的查询,
可能会返回已从样本表中删除的样本。
默认情况下,标签表没有 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,同一指标+标签组合可能会生成不同的 ID:旧行保留原有 ID,新行则使用新的生成器。
进行此类更改后,Prometheus HTTP API 端点 /api/v1/series、/api/v1/labels 和 /api/v1/label/<name>/values
可能会返回由先前生成器写入的时间序列,即使这些时间序列在所请求的时间范围内没有任何 samples。ALTER ... MODIFY SETTING 更改:其中大多数设置在 CREATE 时就已固化到内部表的 schema 中,
而 version 设置会在 CREATE 时自动固定,用于标识 schema 本身 (参见 Schema 版本控制) 。
设置
以下列出了在定义TimeSeries 表时可指定的设置:
早期版本的设置
以下设置仅适用于早期版本的表,因此最新版本的表不会包含这些设置:Schema 版本控制
TimeSeries 表引擎与 PromQL 执行层仍处于活跃开发阶段:
目标端表的集合及其结构可能在不同 ClickHouse 版本之间发生变化。
为了让此类变化可被检测,每个 TimeSeries 表都会将自身版本记录在 version 设置中。
建表时,该版本会自动固化到 CREATE 查询中——其取值为服务器已知的最新版本 (当前为 9) ——
并持久化在表的元数据中,且无法通过 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除外) 都会被拒绝。
版本历史
函数
以下列出了支持将TimeSeries 表作为参数的函数: