> ## 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 个时间序列。

# timeSeriesBottomKMasks

<h2 id="timeSeriesBottomKMasks">
  timeSeriesBottomKMasks
</h2>

引入版本：v26.8.0

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

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

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

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

**语法**

```sql theme={null}
timeSeriesBottomKMasks(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 timeSeriesBottomKMasks(2, s.1, s.2)
FROM (SELECT arrayJoin(series) AS s);
```

```response title=Response theme={null}
[(1,[1,1,0]),(2,[1,1,1]),(3,[0,0,1])]
```