> ## 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.

> 时间序列相关函数文档

# 时间序列相关函数

以下函数设计用于与 `timeSeries*()` aggregate functions 一起使用，例如
[`timeSeriesInstantRateToGrid`](/zh/reference/functions/aggregate-functions/timeSeriesInstantRateToGrid)、
[`timeSeriesLastToGrid`](/zh/reference/functions/aggregate-functions/timeSeriesResampleToGridWithStaleness)
等。

{/*AUTOGENERATED_START*/}

<div id="seriesDecomposeSTL">
  ## seriesDecomposeSTL
</div>

引入版本：v24.1.0

使用 STL ([基于 Loess 的季节-趋势分解过程](https://www.wessa.net/download/stl.pdf)) 将时间序列数据分解为季节性、趋势和残差分量。

**语法**

```sql theme={null}
seriesDecomposeSTL(series, period)
```

**参数**

* `series` — 数值数组 [`Array((U)Int8/16/32/64)`](/zh/reference/data-types/array) 或 [`Array(Float*)`](/zh/reference/data-types/array)
* `period` — 正整数 [`UInt8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回一个包含四个数组的数组：第一个数组包含季节性成分，第二个数组包含趋势成分，第三个数组包含残差成分，第四个数组包含基线 (季节性 + 趋势) 成分。[`Array(Array(Float32), Array(Float32), Array(Float32), Array(Float32))`](/zh/reference/data-types/array)

**示例**

**使用 STL 分解时间序列数据**

```sql title=Query theme={null}
SELECT seriesDecomposeSTL([10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34], 3) AS print_0
```

```response title=Response theme={null}
┌───────────print_0──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [[
        -13.529999, -3.1799996, 16.71,      -13.53,     -3.1799996, 16.71,      -13.53,     -3.1799996,
        16.71,      -13.530001, -3.18,      16.710001,  -13.530001, -3.1800003, 16.710001,  -13.530001,
        -3.1800003, 16.710001,  -13.530001, -3.1799994, 16.71,      -13.529999, -3.1799994, 16.709997
    ],
    [
        23.63,     23.63,     23.630003, 23.630001, 23.630001, 23.630001, 23.630001, 23.630001,
        23.630001, 23.630001, 23.630001, 23.63,     23.630001, 23.630001, 23.63,     23.630001,
        23.630001, 23.63,     23.630001, 23.630001, 23.630001, 23.630001, 23.630001, 23.630003
    ],
    [
        0, 0.0000019073486, -0.0000019073486, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.0000019073486, 0,
        0
    ],
    [
        10.1, 20.449999, 40.340004, 10.100001, 20.45, 40.34, 10.100001, 20.45, 40.34, 10.1, 20.45, 40.34,
        10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.100002, 20.45, 40.34
    ]]                                                                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="seriesOutliersDetectTukey">
  ## seriesOutliersDetectTukey
</div>

引入版本：v24.2.0

使用 [Tukey Fences](https://en.wikipedia.org/wiki/Outlier#Tukey%27s_fences) 检测时间序列数据中的离群值。

**语法**

```sql theme={null}
seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])
```

**参数**

* `series` — 由数值组成的数组。[`Array((UInt8/16/32/64))`](/zh/reference/data-types/array) 或 [`Array(Float*)`](/zh/reference/data-types/array)
* `min_percentile` — 可选。用于计算四分位距 [(IQR)](https://en.wikipedia.org/wiki/Interquartile_range) 的最小百分位数。该值必须在 \[0.02,0.98] 范围内。默认值为 0.25。[`Float*`](/zh/reference/data-types/float)
* `max_percentile` — 可选。用于计算四分位距 (IQR) 的最大百分位数。该值必须在 \[0.02,0.98] 范围内。默认值为 0.75。[`Float*`](/zh/reference/data-types/float)
* `K` — 可选。用于检测轻度或更明显离群值的非负常数。默认值为 1.5。[`Float*`](/zh/reference/data-types/float)

**返回值**

返回一个与输入数组长度相同的数组，其中每个值表示 `series` 中对应元素的异常可能性评分。非零评分表示该元素可能存在异常。[`Array(Float32)`](/zh/reference/data-types/array)

**示例**

**基础离群值检测**

```sql title=Query theme={null}
SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4, 5, 12, 45, 12, 3, 3, 4, 5, 6]) AS print_0
```

```response title=Response theme={null}
┌───────────print_0─────────────────┐
│[0,0,0,0,0,0,0,0,0,27,0,0,0,0,0,0] │
└───────────────────────────────────┘
```

**用于时间序列数据离群值检测的自定义参数**

```sql title=Query theme={null}
SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4.50, 5, 12, 45, 12, 3.40, 3, 4, 5, 6], 0.2, 0.8, 1.5) AS print_0
```

```response title=Response theme={null}
┌─print_0──────────────────────────────┐
│ [0,0,0,0,0,0,0,0,0,19.5,0,0,0,0,0,0] │
└──────────────────────────────────────┘
```

<div id="seriesPeriodDetectFFT">
  ## seriesPeriodDetectFFT
</div>

引入于：v23.12.0

使用 FFT - [快速傅里叶变换](https://en.wikipedia.org/wiki/Fast_Fourier_transform) 检测给定时间序列数据的周期

**语法**

```sql theme={null}
seriesPeriodDetectFFT(series)
```

**参数**

* `series` — 数值数组。[`Array((U)Int8/16/32/64)`](/zh/reference/data-types/array) 或 [`Array(Float*)`](/zh/reference/data-types/array)

**返回值**

返回一个实数值，表示序列数据的周期。当数据点少于 4 个时，返回 NaN。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用简单模式检测周期**

```sql title=Query theme={null}
SELECT seriesPeriodDetectFFT([1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6]) AS print_0
```

```response title=Response theme={null}
┌───────────print_0──────┐
│                      3 │
└────────────────────────┘
```

**复杂模式的周期检测**

```sql title=Query theme={null}
SELECT seriesPeriodDetectFFT(arrayMap(x -> abs((x % 6) - 3), range(1000))) AS print_0
```

```response title=Response theme={null}
┌─print_0─┐
│       6 │
└─────────┘
```

<div id="timeSeriesCopyTag">
  ## timeSeriesCopyTag
</div>

引入版本：v26.1.0

将指定标签从一个标签组 (`src_group`) 复制到另一个标签组 (`dest_group`) 。
该函数会覆盖 `dest_group` 中该复制标签之前的任何值。
如果 `src_group` 中不存在该标签，则函数也会将其从 `dest_group` 中移除。
该函数模拟了 prometheus
[group left/group right](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) 修饰符的复制逻辑。

**语法**

```sql theme={null}
timeSeriesCopyTag(dest_group, src_group, tag_to_copy)
```

**参数**

* `dest_group` — 目标标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `src_group` — 源标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `tag_to_copy` — 要复制的标签名称。[`String`](/zh/reference/data-types/string)

**返回值**

返回一个标签组，其中包含 `dest_group` 中的标签，以及从 `src_group` 复制过来的标签。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS dest_group,
       timeSeriesTagsToGroup([('code', '404'), ('message', 'Page not found')], '__name__', 'http_codes') AS src_group,
       timeSeriesCopyTag(dest_group, src_group, '__name__') AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesCopyTags">
  ## timeSeriesCopyTags
</div>

引入版本：v26.1.0

将指定的标签从一个标签组 (`src_group`) 复制到另一个标签组 (`dest_group`) 。
该函数会替换 `dest_group` 中这些已复制标签原有的值。
如果某些要复制的标签在 `src_group` 中不存在，该函数也会将它们从 `dest_group` 中删除。
该函数模拟了 Prometheus
[group left/group right](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) 修饰符的复制逻辑。

**语法**

```sql theme={null}
timeSeriesCopyTags(dest_group, src_group, tags_to_copy)
```

**参数**

* `dest_group` — 目标标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `src_group` — 源标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `tags_to_copy` — 要复制的标签名称。[`Array(String)`](/zh/reference/data-types/array)

**返回值**

返回一个标签组，其中包含 `dest_group` 中的标签，以及从 `src_group` 复制过来的标签。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS dest_group,
       timeSeriesTagsToGroup([('code', '404'), ('message', 'Page not found')], '__name__', 'http_codes') AS src_group,
       timeSeriesCopyTags(dest_group, src_group, ['__name__', 'code', 'env']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesExtractTag">
  ## timeSeriesExtractTag
</div>

首次引入版本：v26.1.0

从标签组中提取指定标签的值。若未找到，则返回 NULL。
另请参见函数 [timeSeriesGroupToTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags)。

**语法**

```sql theme={null}
timeSeriesExtractTag(group)
```

**参数**

* `group` — 一个标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `tag_to_extract` — 要从该标签组中提取的标签名称 [`String`](/zh/reference/data-types/string)

**返回值**

返回指定标签的值。[`Nullable(String)`](/zh/reference/data-types/nullable)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesExtractTag(group, '__name__'),
       timeSeriesExtractTag(group, 'env'),
       timeSeriesExtractTag(group, 'instance')
```

```response title=Response theme={null}
┌─group─┬─timeSeriesExtractTag(group, '__name__')─┬─timeSeriesExtractTag(group, 'env')─┬─timeSeriesExtractTag(group, 'instance')─┐
│     1 │ http_requests_count                     │ dev                                │ ᴺᵁᴸᴸ                                    │
└───────┴─────────────────────────────────────────┴────────────────────────────────────┴─────────────────────────────────────────┘
```

<div id="timeSeriesFromGrid">
  ## timeSeriesFromGrid
</div>

首次引入版本：v25.8.0

将值数组 `[x1, x2, x3, ...]` 转换为元组数组
`[(start_timestamp, x1), (start_timestamp + step, x2), (start_timestamp + 2 * step, x3), ...]`。

当前时间戳会按 `step` 递增，直到大于 `end_timestamp`。
如果值的数量与时间戳的数量不一致，该函数会抛出异常。

`[x1, x2, x3, ...]` 中的 NULL 值会被跳过，但当前时间戳仍会继续递增。
例如，对于 `[value1, NULL, x2]`，函数返回 `[(start_timestamp, x1), (start_timestamp + 2 * step, x2)]`。

**语法**

```sql theme={null}
timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)
```

**参数**

* `start_timestamp` — 网格的起点。[`DateTime64`](/zh/reference/data-types/datetime64) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UInt32`](/zh/reference/data-types/int-uint)
* `end_timestamp` — 网格的终点。[`DateTime64`](/zh/reference/data-types/datetime64) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UInt32`](/zh/reference/data-types/int-uint)
* `step` — 网格步长 (以秒为单位) 。[`Decimal64`](/zh/reference/data-types/decimal) 或 [`Decimal32`](/zh/reference/data-types/decimal) 或 [`UInt32/64`](/zh/reference/data-types/int-uint)
* `values` — 值数组。[`Array(Float*)`](/zh/reference/data-types/array) 或 [`Array(Nullable(Float*))`](/zh/reference/data-types/array)

**返回值**

返回源数组中的值，并将其与由 `start_timestamp` 和 `step` 定义的规则时间网格上的时间戳组合。[`Array(Tuple(DateTime64, Float64))`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT timeSeriesFromGrid('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:30.000'::DateTime64(3), 30, [10, 20, NULL, 30]) AS result;
```

```response title=Response theme={null}
┌─────────────────────────────────────────────result─────────────────────────────────────────────┐
│ [('2025-06-01 00:00:00.000',10),('2025-06-01 00:00:30.000',20),('2025-06-01 00:01:30.000',30)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesGroupToSamplingKey">
  ## timeSeriesGroupToSamplingKey
</div>

引入版本：v26.4.0

返回一个由指定组的标签派生出的稳定 `UInt64` 采样键。

该值具有确定性：相同的输入标签始终会生成相同的键。
它适合作为 `limitk` 和 `limit_ratio` 等采样运算符的排序键。

**语法**

```sql theme={null}
timeSeriesGroupToSamplingKey(group)
```

**参数**

* `group` — 标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**返回值**

根据与该组关联的标签计算得出的稳定 `UInt64` 哈希值。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToSamplingKey(group) AS sampling_key
```

```response title=Response theme={null}
┌─group─┬─────────sampling_key─┐
│     1 │ 12876543210987654321 │
└───────┴──────────────────────┘
```

<div id="timeSeriesGroupToTags">
  ## timeSeriesGroupToTags
</div>

引入版本：v26.1.0

返回与指定组关联的标签名称和值。
另请参见函数 [timeSeriesTagsToGroup()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesTagsToGroup)。

**语法**

```sql theme={null}
timeSeriesGroupToTags(group)
```

**别名**：`timeSeriesTagsGroupToTags`

**参数**

* `group` — 标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**返回值**

返回一个由 `(tag_name, tag_value)` 对组成的数组。
返回的数组始终按 `tag_name` 排序，且同一个 `tag_name` 不会出现多次。
[`Array(Tuple(String, String))`](/zh/reference/data-types/array)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToTags(group) AS sorted_tags,
       timeSeriesTagsToGroup(sorted_tags) AS same_group,
       throwIf(same_group != group)
```

```response title=Response theme={null}
┌─group─┬─sorted_tags────────────────────────────────────────────────────────┬─same_group─┬─throwIf(notE⋯up, group))─┐
│     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │          1 │                        0 │
└───────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────┘
```

<div id="timeSeriesIdToGroup">
  ## timeSeriesIdToGroup
</div>

引入版本：v26.1.0

返回与指定时间序列标识符关联的标签名称和值。
另请参见函数 [timeSeriesStoreTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags)。

**语法**

```sql theme={null}
timeSeriesIdToGroup(id)
```

**别名**: `timeSeriesIdToTagsGroup`

**参数**

* `id` — 时间序列的标识符。[`UInt64`](/zh/reference/data-types/int-uint) 或 [`UInt128`](/zh/reference/data-types/int-uint) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`FixedString(16)`](/zh/reference/data-types/fixedstring)

**返回值**

返回与时间序列标识符 `id` 对应的标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToGroup(same_id) AS group,
       timeSeriesGroupToTags(group)
```

```response title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─group─┬─timeSeriesGroupToTags(group)───────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴───────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesIdToTags">
  ## timeSeriesIdToTags
</div>

引入版本：v25.8.0

返回与指定时间序列标识符相关联的标签。
另请参见函数 [timeSeriesStoreTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags)。

**语法**

```sql theme={null}
timeSeriesIdToTags(id)
```

**参数**

* `id` — 时间序列的标识符。[`UInt64`](/zh/reference/data-types/int-uint) 或 [`UInt128`](/zh/reference/data-types/int-uint) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`FixedString(16)`](/zh/reference/data-types/fixedstring)

**返回值**

返回一个由 `(tag_name, tag_value)` 对组成的数组。
返回的数组始终按 `tag_name` 排序，且同一个 `tag_name` 不会重复出现。
[`Array(Tuple(String, String))`](/zh/reference/data-types/array)

**示例**

**示例**

```sql title=Query theme={null}
SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id)
```

```response title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesJoinTags">
  ## timeSeriesJoinTags
</div>

引入版本：v26.1.0

将从标签组中提取的指定标签值拼接起来。
该函数会在拼接后的各个值之间插入分隔符，并返回一个新的标签组，
其中标签 `dest_tag` 的值为拼接后的结果。
该函数模拟了 Prometheus 函数
[label\_join()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_join) 的逻辑。

**语法**

```sql theme={null}
timeSeriesJoinTags(group, dest_tag, separator, src_tags)
```

**参数**

* `group` — 一个标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `dest_tag` — 保存拼接结果并将添加到 `group` 中的标签名称。[`String`](/zh/reference/data-types/string)
* `separator` — 在拼接后的值之间插入的分隔符。[`String`](/zh/reference/data-types/string)
* `src_tags` — 值将被拼接在一起的源标签名称。[`Array(String)`](/zh/reference/data-types/array)

**返回值**

返回一个新的标签组，其中 `dest_tag` 标签的值为拼接结果。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('src1', 'a'), ('src2', 'b'), ('src3', 'c')]) AS group,
       timeSeriesJoinTags(group, 'foo', ',', ['src1', 'src2', 'src3']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─────────────────────────────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a,b,c'),('job','api-server'),('src1','a'),('src2','b'),('src3','c')] │
└───────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesRange">
  ## timeSeriesRange
</div>

引入版本：v25.8.0

生成一个时间戳范围 `[start&#95;timestamp, start&#95;timestamp + step, start&#95;timestamp + 2 * step, ..., end&#95;timestamp]`。

如果 `start_timestamp` 等于 `end_timestamp`，该函数会返回一个仅包含 `[start_timestamp]` 的单元素数组。

函数 `timeSeriesRange()` 与函数 [range](/zh/reference/functions/regular-functions/array-functions#range) 类似。

**语法**

```sql theme={null}
timeSeriesRange(start_timestamp, end_timestamp, step)
```

**参数**

* `start_timestamp` — 范围的起始值。[`DateTime64`](/zh/reference/data-types/datetime64) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UInt32`](/zh/reference/data-types/int-uint)
* `end_timestamp` — 范围的结束值。[`DateTime64`](/zh/reference/data-types/datetime64) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UInt32`](/zh/reference/data-types/int-uint)
* `step` — 范围的步长，单位为秒。[`UInt32/64`](/zh/reference/data-types/int-uint) 或 [`Decimal32/64`](/zh/reference/data-types/decimal)

**返回值**

返回一个时间戳范围。[`Array(DateTime64)`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30)
```

```response title=Response theme={null}
┌────────────────────────────────────result─────────────────────────────────────────┐
│ ['2025-06-01 00:00:00.000', '2025-06-01 00:00:30.000', '2025-06-01 00:01:00.000'] │
└───────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesRemoveAllTagsExcept">
  ## timeSeriesRemoveAllTagsExcept
</div>

引入版本：v26.1.0

从标签组中移除除指定标签外的所有标签。
另请参见函数 [timeSeriesRemoveTag()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags)。

**语法**

```sql theme={null}
timeSeriesRemoveAllTagsExcept(group, tags_to_keep)
```

**参数**

* `group` — 一个标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `tags_to_keep` — 要在该标签组中保留的标签名称。[`Array(String)`](/zh/reference/data-types/array)

**返回值**

一个仅保留指定标签的新标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesRemoveAllTagsExcept(group, ['env']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─┐
│     1 │            2 │ [('env','dev')]                     │
└───────┴──────────────┴─────────────────────────────────────┘
```

<div id="timeSeriesRemoveTag">
  ## timeSeriesRemoveTag
</div>

Introduced in：v26.1.0

从标签组中移除指定标签。
如果该组中不存在该标签，则原样返回该组。
另请参见函数 [timeSeriesRemoveTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags)、
[timeSeriesRemoveAllTagsExcept()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept)。

**Syntax**

```sql theme={null}
timeSeriesRemoveTag(group, tag_to_remove)
```

**参数**

* `group` — 一个标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `tag_to_remove` — 要从该标签组中移除的标签名称。[`String`](/zh/reference/data-types/string)

**返回值**

一个不包含指定标签的新标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group_of_3,
       timeSeriesRemoveTag(group_of_3, '__name__') AS group_of_2,
       timeSeriesGroupToTags(group_of_2),
       timeSeriesRemoveTag(group_of_2, 'env') AS group_of_1,
       timeSeriesGroupToTags(group_of_1),
       timeSeriesRemoveTag(group_of_1, 'region') AS empty_group,
       timeSeriesGroupToTags(empty_group)
```

```response title=Response theme={null}
┌─group_of_3─┬─group_of_2─┬─timeSeriesGroupToTags(group_of_2)─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)─┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('env','dev'),('region','eu')]   │          3 │ [('region','eu')]                 │           0 │ []                                 │
└────────────┴────────────┴───────────────────────────────────┴────────────┴───────────────────────────────────┴─────────────┴────────────────────────────────────┘
```

<div id="timeSeriesRemoveTags">
  ## timeSeriesRemoveTags
</div>

Introduced in: v26.1.0

从标签组中移除指定标签。
如果指定的某些标签不在标签组中，函数会将其忽略。
另请参见函数 [timeSeriesRemoveTag()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag)、
[timeSeriesRemoveAllTagsExcept()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept)。

**Syntax**

```sql theme={null}
timeSeriesRemoveTags(group, tags_to_remove)
```

**参数**

* `group` — 一个标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `tags_to_remove` — 要从此标签组中移除的标签名称。[`Array(String)`](/zh/reference/data-types/array)

**返回值**

一个不包含指定标签的新标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group_of_3,
       timeSeriesRemoveTags(group_of_3, ['env', 'region']) AS group_of_1,
       timeSeriesGroupToTags(group_of_1),
       timeSeriesRemoveTags(group_of_1, ['__name__', 'nonexistent']) AS empty_group,
       timeSeriesGroupToTags(empty_group)
```

```response title=Response theme={null}
┌─group_of_3─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)────┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('__name__','http_requests_count')] │           0 │ []                                 │
└────────────┴────────────┴──────────────────────────────────────┴─────────────┴────────────────────────────────────┘
```

<div id="timeSeriesReplaceTag">
  ## timeSeriesReplaceTag
</div>

Introduced in: v26.1.0

将正则表达式 `regex` 与标签 `src_tag` 的值匹配。
如果匹配成功，返回组中标签 `dest_tag` 的值将为 `replacement` 的展开结果，
同时保留输入中的原始标签。
此函数模拟了 prometheus 函数
[label\_replace()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_replace) 的逻辑。

**Syntax**

```sql theme={null}
timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)
```

**参数**

* `group` — 一个标签组。[`UInt64`](/zh/reference/data-types/int-uint)
* `dest_tag` — 用于获取结果标签组的目标标签名称。[`String`](/zh/reference/data-types/string)
* `replacement` — 替换模式，可以包含 $1、$2 或 \$name，以引用正则表达式 'regex' 中的捕获组。[`String`](/zh/reference/data-types/string)
* `src_tag` — 值将用于匹配正则表达式 'regex' 的标签名称。[`String`](/zh/reference/data-types/string)
* `regex` — 正则表达式。[`String`](/zh/reference/data-types/string)

**返回值**

一个新的标签组，可能会新增 `dest_tag`。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('service', 'a:c')]) AS group,
       timeSeriesReplaceTag(group, 'foo', '$1', 'service', '(.*):.*') AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a'),('job','api-server'),('service','a:c')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesStoreTags">
  ## timeSeriesStoreTags
</div>

引入版本：v25.8.0

在查询上下文中存储指定时间序列标识符与一组标签之间的映射。
函数 [timeSeriesIdToTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesIdToTags)
和 [timeSeriesIdToGroup()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesIdToGroup)
可用于在查询执行过程中的后续阶段访问此映射。

**语法**

```sql theme={null}
timeSeriesStoreTags(id, tags_array, separate_tag_name_1, separate_tag_value_1, ...)
```

**参数**

* `id` — 时间序列的标识符。[`UInt64`](/zh/reference/data-types/int-uint) 或 [`UInt128`](/zh/reference/data-types/int-uint) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`FixedString(16)`](/zh/reference/data-types/fixedstring)
* `tags_array` — 由 (`tag&#95;name`, `tag&#95;value`) 对组成的数组。[`Array(Tuple(String, String))`](/zh/reference/data-types/array) 或 [`NULL`](/zh/reference/syntax#null)
* `separate_tag_name_i` — 标签名称。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `separate_tag_value_i` — 标签值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Nullable(String)`](/zh/reference/data-types/nullable)

**返回值**

返回时间序列的标识符 (即第一个参数) 。

**示例**

**示例**

```sql title=Query theme={null}
SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id),
       timeSeriesGroupToTags(timeSeriesIdToGroup(same_id))
