> ## 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`
في جميع الصفوف بالحجم نفسه). عند كل خطوة زمنية، تُختار السلاسل التي تملك أصغر 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*`](/ar/reference/data-types/int-uint) أو [`Array(UInt*)`](/ar/reference/data-types/array)
* `key` — معرّف السلسلة الزمنية. [`UInt64`](/ar/reference/data-types/int-uint)
* `sampling_key` — قيمة تجزئة لكل سلسلة تحدد ترتيب الاختيار، مثل `timeSeriesGroupToSamplingKey(key)`. [`UInt64`](/ar/reference/data-types/int-uint)
* `values` — قيم السلسلة الزمنية مُحاذاةً مع الشبكة الزمنية، بواقع عنصر واحد لكل خطوة زمنية. [`Array(Nullable(Float32))`](/ar/reference/data-types/array) أو [`Array(Nullable(Float64))`](/ar/reference/data-types/array) أو [`Array(Float32)`](/ar/reference/data-types/array) أو [`Array(Float64)`](/ar/reference/data-types/array)

**القيمة المعادة**

تُعيد السلاسل المختارة مرتبةً تصاعديًا حسب `key`، مع قناع الخطوات الخاص بكل منها: `steps_mask[t] = 1` إذا اختيرت السلسلة عند الخطوة الزمنية `t`. أما السلاسل التي لم تُختر عند أي خطوة زمنية فلا تُعاد. [`Array(Tuple(key UInt64, steps_mask Array(UInt8)))`](/ar/reference/data-types/array)

**أمثلة**

**اختيار سلسلتين لكل خطوة زمنية وفق أصغر مفاتيح أخذ العينات**

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