跳至主要内容
跳至主要内容

时间序列函数

以下函数设计用于与 timeSeries*() 聚合函数一起使用,例如 timeSeriesInstantRateToGridtimeSeriesLastToGrid 等。

seriesDecomposeSTL

引入版本: v24.1

使用 STL(基于 Loess 的季节-趋势分解程序)(Seasonal-Trend Decomposition Procedure Based on Loess) 将序列数据分解为季节性分量、趋势分量和残差分量。

语法

seriesDecomposeSTL(series, period)

参数

返回值

返回一个包含四个数组的数组,其中第一个数组包含季节性分量,第二个数组包含趋势分量,第三个数组包含残差分量,第四个数组包含基线(季节性 + 趋势)分量。 Array(Array(Float32), Array(Float32), Array(Float32), Array(Float32))

示例

使用 STL 分解序列数据

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
┌───────────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
    ]]                                                                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

seriesOutliersDetectTukey

引入于:v24.2

使用 Tukey 围栏 检测序列数据中的异常值。

语法

seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])

参数

  • series — 数字值的数组。 Array((UInt8/16/32/64))Array(Float*)
  • min_percentile — 可选。用于计算四分位距 (IQR) (IQR) 的最小值百分位数。该值必须在 [0.02,0.98] 范围内。默认值为 0.25。 Float*
  • max_percentile — 可选。用于计算四分位距 (IQR) 的最大值百分位数。该值必须在 [0.02,0.98] 范围内。默认值为 0.75。 Float*
  • K — 可选。用于检测轻微或更强异常值的非负常数值。默认值为 1.5。 Float*

返回值

返回一个与输入数组长度相同的数组,其中每个值表示序列中相应元素可能的异常值评分。非零评分表示可能的异常值。 Array(Float32)

示例

基本异常值检测

SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4, 5, 12, 45, 12, 3, 3, 4, 5, 6]) AS print_0
┌───────────print_0─────────────────┐
│[0,0,0,0,0,0,0,0,0,27,0,0,0,0,0,0] │
└───────────────────────────────────┘

自定义参数异常值检测

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
┌─print_0──────────────────────────────┐
│ [0,0,0,0,0,0,0,0,0,19.5,0,0,0,0,0,0] │
└──────────────────────────────────────┘

seriesPeriodDetectFFT

引入于:v23.12

使用 FFT(快速傅里叶变换)(Fast Fourier transform) 查找给定序列数据的周期。

语法

seriesPeriodDetectFFT(series)

参数

返回值

返回一个实数值,等于序列数据的周期。当数据点数量少于四个时,返回 NaN。 Float64

示例

具有简单模式的周期检测

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
┌───────────print_0──────┐
│                      3 │
└────────────────────────┘

具有复杂模式的周期检测

SELECT seriesPeriodDetectFFT(arrayMap(x -> abs((x % 6) - 3), range(1000))) AS print_0
┌─print_0─┐
│       6 │
└─────────┘

timeSeriesCopyTag

引入于:v26.1

将指定的标签从一组标签(src_group)复制到另一组(dest_group)。该函数替换 dest_group 中复制标签的任何先前值。如果复制的标签不存在于 src_group 中,则该函数也会将其从 dest_group 中删除。该函数模拟了 prometheus group left/group right 修饰符的复制逻辑。

语法

timeSeriesCopyTag(dest_group, src_group, tag_to_copy)

参数

  • dest_group — 目标标签组。 UInt64
  • src_group — 源标签组。 UInt64
  • tag_to_copy — 要复制的标签名称。 String

返回值

返回一个包含来自 dest_group 的标签以及从 src_group 复制的标签的标签组。 UInt64

示例

示例

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)
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘

timeSeriesCopyTags

引入于:v26.1

将指定的标签从一组标签(src_group)复制到另一组(dest_group)。该函数替换 dest_group 中复制标签的任何先前值。如果某些复制的标签不存在于 src_group 中,则该函数也会在 dest_group 中删除它们。该函数模拟了 prometheus group left/group right 修饰符的复制逻辑。

语法

timeSeriesCopyTags(dest_group, src_group, tags_to_copy)

参数

  • dest_group — 目标标签组。 UInt64
  • src_group — 源标签组。 UInt64
  • tags_to_copy — 要复制的标签名称。 Array(String)

返回值

返回一个包含来自 dest_group 的标签以及从 src_group 复制的标签的标签组。 UInt64

示例

示例

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)
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘

timeSeriesExtractTag

引入于:v26.1

