> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 各グリッドステップで、値が大きい上位 k 個の時系列を選択します。
# timeSeriesTopKMasks
timeSeriesTopKMasks
導入バージョン: v26.8.0
時間グリッドの各タイムステップにおいて、値が大きい上位 k 個の時系列を選択します。
各入力行は 1 つの時系列を表します。`key` は系列を識別し、`values` には共通の
時間グリッドに揃えられた値が格納されます。そのため、すべての行の `values` 配列は同じサイズでなければなりません。各タイムステップでは、そのステップにおける
非 NULL 値が大きい上位 k 個の系列が選択されます (NaN は他のどの値よりも小さいとみなされます) 。値が同じ場合は、
`key` が小さい系列が優先されます。
この関数は PromQL の `topk()` 集約オペレーターを実装したもので、タイムステップごとにサイズ `k` の上限付きヒープを 1 つだけ保持します。
そのため、ステートのサイズは集計対象の系列数に依存しません。
この関数はプライベートプレビュー段階です。有効にするには `enable_time_series_aggregate_functions = 1` を設定してください。
**構文**
```sql theme={null}
timeSeriesTopKMasks(k, key, values)
```
**引数**
* `k` — 各時間ステップで選択する系列の数。全時間ステップ共通の単一の値か、時間ステップごとに 1 つずつ値を持つ配列のいずれかを指定します。すべての行で同じ値である必要があります。[`UInt*`](/ja/reference/data-types/int-uint) または [`Array(UInt*)`](/ja/reference/data-types/array)
* `key` — 時系列の識別子。[`UInt64`](/ja/reference/data-types/int-uint)
* `values` — 時間グリッドに揃えた時系列の値。時間ステップごとに 1 つの要素を持ちます。[`Array(Nullable(Float32))`](/ja/reference/data-types/array) または [`Array(Nullable(Float64))`](/ja/reference/data-types/array) または [`Array(Float32)`](/ja/reference/data-types/array) または [`Array(Float64)`](/ja/reference/data-types/array)
**戻り値**
選択された系列を `key` の昇順で、それぞれのステップごとのマスクとともに返します。時間ステップ `t` でその系列が選択された場合、`steps_mask[t] = 1` となります。どの時間ステップでも選択されなかった系列は返されません。[`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/ja/reference/data-types/array)
**例**
**時間ステップごとに値が最大の 2 系列を選択する**
```sql title=Query theme={null}
SET enable_time_series_aggregate_functions = 1;
WITH [(1, [10., 1., NULL]), (2, [20., 2., 2.]), (3, [30., NULL, 1.])]::Array(Tuple(UInt64, Array(Nullable(Float64)))) AS series
SELECT timeSeriesTopKMasks(2, s.1, s.2)
FROM (SELECT arrayJoin(series) AS s);
```
```response title=Response theme={null}
[(1,[0,1,0]),(2,[1,1,1]),(3,[1,0,1])]
```