```

```response title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notEquals(same_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┬─timeSeriesGroupToTags(timeSeriesIdToGroup(same_id))────────────────┐
│ 8374283493092 │ 8374283493092 │                               0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴─────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesTagsToGroup">
  ## timeSeriesTagsToGroup
</div>

Introduced in: v26.1.0

返回与指定标签关联的标签组。
如果在查询执行过程中多次遇到同一个标签组，该函数会返回相同的标签组。
对于空标签集，该函数始终返回 0。
另请参见函数 [timeSeriesGroupToTags()](/zh/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags)。

**语法**

```sql theme={null}
timeSeriesTagsToGroup(tags_array, tag_name_1, tag_value_1, tag_name2, tag_value2, ...)
```

**参数**

* `tags_array` — 由 (tag\_name, tag\_value) 对组成的 Array。[`Array(Tuple(String, String))`](/zh/reference/data-types/array) 或 [`NULL`](/zh/reference/syntax#null)
* `tag_name_i` — 标签名称。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `tag_value_i` — 标签值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Nullable(String)`](/zh/reference/data-types/nullable)

**返回值**

返回与指定标签关联的标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group1,
       timeSeriesTagsToGroup([], '__name__', 'http_failures') AS group2,
       timeSeriesTagsToGroup([]) AS empty_group,
       timeSeriesTagsToGroup([], '__name__', 'http_failures') AS same_group2,
       throwIf(same_group2 != group2),
       timeSeriesGroupToTags(group2)
```

```response title=Response theme={null}
┌─group1─┬─group2─┬─empty_group─┬─same_group2─┬─throwIf(notEquals(same_group2, group2))─┬─timeSeriesGroupToTags(group2)──┐
│      1 │      2 │           0 │           2 │                                       0 │ [('__name__','http_failures')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘
```

<div id="timeSeriesThrowDuplicateSeriesIf">
  ## timeSeriesThrowDuplicateSeriesIf
</div>

引入版本：v26.2.0

检查 `condition`，如果其为 true，则抛出异常，并显示以下消息：
`Multiple series have the same tags <tags>, duplicate series in the same result set are not allowed`。
如果 `condition` 为 false，则函数返回 `0`。
此函数与 [throwIf()](/zh/reference/functions/regular-functions/other-functions#throwIf) 类似，
但使用了不同的错误代码，且错误消息的格式也不同。

**语法**

```sql theme={null}
timeSeriesThrowDuplicateSeriesIf(condition, group)
```

**参数**

* `condition` — 待检查的条件，通常包含 [count()](/zh/reference/functions/aggregate-functions/count#count) 函数。[`UInt8`](/zh/reference/data-types/int-uint)
* `group` — 标签组。[`UInt64`](/zh/reference/data-types/int-uint)

**返回值**

返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**示例**

```sql title=Query theme={null}
CREATE TABLE test(tags Array(Tuple(String, String))) engine=Memory;

INSERT INTO test VALUES ([('__name__', 'up')]);

SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0;  -- 正常

INSERT INTO test VALUES ([('__name__', 'up')]);

SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0;  -- 抛出异常 "Multiple series have the same tags {'__name__': 'up'}"
```

```response title=Response theme={null}
```