時系列関数

以下の関数は、timeSeries*() 系の集約関数 (timeSeriesInstantRateToGrid、 timeSeriesLastToGrid など) と組み合わせて使用することを想定しています。

seriesDecomposeSTL

導入バージョン: v24.1

STL（Loess に基づく季節性・トレンド分解手法）を用いて系列データを季節成分、トレンド成分、および残差成分に分解します。

構文

seriesDecomposeSTL(series, period)

引数

series — 数値の配列。型は Array((U)Int8/16/32/64) または Array(Float*)
period — 正の整数。型は UInt8/16/32/64

戻り値

4 つの配列を要素とする配列を返します。1 つ目の配列には季節性成分、2 つ目の配列にはトレンド、3 つ目の配列には残差成分、4 つ目の配列にはベースライン（季節性 + トレンド）成分が含まれます。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 — 省略可。弱い外れ値または強い外れ値を検出するために使用される 0 以上の定数値。デフォルト値は 1.5 です。Float*

戻り値

入力配列と同じ長さの配列を返します。各値は、系列内の対応する要素が異常である可能性を表すスコアです。0 以外のスコアは異常の可能性を示します。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)

引数

series — 数値の配列。Array((U)Int8/16/32/64) または Array(Float*)

戻り値

系列データの周期を表す実数値を返します。データポイント数が 4 未満の場合は 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 — 時系列を識別する 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] を含む要素数 1 の配列を返します。

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')]

seriesDecomposeSTL​

seriesOutliersDetectTukey​

seriesPeriodDetectFFT​

timeSeriesFromGrid​

timeSeriesIdToTags​

timeSeriesIdToTagsGroup​

timeSeriesRange​

timeSeriesStoreTags​

timeSeriesTagsGroupToTags​

seriesDecomposeSTL

seriesOutliersDetectTukey

seriesPeriodDetectFFT

timeSeriesFromGrid

timeSeriesIdToTags

timeSeriesIdToTagsGroup

timeSeriesRange

timeSeriesStoreTags

timeSeriesTagsGroupToTags