> ## 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개의 시계열을 선택합니다.

# timeSeriesLimitKMasks

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

도입 버전: v26.8.0

시간 그리드의 각 시간 간격마다 결정론적 의사 난수 방식으로 최대 k개의 시계열을 선택합니다.

각 입력 행은 하나의 시계열을 나타냅니다. `key`는 시계열을 식별하고, `sampling_key`는 선택 순서로 사용되는 시계열별 해시이며, `values`에는 공통 시간 그리드에 맞춰 정렬된 시계열 값이 담깁니다(따라서 모든 행의 `values` 배열은
크기가 같아야 합니다). 각 시간 간격에서는 해당 간격에 NULL이 아닌 값이 있는 시계열 중 샘플링 키가 가장 작은 k개의 시계열이
선택됩니다. 샘플링 키가 같으면 `key`가 더 작은 시계열이 우선 선택됩니다.

이 함수는 PromQL의 `limitk()` 집계 연산자를 구현하며, 시간 간격마다 크기가 `k`로 제한된 힙을 하나만 유지하므로
상태 크기가 집계되는 시계열의 수와 무관합니다.

<Note>
  이 함수는 비공개 프리뷰 단계입니다. `enable_time_series_aggregate_functions = 1`로 설정하여 활성화하세요.
</Note>

**구문**

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

**인수**

* `k` — 각 시간 간격마다 선택할 시계열의 개수입니다. 모든 시간 간격에 동일하게 적용되는 단일 값 또는 시간 간격마다 하나의 값을 갖는 배열로 지정합니다. 모든 행에서 동일해야 합니다. [`UInt*`](/ko/reference/data-types/int-uint) 또는 [`Array(UInt*)`](/ko/reference/data-types/array)
* `key` — 시계열의 식별자입니다. [`UInt64`](/ko/reference/data-types/int-uint)
* `sampling_key` — 선택 순서를 결정하는 시계열별 해시입니다(예: `timeSeriesGroupToSamplingKey(key)`). [`UInt64`](/ko/reference/data-types/int-uint)
* `values` — 시간 그리드에 맞춰 정렬된 시계열 값으로, 시간 간격마다 하나의 원소를 가집니다. [`Array(Nullable(Float32))`](/ko/reference/data-types/array) 또는 [`Array(Nullable(Float64))`](/ko/reference/data-types/array) 또는 [`Array(Float32)`](/ko/reference/data-types/array) 또는 [`Array(Float64)`](/ko/reference/data-types/array)

**반환 값**

선택된 시계열을 `key` 오름차순으로 반환하며, 각 시계열에는 간격별 마스크가 함께 포함됩니다. 시계열이 시간 간격 `t`에서 선택되면 `steps_mask[t] = 1`입니다. 어떤 시간 간격에서도 선택되지 않은 시계열은 반환되지 않습니다. [`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/ko/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])]
```