> ## 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 قيمة عند كل خطوة من خطوات الشبكة الزمنية.

# timeSeriesTopKMasks

<h2 id="timeSeriesTopKMasks">
  timeSeriesTopKMasks
</h2>

أُضيف في: v26.8.0

يختار السلاسل الزمنية ذات القيم الـ k الأكبر عند كل خطوة زمنية من شبكة زمنية.

يمثّل كل صف إدخال سلسلة زمنية واحدة: يحدّد `key` السلسلة، بينما يحتوي `values` على قيمها مُحاذاةً لشبكة
زمنية مشتركة، ولذلك يجب أن تكون مصفوفات `values` في جميع الصفوف بالحجم نفسه. عند كل خطوة زمنية، تُختار السلاسل التي تملك أكبر k
من القيم غير الفارغة (غير NULL) عند تلك الخطوة (تُعدّ NaN أصغر من أي قيمة أخرى). وعند تساوي القيم، تُفضَّل
السلسلة ذات `key` الأصغر.

تنفّذ هذه الدالة مشغّل التجميع `topk()` في PromQL، ولا تحتفظ إلا بكومة محدودة واحدة بحجم `k` لكل
خطوة زمنية، ولذلك لا يتوقف حجم حالتها على عدد السلاسل المجمّعة.

<Note>
  هذه الدالة في مرحلة المعاينة الخاصة، ويمكن تفعيلها بضبط `enable_time_series_aggregate_functions = 1`.
</Note>

**الصيغة**

```sql theme={null}
timeSeriesTopKMasks(k, 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)
* `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]), (2, [20., 2., 2.]), (3, [30., NULL, 1.])]::Array(Tuple(UInt64, Array(Nullable(Float64)))) AS series
SELECT timeSeriesTopKMasks(2, s.1, 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])]
```