从组中提取指定的标签值。如果未找到,则返回 NULL。另请参阅函数 timeSeriesGroupToTags()

语法

timeSeriesExtractTag(group)

参数

  • group — 一个标签组。 UInt64
  • tag_to_extract — 要从组中提取的标签名称 String

返回值

返回指定的标签值。 Nullable(String)

示例

示例

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesExtractTag(group, '__name__'),
       timeSeriesExtractTag(group, 'env'),
       timeSeriesExtractTag(group, 'instance')
┌─group─┬─timeSeriesExtractTag(group, '__name__')─┬─timeSeriesExtractTag(group, 'env')─┬─timeSeriesExtractTag(group, 'instance')─┐
│     1 │ http_requests_count                     │ dev                                │ ᴺᵁᴸᴸ                                    │
└───────┴─────────────────────────────────────────┴────────────────────────────────────┴─────────────────────────────────────────┘

timeSeriesFromGrid

引入于: v25.8

将值数组 [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)]

语法

timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)

参数

返回值

返回来自源值数组的值与时间戳的组合,这些时间戳位于由 start_timestampstep 描述的规则时间网格上。 Array(Tuple(DateTime64, Float64))

示例

使用示例

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;
┌─────────────────────────────────────────────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)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘

timeSeriesGroupToTags

引入于:v26.1

返回与指定组关联的标签的名称和值。另请参阅函数 timeSeriesTagsToGroup()

语法

timeSeriesGroupToTags(group)

别名timeSeriesTagsGroupToTags

参数

  • group — 一个标签组。 UInt64

返回值

返回一个 (tag_name, tag_value) 对的数组。返回的数组始终按 tag_name 排序,并且从不包含相同的 tag_name 多次。

示例

示例

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)
┌─group─┬─sorted_tags────────────────────────────────────────────────────────┬─same_group─┬─throwIf(notE⋯up, group))─┐
│     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │          1 │                        0 │
└───────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────┘

timeSeriesIdToGroup

引入于:v26.1

返回与指定时间序列标识符关联的标签的名称和值。另请参阅函数 timeSeriesStoreTags()

语法

timeSeriesIdToGroup(id)

别名timeSeriesIdToTagsGroup

参数

返回值

返回与时间序列的标识符 id 关联的标签组。 UInt64

示例

示例

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)
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─group─┬─timeSeriesGroupToTags(group)───────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴───────┴────────────────────────────────────────────────────────────────────┘

timeSeriesIdToTags

引入于: v25.8

返回与指定时间序列标识符关联的标签。另请参阅函数 timeSeriesStoreTags()

语法

timeSeriesIdToTags(id)

参数

返回值

返回一个 (tag_name, tag_value) 对的数组。返回的数组始终按 tag_name 排序,并且从不包含相同的 tag_name 多次。

示例

示例

SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id)
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴────────────────────────────────────────────────────────────────────┘

timeSeriesJoinTags

引入于:v26.1

将从标签组中提取的指定标签的值连接起来。该函数在连接的值之间插入分隔符,并返回一个标签组,其中 dest_tag 标签设置为连接的结果。此函数模拟了 prometheus 函数 label_join() 的逻辑。

语法

timeSeriesJoinTags(group, dest_tag, separator, src_tags)

参数

  • group — 一个标签组。 UInt64
  • dest_tag — 将添加到 group 中的连接结果的标签名称。 String
  • separator — 要插入连接值之间的分隔符。 String
  • src_tags — 具有要连接的值的源标签的名称。 Array(String)

返回值

返回一个新标签组,其中 dest_tag 标签设置为连接的结果。 UInt64

示例

示例

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)
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─────────────────────────────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a,b,c'),('job','api-server'),('src1','a'),('src2','b'),('src3','c')] │
└───────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘

timeSeriesRange

引入于: v25.8

生成时间戳范围 [start_timestamp, start_timestamp + step, start_timestamp + 2 * step, ..., end_timestamp]。

如果 start_timestamp 等于 end_timestamp,则该函数返回包含 [start_timestamp] 的一个元素数组。

函数 timeSeriesRange() 类似于函数 range

语法

timeSeriesRange(start_timestamp, end_timestamp, step)

参数

返回值

返回一个时间戳范围。 Array(DateTime64)

示例

使用示例

SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30)
┌────────────────────────────────────result─────────────────────────────────────────┐
│ ['2025-06-01 00:00:00.000', '2025-06-01 00:00:30.000', '2025-06-01 00:01:00.000'] │
└───────────────────────────────────────────────────────────────────────────────────┘

