> ## 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` во всех строках должны иметь одинаковый размер. На каждом шаге выбираются серии с k наибольшими
значениями, отличными от NULL (NaN считается меньше любого другого значения). При равенстве значений
предпочтение отдаётся серии с меньшим `key`.

Эта функция реализует оператор агрегации `topk()` языка PromQL и хранит лишь одну ограниченную кучу размера `k` для каждого
шага, поэтому размер её состояния не зависит от количества агрегируемых серий.

<Note>
  Эта функция находится в закрытой предварительной версии. Чтобы включить её, установите настройку `enable_time_series_aggregate_functions = 1`.
</Note>

**Синтаксис**

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

**Аргументы**

* `k` — Количество серий, выбираемых на каждом временном шаге: либо одно значение для всех шагов, либо массив с отдельным значением для каждого шага. Должно быть одинаковым для всех строк. [`UInt*`](/ru/reference/data-types/int-uint) или [`Array(UInt*)`](/ru/reference/data-types/array)
* `key` — Идентификатор временной серии. [`UInt64`](/ru/reference/data-types/int-uint)
* `values` — Значения временной серии, выровненные по временной сетке, — по одному элементу на каждый временной шаг. [`Array(Nullable(Float32))`](/ru/reference/data-types/array) или [`Array(Nullable(Float64))`](/ru/reference/data-types/array) или [`Array(Float32)`](/ru/reference/data-types/array) или [`Array(Float64)`](/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает выбранные серии в порядке возрастания `key`, каждую — вместе с её маской по шагам: `steps_mask[t] = 1`, если серия выбрана на временном шаге `t`. Серии, не выбранные ни на одном временном шаге, не возвращаются. [`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/ru/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])]
```