> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 時系列を扱うための関数のドキュメント
# 時系列を扱うための関数
以下の関数は、次のような `timeSeries*()` 集約関数と組み合わせて使用することを想定しています。
[`timeSeriesInstantRateToGrid`](/ja/reference/functions/aggregate-functions/timeSeriesInstantRateToGrid)、
[`timeSeriesLastToGrid`](/ja/reference/functions/aggregate-functions/timeSeriesResampleToGridWithStaleness)
などです。
{/*AUTOGENERATED_START*/}
## seriesDecomposeSTL
導入バージョン: v24.1.0
STL [(Seasonal-Trend Decomposition Procedure Based on Loess)](https://www.wessa.net/download/stl.pdf) を使用して、時系列データを季節性、トレンド、残差の各成分に分解します。
**構文**
```sql theme={null}
seriesDecomposeSTL(series, period)
```
**引数**
* `series` — 数値の配列 [`Array((U)Int8/16/32/64)`](/ja/reference/data-types/array) または [`Array(Float*)`](/ja/reference/data-types/array)
* `period` — 正の整数 [`UInt8/16/32/64`](/ja/reference/data-types/int-uint)
**戻り値**
4つの配列からなる配列を返します。1つ目の配列には季節成分、2つ目の配列にはトレンド、3つ目の配列には残差成分、4つ目の配列にはベースライン (季節成分 + トレンド) が含まれます。 [`Array(Array(Float32), Array(Float32), Array(Float32), Array(Float32))`](/ja/reference/data-types/array)
**例**
**STL を使用して時系列データを分解する**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌───────────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.0
[Tukey Fences](https://en.wikipedia.org/wiki/Outlier#Tukey%27s_fences) を用いて時系列データの外れ値を検出します。
**構文**
```sql theme={null}
seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])
```
**引数**
* `series` — 数値の配列。[`Array((UInt8/16/32/64))`](/ja/reference/data-types/array) または [`Array(Float*)`](/ja/reference/data-types/array)
* `min_percentile` — 省略可能。四分位範囲[(IQR)](https://en.wikipedia.org/wiki/Interquartile_range)の計算に使用する最小のパーセンタイル。値は \[0.02,0.98] の範囲内である必要があります。デフォルトは 0.25 です。[`Float*`](/ja/reference/data-types/float)
* `max_percentile` — 省略可能。四分位範囲 (IQR) の計算に使用する最大のパーセンタイル。値は \[0.02,0.98] の範囲内である必要があります。デフォルトは 0.75 です。[`Float*`](/ja/reference/data-types/float)
* `K` — 省略可能。軽度以上の外れ値を検出するための非負の定数値。デフォルト値は 1.5 です。[`Float*`](/ja/reference/data-types/float)
**戻り値**
入力配列と同じ長さの配列を返します。各値は、`series` 内の対応する要素に異常の可能性があることを示すスコアを表します。スコアがゼロ以外の場合は、異常の可能性を示します。[`Array(Float32)`](/ja/reference/data-types/array)
**例**
**基本的な外れ値検出**
```sql title=Query theme={null}
SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4, 5, 12, 45, 12, 3, 3, 4, 5, 6]) AS print_0
```
```response title=Response theme={null}
┌───────────print_0─────────────────┐
│[0,0,0,0,0,0,0,0,0,27,0,0,0,0,0,0] │
└───────────────────────────────────┘
```
**カスタムパラメータを用いた外れ値検出**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─print_0──────────────────────────────┐
│ [0,0,0,0,0,0,0,0,0,19.5,0,0,0,0,0,0] │
└──────────────────────────────────────┘
```
## seriesPeriodDetectFFT
導入バージョン: v23.12.0
FFT - [Fast Fourier transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform) を使用して、指定された時系列データの周期を検出します
**構文**
```sql theme={null}
seriesPeriodDetectFFT(series)
```
**引数**
* `series` — 数値の配列です。[`Array((U)Int8/16/32/64)`](/ja/reference/data-types/array) または [`Array(Float*)`](/ja/reference/data-types/array)
**戻り値**
時系列データの周期に相当する実数値を返します。データ点の数が 4 未満の場合は NaN です。[`Float64`](/ja/reference/data-types/float)
**例**
**単純なパターンでの周期検出**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌───────────print_0──────┐
│ 3 │
└────────────────────────┘
```
**複雑なパターンを用いた周期検出**
```sql title=Query theme={null}
SELECT seriesPeriodDetectFFT(arrayMap(x -> abs((x % 6) - 3), range(1000))) AS print_0
```
```response title=Response theme={null}
┌─print_0─┐
│ 6 │
└─────────┘
```
## timeSeriesCopyTag
導入バージョン: v26.1.0
指定したタグを、1 つのタググループ (`src_group`) から別のタググループ (`dest_group`) へコピーします。
この関数は、コピー先の `dest_group` にある同じタグの既存の値を置き換えます。
コピー対象のタグが `src_group` に存在しない場合、この関数は `dest_group` からもそのタグを削除します。
この関数は、Prometheus の
[group left/group right](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) 修飾子のコピーの挙動を模倣します。
**構文**
```sql theme={null}
timeSeriesCopyTag(dest_group, src_group, tag_to_copy)
```
**引数**
* `dest_group` — コピー先のタググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `src_group` — コピー元のタググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `tag_to_copy` — コピーするタグの名前。[`String`](/ja/reference/data-types/string)
**戻り値**
`dest_group` のタグに、`src_group` からコピーしたタグを加えたタググループを返します。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│ 1 │ 2 │ 3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```
## timeSeriesCopyTags
導入バージョン: v26.1.0
指定したタグを、あるタググループ (`src_group`) から別のタググループ (`dest_group`) にコピーします。
この関数は、コピーしたタグについて、`dest_group` 内の既存の値を置き換えます。
コピー対象のタグの一部が `src_group` に存在しない場合、この関数はそれらのタグを `dest_group` からも削除します。
この関数は、Prometheus の
[修飾子](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) のコピー動作を模倣しています。
**構文**
```sql theme={null}
timeSeriesCopyTags(dest_group, src_group, tags_to_copy)
```
**引数**
* `dest_group` — 宛先のタググループです。[`UInt64`](/ja/reference/data-types/int-uint)
* `src_group` — コピー元のタググループです。[`UInt64`](/ja/reference/data-types/int-uint)
* `tags_to_copy` — コピーするタグの名前です。[`Array(String)`](/ja/reference/data-types/array)
**戻り値**
`dest_group` のタグと、`src_group` からコピーされたタグを含むタググループを返します。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│ 1 │ 2 │ 3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```
導入バージョン: v26.1.0
グループから指定したタグの値を抽出します。見つからない場合は NULL を返します。
関連項目: 関数 [timeSeriesGroupToTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags)
**構文**
```sql theme={null}
timeSeriesExtractTag(group)
```
**引数**
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `tag_to_extract` — グループから抽出するタグ名。[`String`](/ja/reference/data-types/string)
**戻り値**
指定したタグの値を返します。[`Nullable(String)`](/ja/reference/data-types/nullable)
**例**
**例**
```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
timeSeriesExtractTag(group, '__name__'),
timeSeriesExtractTag(group, 'env'),
timeSeriesExtractTag(group, 'instance')
```
```response title=Response theme={null}
┌─group─┬─timeSeriesExtractTag(group, '__name__')─┬─timeSeriesExtractTag(group, 'env')─┬─timeSeriesExtractTag(group, 'instance')─┐
│ 1 │ http_requests_count │ dev │ ᴺᵁᴸᴸ │
└───────┴─────────────────────────────────────────┴────────────────────────────────────┴─────────────────────────────────────────┘
```
## timeSeriesFromGrid
導入バージョン: v25.8.0
値の配列 `[x1, x2, x3, ...]` を、タプルの配列
`[(start_timestamp, x1), (start_timestamp + step, x2), (start_timestamp + 2 * step, x3), ...]` に変換します。
現在のタイムスタンプは、`end_timestamp` を超えるまで `step` ずつ増加します。
値の数がタイムスタンプの数と一致しない場合、この関数は例外をスローします。
`[x1, x2, x3, ...]` 内の NULL 値 はスキップされますが、現在のタイムスタンプは引き続き増加します。
たとえば、`[value1, NULL, x2]` に対して、この関数は `[(start_timestamp, x1), (start_timestamp + 2 * step, x2)]` を返します。
**構文**
```sql theme={null}
timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)
```
**引数**
* `start_timestamp` — グリッドの開始時刻。[`DateTime64`](/ja/reference/data-types/datetime64) または [`DateTime`](/ja/reference/data-types/datetime) または [`UInt32`](/ja/reference/data-types/int-uint)
* `end_timestamp` — グリッドの終了時刻。[`DateTime64`](/ja/reference/data-types/datetime64) または [`DateTime`](/ja/reference/data-types/datetime) または [`UInt32`](/ja/reference/data-types/int-uint)
* `step` — 秒単位のグリッド間隔。[`Decimal64`](/ja/reference/data-types/decimal) または [`Decimal32`](/ja/reference/data-types/decimal) または [`UInt32/64`](/ja/reference/data-types/int-uint)
* `values` — 値の配列 [`Array(Float*)`](/ja/reference/data-types/array) または [`Array(Nullable(Float*))`](/ja/reference/data-types/array)
**戻り値**
`start_timestamp` と `step` で定義された一定間隔の時間グリッド上のタイムスタンプと組み合わせたソース配列の値を返します。[`Array(Tuple(DateTime64, Float64))`](/ja/reference/data-types/array)
**例**
**使用例**
```sql title=Query theme={null}
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;
```
```response title=Response theme={null}
┌─────────────────────────────────────────────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)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## timeSeriesGroupToSamplingKey
導入バージョン: v26.4.0
指定したグループのタグから導出される、安定した `UInt64` のサンプリングキーを返します。
この値は決定論的で、入力タグが同一であれば常に同じキーが生成されます。
`limitk` や `limit_ratio` などのサンプリング演算子のソートキーとして使用することを想定しています。
**構文**
```sql theme={null}
timeSeriesGroupToSamplingKey(group)
```
**引数**
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
**戻り値**
グループに関連付けられたタグから算出される、安定した `UInt64` ハッシュ。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
timeSeriesGroupToSamplingKey(group) AS sampling_key
```
```response title=Response theme={null}
┌─group─┬─────────sampling_key─┐
│ 1 │ 12876543210987654321 │
└───────┴──────────────────────┘
```
## timeSeriesGroupToTags
導入バージョン: v26.1.0
指定したグループに関連付けられたタグの名前と値を返します。
関連項目: 関数 [timeSeriesTagsToGroup()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesTagsToGroup)
**構文**
```sql theme={null}
timeSeriesGroupToTags(group)
```
**別名**: `timeSeriesTagsGroupToTags`
**引数**
* `group` — タググループ。 [`UInt64`](/ja/reference/data-types/int-uint)
**戻り値**
`(tag_name, tag_value)` のペアからなる配列を返します。
返される配列は常に `tag_name` でソートされ、同じ `tag_name` を複数回含むことはありません。
[`Array(Tuple(String, String))`](/ja/reference/data-types/array)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─group─┬─sorted_tags────────────────────────────────────────────────────────┬─same_group─┬─throwIf(notE⋯up, group))─┐
│ 1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │ 1 │ 0 │
└───────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────┘
```
## timeSeriesIdToGroup
導入バージョン: v26.1.0
指定した時系列の識別子に関連付けられたタグの名前と値を返します。
関連項目: 関数 [timeSeriesStoreTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags)
**構文**
```sql theme={null}
timeSeriesIdToGroup(id)
```
**別名**: `timeSeriesIdToTagsGroup`
**引数**
* `id` — 時系列の識別子。[`UInt64`](/ja/reference/data-types/int-uint) または [`UInt128`](/ja/reference/data-types/int-uint) または [`UUID`](/ja/reference/data-types/uuid) または [`FixedString(16)`](/ja/reference/data-types/fixedstring)
**戻り値**
時系列の識別子 `id` に関連付けられたタググループを返します。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌────────────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.0
指定した時系列の識別子に関連付けられたタグを返します。
関連項目: 関数 [timeSeriesStoreTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags)
**構文**
```sql theme={null}
timeSeriesIdToTags(id)
```
**引数**
* `id` — 時系列の識別子。[`UInt64`](/ja/reference/data-types/int-uint) または [`UInt128`](/ja/reference/data-types/int-uint) または [`UUID`](/ja/reference/data-types/uuid) または [`FixedString(16)`](/ja/reference/data-types/fixedstring)
**戻り値**
`(tag_name, tag_value)` のペアからなる配列を返します。
返される配列は常に `tag_name` 順にソートされ、同じ `tag_name` を複数回含むことはありません。
[`Array(Tuple(String, String))`](/ja/reference/data-types/array)
**例**
**例**
```sql title=Query theme={null}
SELECT 8374283493092 AS id,
timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
throwIf(same_id != id),
timeSeriesIdToTags(same_id)
```
```response title=Response theme={null}
┌────────────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.0
タググループから抽出した指定のタグの値を結合します。
この関数は、結合した値の間に区切り文字を挿入し、タグ `dest_tag` に結合後の値を設定した新しいタググループを返します。
この関数は、Prometheus の関数
[label\_join()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_join) のロジックを模倣しています。
**構文**
```sql theme={null}
timeSeriesJoinTags(group, dest_tag, separator, src_tags)
```
**引数**
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `dest_tag` — 結合結果を格納し、`group` に追加されるタグの名前。[`String`](/ja/reference/data-types/string)
* `separator` — 結合された値の間に挿入する区切り文字。[`String`](/ja/reference/data-types/string)
* `src_tags` — 結合する値を持つソースタグの名前。[`Array(String)`](/ja/reference/data-types/array)
**戻り値**
結合結果が `dest_tag` タグに設定された新しいタググループを返します。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─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.0
タイムスタンプの範囲 `[start_timestamp, start_timestamp + step, start_timestamp + 2 * step, ..., end_timestamp]` を生成します。
`start_timestamp` と `end_timestamp` が等しい場合、この関数は `[start_timestamp]` を含む 1 要素の配列を返します。
関数 `timeSeriesRange()` は [range](/ja/reference/functions/regular-functions/array-functions#range) 関数に似ています。
**構文**
```sql theme={null}
timeSeriesRange(start_timestamp, end_timestamp, step)
```
**引数**
* `start_timestamp` — 範囲の開始時刻。[`DateTime64`](/ja/reference/data-types/datetime64) または [`DateTime`](/ja/reference/data-types/datetime) または [`UInt32`](/ja/reference/data-types/int-uint)
* `end_timestamp` — 範囲の終了時刻。[`DateTime64`](/ja/reference/data-types/datetime64) または [`DateTime`](/ja/reference/data-types/datetime) または [`UInt32`](/ja/reference/data-types/int-uint)
* `step` — 範囲の間隔 (秒) 。[`UInt32/64`](/ja/reference/data-types/int-uint) または [`Decimal32/64`](/ja/reference/data-types/decimal)
**戻り値**
タイムスタンプの範囲を返します。[`Array(DateTime64)`](/ja/reference/data-types/array)
**例**
**使用例**
```sql title=Query theme={null}
SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30)
```
```response title=Response theme={null}
┌────────────────────────────────────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.0
指定したタグを除くすべてのタグをタググループから削除します。
関連項目: 関数 [timeSeriesRemoveTag()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags)。
**構文**
```sql theme={null}
timeSeriesRemoveAllTagsExcept(group, tags_to_keep)
```
**引数**
* `group` — タググループです。[`UInt64`](/ja/reference/data-types/int-uint)
* `tags_to_keep` — グループ内で保持するタグの名前です。[`Array(String)`](/ja/reference/data-types/array)
**戻り値**
指定したタグのみを保持する新しいタググループです。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
timeSeriesRemoveAllTagsExcept(group, ['env']) AS result_group,
timeSeriesGroupToTags(result_group)
```
```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─┐
│ 1 │ 2 │ [('env','dev')] │
└───────┴──────────────┴─────────────────────────────────────┘
```
## timeSeriesRemoveTag
導入バージョン: v26.1.0
タググループから指定したタグを削除します。
グループ内に該当するタグがない場合は、グループは変更されずにそのまま返されます。
関連項目: 関数 [timeSeriesRemoveTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags)、
[timeSeriesRemoveAllTagsExcept()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept)。
**構文**
```sql theme={null}
timeSeriesRemoveTag(group, tag_to_remove)
```
**引数**
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `tag_to_remove` — グループから削除するタグ名。[`String`](/ja/reference/data-types/string)
**戻り値**
指定したタグを含まない新しいタググループ。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─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.0
タググループから指定したタグを削除します。
指定したタグの一部がタググループに含まれていない場合、関数はそれらを無視します。
関連項目: 関数 [timeSeriesRemoveTag()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveAllTagsExcept()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept)。
**構文**
```sql theme={null}
timeSeriesRemoveTags(group, tags_to_remove)
```
**引数**
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `tags_to_remove` — グループから削除するタグ名。[`Array(String)`](/ja/reference/data-types/array)
**戻り値**
指定したタグを除いた新しいタググループ。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─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.0
タグ `src_tag` の値に対して正規表現 `regex` を照合します。
一致した場合、返されるグループ内のタグ `dest_tag` の値は `replacement` を展開したものとなり、
入力に含まれる元のタグもそのまま保持されます。
この関数は、Prometheus の関数
[label\_replace()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_replace) のロジックを模倣しています。
**構文**
```sql theme={null}
timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)
```
**引数**
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
* `dest_tag` — 結果のタググループを格納する宛先タグの名前。[`String`](/ja/reference/data-types/string)
* `replacement` — 置換パターン。正規表現 'regex' のキャプチャグループを参照するために、$1、$2、または \$name を含めることができます。[`String`](/ja/reference/data-types/string)
* `src_tag` — 値が正規表現 'regex' との照合に使用されるタグの名前。[`String`](/ja/reference/data-types/string)
* `regex` — 正規表現。[`String`](/ja/reference/data-types/string)
**戻り値**
必要に応じて `dest_tag` が追加された新しいタググループ。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('service', 'a:c')]) AS group,
timeSeriesReplaceTag(group, 'foo', '$1', 'service', '(.*):.*') AS result_group,
timeSeriesGroupToTags(result_group)
```
```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────────────────┐
│ 1 │ 2 │ [('__name__','up'),('foo','a'),('job','api-server'),('service','a:c')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘
```
## timeSeriesStoreTags
導入バージョン: v25.8.0
指定した時系列の識別子と、一連のタグとの対応関係をクエリコンテキストに格納します。
この対応関係は、クエリ実行中に関数 [timeSeriesIdToTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesIdToTags)
および [timeSeriesIdToGroup()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesIdToGroup)
を使って後から参照できます。
**構文**
```sql theme={null}
timeSeriesStoreTags(id, tags_array, separate_tag_name_1, separate_tag_value_1, ...)
```
**引数**
* `id` — 時系列の識別子。[`UInt64`](/ja/reference/data-types/int-uint) または [`UInt128`](/ja/reference/data-types/int-uint) または [`UUID`](/ja/reference/data-types/uuid) または [`FixedString(16)`](/ja/reference/data-types/fixedstring)
* `tags_array` — (tag\_name, tag\_value) のペアからなる Array。[`Array(Tuple(String, String))`](/ja/reference/data-types/array) または [`NULL`](/ja/reference/syntax#null)
* `separate_tag_name_i` — タグ名。[`String`](/ja/reference/data-types/string) または [`FixedString`](/ja/reference/data-types/fixedstring)
* `separate_tag_value_i` — タグの値。[`String`](/ja/reference/data-types/string) または [`FixedString`](/ja/reference/data-types/fixedstring) または [`Nullable(String)`](/ja/reference/data-types/nullable)
**戻り値**
時系列の識別子 (つまり最初の引数) を返します。
**例**
**例**
```sql title=Query theme={null}
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))
```
```response title=Response theme={null}
┌────────────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
指定したタグに対応するタググループを返します。
クエリの実行中に同じタググループが複数回見つかった場合、この関数は同じタググループを返します。
タグ集合が空の場合、この関数は常に 0 を返します。
関連項目: 関数 [timeSeriesGroupToTags()](/ja/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags)。
**構文**
```sql theme={null}
timeSeriesTagsToGroup(tags_array, tag_name_1, tag_value_1, tag_name2, tag_value2, ...)
```
**引数**
* `tags_array` — ペア (tag\_name, tag\_value) からなる Array。[`Array(Tuple(String, String))`](/ja/reference/data-types/array) または [`NULL`](/ja/reference/syntax#null)
* `tag_name_i` — タグ名。[`String`](/ja/reference/data-types/string) または [`FixedString`](/ja/reference/data-types/fixedstring)
* `tag_value_i` — タグの値。[`String`](/ja/reference/data-types/string) または [`FixedString`](/ja/reference/data-types/fixedstring) または [`Nullable(String)`](/ja/reference/data-types/nullable)
**戻り値**
指定したタグに対応するタググループを返します。[`UInt64`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─group1─┬─group2─┬─empty_group─┬─same_group2─┬─throwIf(notEquals(same_group2, group2))─┬─timeSeriesGroupToTags(group2)──┐
│ 1 │ 2 │ 0 │ 2 │ 0 │ [('__name__','http_failures')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘
```
## timeSeriesThrowDuplicateSeriesIf
導入バージョン: v26.2.0
`condition` をチェックし、それが `true` の場合は、次のメッセージを含む例外をスローします。
`Multiple series have the same tags , duplicate series in the same result set are not allowed`
`condition` が `false` の場合、この関数は `0` を返します。
この関数は [throwIf()](/ja/reference/functions/regular-functions/other-functions#throwIf) に似ていますが、
使用するエラーコードが異なり、エラーメッセージのフォーマットも異なります。
**構文**
```sql theme={null}
timeSeriesThrowDuplicateSeriesIf(condition, group)
```
**引数**
* `condition` — 確認対象の条件。通常は関数 [count()](/ja/reference/functions/aggregate-functions/count#count) [`UInt8`](/ja/reference/data-types/int-uint) を含みます
* `group` — タググループ。[`UInt64`](/ja/reference/data-types/int-uint)
**戻り値**
`0` を返します。[`UInt8`](/ja/reference/data-types/int-uint)
**例**
**例**
```sql title=Query theme={null}
CREATE TABLE test(tags Array(Tuple(String, String))) engine=Memory;
INSERT INTO test VALUES ([('__name__', 'up')]);
SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0; -- OK
INSERT INTO test VALUES ([('__name__', 'up')]);
SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0; -- 例外をスロー "Multiple series have the same tags {'__name__': 'up'}"
```
```response title=Response theme={null}
```