timeSeriesRemoveAllTagsExcept

引入于:v26.1

删除标签组中除指定标签以外的所有标签。另请参阅函数 timeSeriesRemoveTag()timeSeriesRemoveTags()

语法

timeSeriesRemoveAllTagsExcept(group, tags_to_keep)

参数

  • group — 一个标签组。 UInt64
  • tags_to_keep — 要保留在组中的标签名称。 Array(String)

返回值

一个新标签组,仅保留指定的标签。 UInt64

示例

示例

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesRemoveAllTagsExcept(group, ['env']) AS result_group,
       timeSeriesGroupToTags(result_group)
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─┐
│     1 │            2 │ [('env','dev')]                     │
└───────┴──────────────┴─────────────────────────────────────┘

timeSeriesRemoveTag

引入于:v26.1

从一组标签中移除指定的标签。如果组中不存在该标签,则返回未更改的组。另请参阅函数 timeSeriesRemoveTags()timeSeriesRemoveAllTagsExcept()

语法

timeSeriesRemoveTag(group, tag_to_remove)

参数

  • group — 一个标签组。 UInt64
  • tag_to_remove — 要从组中移除的标签的名称。 String

返回值

一个不包含指定标签的新标签组。 UInt64

示例

示例

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)
┌─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 │ []                                 │
└────────────┴────────────┴───────────────────────────────────┴────────────┴───────────────────────────────────┴─────────────┴────────────────────────────────────┘

timeSeriesRemoveTags

引入于:v26.1

从一组标签中移除指定的标签。如果指定的标签中有些不在标签组中,该函数会忽略它们。另请参阅函数 timeSeriesRemoveTag()timeSeriesRemoveAllTagsExcept()

语法

timeSeriesRemoveTags(group, tags_to_remove)

参数

  • group — 一个标签组。 UInt64
  • tags_to_remove — 要从组中移除的标签名称。 Array(String)

返回值

一个不包含指定标签的新标签组。 UInt64

示例

示例

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)
┌─group_of_3─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)────┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('__name__','http_requests_count')] │           0 │ []                                 │
└────────────┴────────────┴──────────────────────────────────────┴─────────────┴────────────────────────────────────┘

timeSeriesReplaceTag

引入于:v26.1

将正则表达式 regex 与标签 src_tag 的值匹配。如果匹配,则返回组中标签 dest_tag 的值将是 replacement 的扩展,以及输入中的原始标签。此函数模仿了 prometheus 函数 label_replace() 的逻辑。

语法

timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)

参数

  • group — 一个标签组。 UInt64
  • dest_tag — 获取结果组的目标标签的名称。 String
  • replacement — 替换模式,可以包含 1,1, 2 或 $name 以引用正则表达式 'regex' 中的捕获组。 String
  • src_tag — 用于匹配正则表达式 'regex' 的标签的名称。 String
  • regex — 一个正则表达式。 String

返回值

一个包含可能添加了 dest_tag 的新标签组。 UInt64

示例

示例

SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('service', 'a:c')]) AS group,
       timeSeriesReplaceTag(group, 'foo', '$1', 'service', '(.*):.*') AS result_group,
       timeSeriesGroupToTags(result_group)
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a'),('job','api-server'),('service','a:c')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘

timeSeriesStoreTags

引入于: v25.8

在查询上下文中存储一个时间序列标识符与其一组标签之间的映射。函数 timeSeriesIdToTags()timeSeriesIdToGroup() 可用于在查询执行期间访问此映射。

语法

timeSeriesStoreTags(id, tags_array, separate_tag_name_1, separate_tag_value_1, ...)

参数

返回值

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

示例

示例

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))
┌────────────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')] │
└───────────────┴───────────────┴─────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘

timeSeriesTagsToGroup

引入于:v26.1

返回与指定标签关联的标签组。如果在查询执行期间多次找到相同的标签组,该函数将返回相同的组。对于空标签集,该函数始终返回 0。另请参阅函数 timeSeriesGroupToTags()

语法

timeSeriesTagsToGroup(tags_array, tag_name_1, tag_value_1, tag_name2, tag_value2, ...)

参数

返回值

返回与指定标签关联的标签组。 UInt64

示例

示例

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)
┌─group1─┬─group2─┬─empty_group─┬─same_group2─┬─throwIf(notEquals(same_group2, group2))─┬─timeSeriesGroupToTags(group2)──┐
│      1 │      2 │           0 │           2 │                                       0 │ [('__name__','http_failures')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘
    © . This site is unofficial and not affiliated with ClickHouse, Inc.