> ## 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 <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

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

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

<Info>
  这是一个 Experimental 功能，未来的发行版中可能会发生不向后兼容的变更。
  使用 [allow\_experimental\_time\_series\_table](/zh/reference/settings/session-settings#allow_experimental_time_series_table) 设置
  启用 TimeSeries 表引擎。
  输入命令 `set allow_experimental_time_series_table = 1`。
</Info>

<div id="syntax">
  ## 语法
</div>

```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)]
```

<div id="usage">
  ## 用法
</div>

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

```sql theme={null}
CREATE TABLE my_table ENGINE=TimeSeries
```

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

* [Prometheus remote-write](/zh/concepts/features/interfaces/prometheus#remote-write)
* [Prometheus remote-read](/zh/concepts/features/interfaces/prometheus#remote-read)

<div id="target-tables">
  ## 目标表
</div>

`TimeSeries` 表本身不存储数据，所有数据都保存在其目标表中。
这与 [materialized view](/zh/reference/statements/create/view#materialized-view) 的工作方式类似，
区别在于 materialized view 只有一个目标表，
而 `TimeSeries` 表有三个目标表，分别名为 [data](#data-table)、[标签](#tags-table) 和 [metrics](#metrics-table)。

这些目标表既可以在 `CREATE TABLE` 查询中显式指定，
也可以由 `TimeSeries` 表引擎自动生成内部目标表。

目标表如下：

<div id="data-table">
  ### Data 表
</div>

*data* 表包含与某个标识符关联的时间序列。

*data* 表必须包含以下列：

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

<div id="tags-table">
  ### 标签表
</div>

*tags* 表包含针对每种指标名称与标签组合计算出的标识符。

*tags* 表必须包含以下列：

| 名称                   | 必填？  | 默认类型                                  | 可能的类型                                                                                                                 | 描述                                                                                    |
| -------------------- | ---- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `id`                 | \[x] | `UUID`                                | any (必须与 [data](#data-table) 表中 `id` 的类型匹配)                                                                           | `id` 用于标识一种指标名称与标签的组合。DEFAULT 表达式指定了如何计算该标识符                                          |
| `metric_name`        | \[x] | `LowCardinality(String)`              | `String` 或 `LowCardinality(String)`                                                                                   | 指标名称                                                                                  |
| `<tag_value_column>` | \[ ] | `String`                              | `String` 或 `LowCardinality(String)` 或 `LowCardinality(Nullable(String))`                                              | 特定标签的值；该标签的名称以及对应列的名称在 [tags\_to\_columns](#settings) 设置中指定                           |
| `tags`               | \[x] | `Map(LowCardinality(String), String)` | `Map(String, String)` 或 `Map(LowCardinality(String), String)` 或 `Map(LowCardinality(String), LowCardinality(String))` | 标签映射，不包括表示指标名称的标签 `__name__`，也不包括 [tags\_to\_columns](#settings) 设置中枚举的标签名称           |
| `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](#settings) 为 `true`，则会创建此列 |
| `max_time`           | \[ ] | `Nullable(DateTime64(3))`             | `DateTime64(X)` 或 `Nullable(DateTime64(X))`                                                                           | 具有该 `id` 的时间序列的最大时间戳。如果 [store\_min\_time\_and\_max\_time](#settings) 为 `true`，则会创建此列 |

<div id="metrics-table">
  ### 指标表
</div>

*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](#data-table)、[tags](#tags-table)、[metrics](#metrics-table) 表中的所有这些列。

<div id="creation">
  ## 创建
</div>

可以通过多种方式使用 `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](/zh/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
```

<div id="adjusting-column-types">
  ## 调整列类型
</div>

你几乎可以在定义主表时，通过显式指定内部目标表中几乎任意列的类型来调整其类型。例如，

```sql theme={null}
CREATE TABLE my_table
(
    timestamp DateTime64(6)
) ENGINE=TimeSeries
```

这会使内部的 [data](#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)
```

<div id="id-column">
  ## `id` 列
</div>

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

```sql theme={null}
CREATE TABLE my_table
(
  id UInt64 DEFAULT sipHash64(metric_name, all_tags)
)
ENGINE=TimeSeries
```

<div id="tags-and-all-tags">
  ## `tags` 和 `all_tags` 列
</div>

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

```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-table)目标表的定义中。在这种情况下，`tags` 列将不包含 `instance` 和 `job` 这两个标签，
但 `all_tags` 列会包含它们。`all_tags` 列是临时列，其唯一用途是用于 `id` 列的 DEFAULT 表达式
中。

可以通过显式指定列类型来进行调整：

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

<div id="inner-table-engines">
  ## 内部目标表的表引擎
</div>

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

* [data](#data-table) 表使用 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree)；
* [tags](#tags-table) 表使用 [AggregatingMergeTree](/zh/reference/engines/table-engines/mergetree-family/aggregatingmergetree)，因为相同的数据通常会多次插入该表，因此需要一种去重方式，
  同时还需要对列 `min_time` 和 `max_time` 进行聚合；
* [metrics](#metrics-table) 表使用 [ReplacingMergeTree](/zh/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
```

<div id="external-target-tables">
  ## 外部目标表
</div>

也可以让 `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;
```

<div id="settings">
  ## 设置
</div>

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

| 名称                                   | 类型   | 默认值  | 说明                                                                                                                                                   |
| ------------------------------------ | ---- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tags_to_columns`                    | Map  | {}   | 指定哪些标签应映射到 [标签](#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` 表时，此标志会启用将 `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` 表作为参数的函数：

* [timeSeriesData](/zh/reference/functions/table-functions/timeSeriesData)
* [timeSeriesTags](/zh/reference/functions/table-functions/timeSeriesTags)
* [timeSeriesMetrics](/zh/reference/functions/table-functions/timeSeriesMetrics)