> ## 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

<h2 id="timeSeriesTopKMasks">
  timeSeriesTopKMasks
</h2>

引入版本：v26.8.0

在时间网格的每个时间步上，选出取值最大的 k 个时间序列。

每个输入行代表一个时间序列：`key` 用于标识该序列，`values` 包含该序列按公共时间网格对齐的取值，因此所有行的 `values` 数组长度必须相同。在每个时间步上，选出该时间步中非 NULL 值最大的 k 个序列 (非数字 (NaN) 被视为小于任何其他值) 。若取值相同，则优先选择 `key` 较小的序列。

该函数实现了 PromQL 的 `topk()` 聚合运算符，每个时间步仅维护一个大小为 `k` 的有界堆，因此其状态大小与参与聚合的序列数量无关。

<Note>
  该函数目前处于私有预览阶段，可通过设置 `enable_time_series_aggregate_functions = 1` 启用。
</Note>

**语法**

```sql theme={null}
timeSeriesTopKMasks(k, key, values)
```

**参数**

* `k` — 每个时间步要选取的序列数量，可以是适用于所有时间步的单个值，也可以是为每个时间步分别指定一个值的数组。所有行中的该值必须相同。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Array(UInt*)`](/zh/reference/data-types/array)
* `key` — 时间序列的标识符。[`UInt64`](/zh/reference/data-types/int-uint)
* `values` — 与时间网格对齐的时间序列值，每个时间步对应一个元素。[`Array(Nullable(Float32))`](/zh/reference/data-types/array) 或 [`Array(Nullable(Float64))`](/zh/reference/data-types/array) 或 [`Array(Float32)`](/zh/reference/data-types/array) 或 [`Array(Float64)`](/zh/reference/data-types/array)

**返回值**

按 `key` 升序返回被选中的序列，每个序列附带其按时间步划分的掩码：若该序列在时间步 `t` 被选中，则 `steps_mask[t] = 1`。在所有时间步均未被选中的序列不会返回。[`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/zh/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])]
```