以下函数旨在与 timeSeries*() 聚合函数一起使用,例如
timeSeriesInstantRateToGrid、timeSeriesLastToGrid 等。
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 Fences 检测序列数据中的异常值。
语法
seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])
参数
返回值
返回一个与输入数组长度相同的数组,其中每个值表示该序列中对应元素可能存在异常的得分。非零得分表示可能存在异常。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(快速傅里叶变换)检测给定序列数据的周期。
语法
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 的标签以及从 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')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
引入于: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 中已有的标签以及从 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')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
自 v26.1 起引入
从分组中提取指定标签的值。如果未找到则返回 NULL。
另请参阅函数 timeSeriesGroupToTags()。
语法
timeSeriesExtractTag(group)
参数
返回值
返回指定标签的值。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_timestamp 和 step 定义的等间隔时间网格上的时间戳组合在一起。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)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
自 v26.1 起提供
返回与指定 group 关联的标签名称和值。
另请参阅函数 timeSeriesTagsToGroup()。
语法
timeSeriesGroupToTags(group)
别名: timeSeriesTagsGroupToTags
参数
返回值
返回由若干 (tag_name, tag_value) 对组成的数组。
返回的数组始终按 tag_name 排序,且不会包含重复的 tag_name。
Array(Tuple(String, String))
示例
示例
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()。
语法
别名: 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')] │
└───────────────┴───────────────┴──────────────────────────┴───────┴────────────────────────────────────────────────────────────────────┘
自 v25.8 起可用
返回与指定时间序列标识符关联的标签。
另请参阅函数 timeSeriesStoreTags()。
语法
参数
返回值
返回一个由 (tag_name, tag_value) 组成的二元组数组。
返回的数组始终按 tag_name 排序,且任何 tag_name 至多出现一次。
Array(Tuple(String, String))
示例
示例
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')] │
└───────────────┴───────────────┴──────────────────────────┴────────────────────────────────────────────────────────────────────┘
引入版本:v26.1
将从一组标签中提取出的指定标签的值进行拼接。
该函数在拼接的值之间插入分隔符,并返回一个新的标签组,
其中标签 dest_tag 被设置为拼接后的值。
此函数模拟了 Prometheus 函数
label_join() 的逻辑。
语法
timeSeriesJoinTags(group, dest_tag, separator, src_tags)
参数
返回值
返回一个新的标签组,其中 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() FUNCTION 与 range FUNCTION 类似。
语法
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'] │
└───────────────────────────────────────────────────────────────────────────────────┘
引入版本:v26.1
从一组标签中移除除指定标签外的所有标签。
另请参见函数 timeSeriesRemoveTag()、timeSeriesRemoveTags()。
语法
timeSeriesRemoveAllTagsExcept(group, tags_to_keep)
参数
返回值
仅保留指定标签的新标签组。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)
参数
返回值
返回一个不包含指定标签的新标签组。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 │ [] │
└────────────┴────────────┴───────────────────────────────────┴────────────┴───────────────────────────────────┴─────────────┴────────────────────────────────────┘
自 v26.1 起引入。
从一组标签中移除指定的标签。
如果某些指定标签不在该标签组中,则函数会忽略它们。
另请参阅函数 timeSeriesRemoveTag()、timeSeriesRemoveAllTagsExcept()。
语法
timeSeriesRemoveTags(group, tags_to_remove)
参数
返回值
返回一个不包含指定标签的新标签组。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
对标签 src_tag 的值应用正则表达式 regex 进行匹配。
如果匹配成功,则返回结果中的标签 dest_tag 的值将是 replacement 展开的结果,
并与输入中的原始标签一同返回。
此函数仿照 prometheus 函数
label_replace() 的逻辑实现。
语法
timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)
参数
group — 一组 tag。UInt64
dest_tag — 用于接收结果分组的目标 tag 名称。String
replacement — 替换模式,可以包含 1、2 或 $name,用于引用正则表达式 regex 中的捕获分组。String
src_tag — 其值用于与正则表达式 regex 匹配的 tag 名称。String
regex — 正则表达式。String
返回值
一个新的 tag 分组,其中可能包含新增的 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')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘
引入版本: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')] │
└───────────────┴───────────────┴─────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
引入于: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')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