时间序列函数

以下函数专为与 timeSeries*() 聚合函数配合使用而设计，例如 timeSeriesInstantRateToGrid、timeSeriesLastToGrid 等。

timeSeriesRange

生成一系列时间戳。

语法

timeSeriesRange(start_timestamp, end_timestamp, step)

参数

start_timestamp - 范围的起始时间戳。
end_timestamp - 范围的结束时间戳。
step - 范围的步长（单位：秒）。

返回值

返回一组时间戳序列 [start_timestamp, start_timestamp + step, start_timestamp + 2 * step, ..., end_timestamp]。

示例

查询：

SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30) AS rng;

结果：

┌────────────────────────────────────result─────────────────────────────────────────┐
│ ['2025-06-01 00:00:00.000', '2025-06-01 00:00:30.000', '2025-06-01 00:01:00.000'] │
└───────────────────────────────────────────────────────────────────────────────────┘

注意

如果调用函数 timeSeriesRange() 时，start_timestamp 等于 end_timestamp，则它会返回一个仅包含该时间戳的单元素数组：[start_timestamp]
函数 timeSeriesRange() 类似于函数 range。例如，如果时间戳类型为 DateTime64(3) 且 start_timestamp < end_timestamp，则 timeSeriesRange(start_timestamp, end_timestamp, step) 返回的结果与以下表达式相同：

range(start_timestamp::Int64, end_timestamp::Int64 + 1, step::Int64)::Array(DateTime64(3))

timeSeriesFromGrid

将数值数组 [value1, value2, value3, ..., valueN] 转换为元组数组 [(start_timestamp, value1), (start_timestamp + step, value2), (start_timestamp + 2 * step, value3), ..., (end_timestamp, valueN)]。

如果数组 [value1, value2, value3, ...] 中有一些值为 NULL，则函数不会将这些 NULL 值复制到结果数组中，但仍然会增加当前时间戳。例如，对于 [value1, NULL, value2]，函数将返回 [(start_timestamp, value1), (start_timestamp + 2 * step, value2)]。

当前时间戳按步长递增，直到其大于 end_timestamp，每个时间戳都会与指定值数组中的一个值配对。如果值的数量与时间戳的数量不匹配，函数将抛出异常。

语法

timeSeriesFromGrid(start_timestamp, end_timestamp, step, values);

参数

start_timestamp - 网格的起始时间。
end_timestamp - 网格的结束时间。
step - 网格的步长（以秒为单位）。
values - 值数组 [value1, value2, ..., valueN]。

返回值

返回在由 start_timestamp 和 step 定义的等间隔时间网格上，将时间戳与源值数组中的值对齐组合后的结果。

示例

查询：

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

注意函数 timeSeriesFromGrid(start_timestamp, end_timestamp, step, values) 返回的结果与下列表达式等价：

arrayFilter(x -> x.2 IS NOT NULL, arrayZip(timeSeriesRange(start_timestamp, end_timestamp, step), values))

seriesDecomposeSTL

引入版本：v24.1

使用 STL（基于 Loess 的季节-趋势分解方法 (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 — 时间网格的起始时间。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 起引入

在查询上下文中存储时间序列标识符与其标签之间的映射，以便 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')]

timeSeriesRange​

timeSeriesFromGrid​

seriesDecomposeSTL​

seriesOutliersDetectTukey​

seriesPeriodDetectFFT​

timeSeriesFromGrid​

timeSeriesIdToTags​

timeSeriesIdToTagsGroup​

timeSeriesRange​

timeSeriesStoreTags​

timeSeriesTagsGroupToTags​

timeSeriesRange

timeSeriesFromGrid

seriesDecomposeSTL

seriesOutliersDetectTukey

seriesPeriodDetectFFT

timeSeriesFromGrid

timeSeriesIdToTags

timeSeriesIdToTagsGroup

timeSeriesRange

timeSeriesStoreTags

timeSeriesTagsGroupToTags