时间序列函数

以下函数被设计用于与 timeSeries*() 聚合函数一起使用，例如 timeSeriesInstantRateToGrid、timeSeriesLastToGrid 等。

seriesDecomposeSTL

在 v24.1 中引入

使用 STL (Seasonal-Trend Decomposition Procedure Based on Loess) 将时间序列数据分解为季节成分、趋势成分和残差成分。

语法

seriesDecomposeSTL(series, period)

参数

series — 数值数组 Array((U)Int8/16/32/64) 或 Array(Float*)
period — 正整数 UInt8/16/32/64

返回值

返回一个由四个数组组成的数组，其中第一个数组为季节性成分，第二个数组为趋势成分，第三个数组为残差成分，第四个数组为基线（季节性 + 趋势）成分。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])

参数

series — 数值数组。Array((UInt8/16/32/64)) 或 Array(Float*)
min_percentile — 可选。用于计算四分位距 (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（快速傅里叶变换）检测给定序列数据的周期。

语法

seriesPeriodDetectFFT(series)

参数

series — 数值数组。Array((U)Int8/16/32/64) 或 Array(Float*)

返回值

返回一个实数，表示序列数据的周期。当数据点数量少于四个时，返回 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 │
└─────────┘

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 — 时间网格的起始时间。DateTime64 或 DateTime 或 UInt32
end_timestamp — 时间网格的结束时间。DateTime64 或 DateTime 或 UInt32
step — 时间网格的步长（以秒为单位）。Decimal64 或 Decimal32 或 UInt32/64
values — 值数组。Array(Float*) 或 Array(Nullable(Float*))

返回值

返回在由 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)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘

timeSeriesIdToTags

引入于：v25.8

查找与指定时间序列标识符关联的标签。

语法

timeSeriesIdToTags(id)

参数

id — 时间序列的标识符。UInt64 或 UInt128 或 UUID 或 FixedString(16)

返回值

返回由若干对 (tag_name, tag_value) 组成的数组。Array(Tuple(String, String))

示例

SELECT timeSeriesStoreTags(8374283493092, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS id, timeSeriesIdToTags(id)

8374283493092    [('__name__', ''http_requests_count''), ('env', 'dev'), ('region', 'eu')]

timeSeriesIdToTagsGroup

引入于：v25.8

将指定的时间序列标识符转换为其组索引。组索引是数字 0、1、2、3，在当前执行的查询上下文中与每种唯一的标签组合一一对应。

语法

timeSeriesIdToTagsGroup(id)

参数

id — 时间序列的标识符。UInt64 或 UInt128 或 UUID 或 FixedString(16)

返回值

返回与此标签集关联的组索引。UInt64

示例

SELECT timeSeriesStoreTags(8374283493092, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS id, timeSeriesIdToTagsGroup(id)

8374283493092    0

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)

参数

start_timestamp — 区间起始时间。DateTime64 或 DateTime 或 UInt32
end_timestamp — 区间结束时间。DateTime64 或 DateTime 或 UInt32
step — 区间步长（以秒为单位）。UInt32/64 或 Decimal32/64

返回值

返回一组时间戳。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'] │
└───────────────────────────────────────────────────────────────────────────────────┘

timeSeriesStoreTags

自 v25.8 起引入

在查询上下文中存储时间序列标识符与其标签（tags）之间的映射，以便函数 timeSeriesIdToTags() 稍后可以提取这些标签。

语法

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

参数

id — 时间序列的标识符。UInt64 或 UInt128 或 UUID 或 FixedString(16)
tags_array — 由 (tag_name, tag_value) 键值对组成的数组。Array(Tuple(String, String)) 或 NULL
separate_tag_name_i — 标签名称。String 或 FixedString
separate_tag_value_i — 标签值。String 或 FixedString 或 Nullable(String)

返回值

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

示例

SELECT timeSeriesStoreTags(8374283493092, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count')

8374283493092

timeSeriesTagsGroupToTags

自 v25.8 引入

查找与某个组索引关联的标签。组索引是在当前正在执行的查询上下文中，与每个唯一标签集合关联的编号 0、1、2、3。

语法

timeSeriesTagsGroupToTags(group)

参数

group — 与时间序列关联的分组索引。UInt64

返回值

由二元组 (tag_name, tag_value) 组成的数组。Array(Tuple(String, String))

示例

SELECT timeSeriesStoreTags(8374283493092, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS id, timeSeriesIdToTagsGroup(id) AS group, timeSeriesTagsGroupToTags(group)

8374283493092    0    [('__name__', ''http_requests_count''), ('env', 'dev'), ('region', 'eu')]

seriesDecomposeSTL​

seriesOutliersDetectTukey​

seriesPeriodDetectFFT​

timeSeriesFromGrid​

timeSeriesIdToTags​

timeSeriesIdToTagsGroup​

timeSeriesRange​

timeSeriesStoreTags​

timeSeriesTagsGroupToTags​

seriesDecomposeSTL

seriesOutliersDetectTukey

seriesPeriodDetectFFT

timeSeriesFromGrid

timeSeriesIdToTags

timeSeriesIdToTagsGroup

timeSeriesRange

timeSeriesStoreTags

timeSeriesTagsGroupToTags