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

> Seleciona até k séries temporais em cada passo da grade usando uma ordenação pseudoaleatória determinística.

# timeSeriesLimitKMasks

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

Introduzido em: v26.8.0

Seleciona até k séries temporais em cada passo de uma grade temporal, de forma pseudoaleatória e determinística.

Cada linha de entrada corresponde a uma série temporal: `key` identifica a série, `sampling_key` é um hash por série usado como
ordem de seleção e `values` contém os valores da série alinhados a uma grade temporal comum (portanto, os arrays `values`
de todas as linhas devem ter o mesmo tamanho). Em cada passo de tempo, são selecionadas as séries com as k menores chaves de amostragem dentre aquelas
com valores não NULL naquele passo. Empates entre chaves de amostragem são resolvidos dando preferência à série com o menor `key`.

Esta função implementa o operador de agregação `limitk()` do PromQL e mantém apenas um heap limitado de tamanho `k` por
passo de tempo, de modo que o tamanho do seu estado não depende do número de séries agregadas.

<Note>
  Esta função está em prévia privada; para habilitá-la, defina `enable_time_series_aggregate_functions = 1`.
</Note>

**Sintaxe**

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

**Argumentos**

* `k` — Quantas séries selecionar em cada passo de tempo: um único valor para todos os passos de tempo ou um array com um valor por passo de tempo. Deve ser o mesmo para todas as linhas. [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Array(UInt*)`](/pt-BR/reference/data-types/array)
* `key` — Identificador da série temporal. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `sampling_key` — Um hash por série que define a ordem de seleção, por exemplo, `timeSeriesGroupToSamplingKey(key)`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `values` — Valores da série temporal alinhados à grade temporal, um elemento por passo de tempo. [`Array(Nullable(Float32))`](/pt-BR/reference/data-types/array) ou [`Array(Nullable(Float64))`](/pt-BR/reference/data-types/array) ou [`Array(Float32)`](/pt-BR/reference/data-types/array) ou [`Array(Float64)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Retorna as séries selecionadas em ordem crescente de `key`, cada uma acompanhada de sua máscara por passo: `steps_mask[t] = 1` se a série for selecionada no passo de tempo `t`. Séries que não forem selecionadas em nenhum passo de tempo não são retornadas. [`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/pt-BR/reference/data-types/array)

**Exemplos**

**Seleção de 2 séries por passo de tempo com base nas menores chaves de amostragem**

```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])]
```