> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Выбирает не более k временных серий на каждом шаге сетки в детерминированном псевдослучайном порядке.

# timeSeriesLimitKMasks

<h2 id="timeSeriesLimitKMasks">
  timeSeriesLimitKMasks
</h2>

Добавлено в: v26.8.0

Выбирает до k временных серий на каждом шаге временной сетки детерминированным псевдослучайным образом.

Каждая входная строка соответствует одной временной серии: `key` идентифицирует серию, `sampling_key` — хеш серии, задающий
порядок выбора, а `values` содержит значения серии, выровненные по общей временной сетке (поэтому массивы `values`
во всех строках должны иметь одинаковый размер). На каждом шаге выбираются k серий с наименьшими ключами выборки среди тех,
у которых на этом шаге есть значения, отличные от NULL. При равенстве ключей выборки предпочтение отдаётся серии с меньшим `key`.

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

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

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

```sql theme={null}
timeSeriesLimitKMasks(k, key, sampling_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)
* `sampling_key` — Хеш, вычисляемый для каждой серии и определяющий порядок выбора, например `timeSeriesGroupToSamplingKey(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], 300), (2, [20., 2., 2.], 100), (3, [30., NULL, 1.], 200)]::Array(Tuple(UInt64, Array(Nullable(Float64)), UInt64)) AS series
SELECT timeSeriesLimitKMasks(2, s.1, s.3, 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])]
```