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

> Sélectionne jusqu'à k séries temporelles à chaque pas de la grille selon un ordre pseudo-aléatoire déterministe.

# timeSeriesLimitKMasks

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

Introduit dans : v26.8.0

Sélectionne jusqu'à k séries temporelles à chaque pas d'une grille temporelle, de manière pseudo-aléatoire et déterministe.

Chaque ligne d'entrée correspond à une série temporelle : `key` identifie la série, `sampling_key` est un hachage propre à chaque série qui détermine
l'ordre de sélection, et `values` contient les valeurs de la série alignées sur une grille temporelle commune (les tableaux `values`
de toutes les lignes doivent donc être de même taille). À chaque pas de temps, parmi les séries qui ont des valeurs non NULL à ce pas, celles
dont les clés d'échantillonnage sont les k plus petites sont sélectionnées. En cas d'égalité des clés d'échantillonnage, la série dont la `key` est la plus petite est retenue en priorité.

Cette fonction implémente l'opérateur d'agrégation `limitk()` de PromQL et ne conserve qu'un seul tas borné de taille `k` par
pas de temps ; la taille de son état est donc indépendante du nombre de séries agrégées.

<Note>
  Cette fonction est en aperçu privé ; pour l'activer, définissez le paramètre `enable_time_series_aggregate_functions = 1`.
</Note>

**Syntaxe**

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

**Arguments**

* `k` — Nombre de séries à sélectionner à chaque pas de temps : soit une valeur unique pour tous les pas de temps, soit un tableau contenant une valeur par pas de temps. Doit être identique pour toutes les lignes. [`UInt*`](/fr/reference/data-types/int-uint) ou [`Array(UInt*)`](/fr/reference/data-types/array)
* `key` — Identifiant de la série temporelle. [`UInt64`](/fr/reference/data-types/int-uint)
* `sampling_key` — Hachage propre à chaque série, qui définit l'ordre de sélection, par exemple `timeSeriesGroupToSamplingKey(key)`. [`UInt64`](/fr/reference/data-types/int-uint)
* `values` — Valeurs de la série temporelle alignées sur la grille temporelle, à raison d'un élément par pas de temps. [`Array(Nullable(Float32))`](/fr/reference/data-types/array) ou [`Array(Nullable(Float64))`](/fr/reference/data-types/array) ou [`Array(Float32)`](/fr/reference/data-types/array) ou [`Array(Float64)`](/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie les séries sélectionnées, triées par ordre croissant de `key`, chacune accompagnée de son masque par pas de temps : `steps_mask[t] = 1` si la série est sélectionnée au pas de temps `t`. Les séries qui ne sont sélectionnées à aucun pas de temps ne sont pas renvoyées. [`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/fr/reference/data-types/array)

**Exemples**

**Sélection de 2 séries par pas de temps selon les plus petites clés d'échantillonnage**

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