> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> توثيق الدوال الخاصة بالعمل مع السلاسل الزمنية

# دوال للعمل مع السلاسل الزمنية

الدوال أدناه مُصمَّمة للاستخدام مع دوال التجميع `timeSeries*()` مثل
[`timeSeriesInstantRateToGrid`](/ar/reference/functions/aggregate-functions/timeSeriesInstantRateToGrid),
[`timeSeriesLastToGrid`](/ar/reference/functions/aggregate-functions/timeSeriesResampleToGridWithStaleness),
وغيرها.

{/*AUTOGENERATED_START*/}

<div id="seriesDecomposeSTL">
  ## seriesDecomposeSTL
</div>

استُحدث في: v24.1.0

يفكّك بيانات السلاسل الزمنية باستخدام STL [(إجراء تفكيك الاتجاه الموسمي المعتمد على Loess)](https://www.wessa.net/download/stl.pdf) إلى مكوّن موسمي واتجاه ومكوّن متبقٍّ.

**البنية**

```sql theme={null}
seriesDecomposeSTL(series, period)
```

**المعاملات**

* `series` — مصفوفة من القيم الرقمية [`Array((U)Int8/16/32/64)`](/ar/reference/data-types/array) أو [`Array(Float*)`](/ar/reference/data-types/array)
* `period` — عدد صحيح موجب [`UInt8/16/32/64`](/ar/reference/data-types/int-uint)

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

تُرجع مصفوفة تتكوّن من أربع مصفوفات، حيث تحتوي المصفوفة الأولى على المكوّنات الموسمية، والثانية على الاتجاه، والثالثة على المكوّن المتبقي، والرابعة على مكوّن خط الأساس (الموسمي + الاتجاه). [`Array(Array(Float32), Array(Float32), Array(Float32), Array(Float32))`](/ar/reference/data-types/array)

**أمثلة**

**تفكيك بيانات السلاسل الزمنية باستخدام STL**

```sql title=Query theme={null}
SELECT seriesDecomposeSTL([10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34], 3) AS print_0
```

```response title=Response theme={null}
┌───────────print_0──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [[
        -13.529999, -3.1799996, 16.71,      -13.53,     -3.1799996, 16.71,      -13.53,     -3.1799996,
        16.71,      -13.530001, -3.18,      16.710001,  -13.530001, -3.1800003, 16.710001,  -13.530001,
        -3.1800003, 16.710001,  -13.530001, -3.1799994, 16.71,      -13.529999, -3.1799994, 16.709997
    ],
    [
        23.63,     23.63,     23.630003, 23.630001, 23.630001, 23.630001, 23.630001, 23.630001,
        23.630001, 23.630001, 23.630001, 23.63,     23.630001, 23.630001, 23.63,     23.630001,
        23.630001, 23.63,     23.630001, 23.630001, 23.630001, 23.630001, 23.630001, 23.630003
    ],
    [
        0, 0.0000019073486, -0.0000019073486, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.0000019073486, 0,
        0
    ],
    [
        10.1, 20.449999, 40.340004, 10.100001, 20.45, 40.34, 10.100001, 20.45, 40.34, 10.1, 20.45, 40.34,
        10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.100002, 20.45, 40.34
    ]]                                                                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="seriesOutliersDetectTukey">
  ## seriesOutliersDetectTukey
</div>

أُضيفت في: v24.2.0

تكتشف القيم الشاذة في بيانات السلاسل الزمنية باستخدام [Tukey Fences](https://en.wikipedia.org/wiki/Outlier#Tukey%27s_fences).

**الصيغة**

```sql theme={null}
seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])
```

**المعاملات**

* `series` — مصفوفة من القيم الرقمية. [`Array((UInt8/16/32/64))`](/ar/reference/data-types/array) أو [`Array(Float*)`](/ar/reference/data-types/array)
* `min_percentile` — اختياري. الحد الأدنى للمئين المُستخدَم لحساب المدى بين الربيعين [(IQR)](https://en.wikipedia.org/wiki/Interquartile_range). يجب أن تكون القيمة ضمن النطاق \[0.02,0.98]. القيمة الافتراضية هي 0.25. [`Float*`](/ar/reference/data-types/float)
* `max_percentile` — اختياري. الحد الأقصى للمئين المُستخدَم لحساب المدى بين الربيعين (IQR). يجب أن تكون القيمة ضمن النطاق \[0.02,0.98]. القيمة الافتراضية هي 0.75. [`Float*`](/ar/reference/data-types/float)
* `K` — اختياري. قيمة ثابتة غير سالبة لاكتشاف القيم الشاذة الطفيفة أو الأشد. القيمة الافتراضية هي 1.5. [`Float*`](/ar/reference/data-types/float)

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

تعيد مصفوفة بالطول نفسه لمصفوفة الإدخال، بحيث تمثل كل قيمة درجة لاحتمال وجود شذوذ في العنصر المقابل في السلسلة. وتشير الدرجة غير الصفرية إلى شذوذ محتمل. [`Array(Float32)`](/ar/reference/data-types/array)

**أمثلة**

**الاكتشاف الأساسي للقيم الشاذة**

```sql title=Query theme={null}
SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4, 5, 12, 45, 12, 3, 3, 4, 5, 6]) AS print_0
```

```response title=Response theme={null}
┌───────────print_0─────────────────┐
│[0,0,0,0,0,0,0,0,0,27,0,0,0,0,0,0] │
└───────────────────────────────────┘
```

**اكتشاف القيم الشاذة بمعلمات مخصصة**

```sql title=Query theme={null}
SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4.50, 5, 12, 45, 12, 3.40, 3, 4, 5, 6], 0.2, 0.8, 1.5) AS print_0
```

```response title=Response theme={null}
┌─print_0──────────────────────────────┐
│ [0,0,0,0,0,0,0,0,0,19.5,0,0,0,0,0,0] │
└──────────────────────────────────────┘
```

<div id="seriesPeriodDetectFFT">
  ## seriesPeriodDetectFFT
</div>

أُضيف في: v23.12.0

يحدّد فترة بيانات السلاسل الزمنية المعطاة باستخدام FFT - [تحويل فورييه السريع](https://en.wikipedia.org/wiki/Fast_Fourier_transform)

**الصيغة**

```sql theme={null}
seriesPeriodDetectFFT(series)
```

**الوسائط**

* `series` — مصفوفة من القيم العددية. [`Array((U)Int8/16/32/64)`](/ar/reference/data-types/array) أو [`Array(Float*)`](/ar/reference/data-types/array)

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

تُرجِع قيمة حقيقية تساوي فترة بيانات السلاسل الزمنية `series`. وتكون NaN عندما يكون عدد نقاط البيانات أقل من أربع. [`Float64`](/ar/reference/data-types/float)

**أمثلة**

**اكتشاف الفترة باستخدام نمط بسيط**

```sql title=Query theme={null}
SELECT seriesPeriodDetectFFT([1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6]) AS print_0
```

```response title=Response theme={null}
┌───────────print_0──────┐
│                      3 │
└────────────────────────┘
```

**اكتشاف الدورية باستخدام نمط معقّد**

```sql title=Query theme={null}
SELECT seriesPeriodDetectFFT(arrayMap(x -> abs((x % 6) - 3), range(1000))) AS print_0
```

```response title=Response theme={null}
┌─print_0─┐
│       6 │
└─────────┘
```

<div id="timeSeriesCopyTag">
  ## timeSeriesCopyTag
</div>

أُضيفت في: v26.1.0

تنسخ وسمًا محددًا من مجموعة وسوم (`src_group`) إلى مجموعة أخرى (`dest_group`).
وتستبدل الدالة أي قيم سابقة للوسم المنسوخ في `dest_group`.
إذا لم يكن الوسم المنسوخ موجودًا في `src_group`، فستزيله الدالة من `dest_group` أيضًا.
وتحاكي الدالة منطق النسخ في مُعدِّلات Prometheus
[group left/group right](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers).

**الصيغة**

```sql theme={null}
timeSeriesCopyTag(dest_group, src_group, tag_to_copy)
```

**الوسيطات**

* `dest_group` — مجموعة الوسوم الوجهة. [`UInt64`](/ar/reference/data-types/int-uint)
* `src_group` — مجموعة الوسوم المصدر. [`UInt64`](/ar/reference/data-types/int-uint)
* `tag_to_copy` — اسم الوسم المراد نسخه. [`String`](/ar/reference/data-types/string)

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

تعيد مجموعة وسوم تتضمن الوسوم من `dest_group` بالإضافة إلى الوسوم المنسوخة من `src_group`. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS dest_group,
       timeSeriesTagsToGroup([('code', '404'), ('message', 'Page not found')], '__name__', 'http_codes') AS src_group,
       timeSeriesCopyTag(dest_group, src_group, '__name__') AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesCopyTags">
  ## timeSeriesCopyTags
</div>

أُضيف في: v26.1.0

ينسخ الوسوم المحددة من مجموعة وسوم (`src_group`) إلى مجموعة أخرى (`dest_group`).
تستبدل الدالة أي قيم سابقة للوسوم المنسوخة في `dest_group`.
إذا كان بعض الوسوم المنسوخة غير موجود في `src_group`، فستحذفه الدالة من `dest_group` أيضًا.
تحاكي الدالة منطق النسخ في مُعدِّلات prometheus
[group left/group right](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers).

**الصيغة**

```sql theme={null}
timeSeriesCopyTags(dest_group, src_group, tags_to_copy)
```

**المعاملات**

* `dest_group` — مجموعة الوسوم الوجهة. [`UInt64`](/ar/reference/data-types/int-uint)
* `src_group` — مجموعة الوسوم المصدر. [`UInt64`](/ar/reference/data-types/int-uint)
* `tags_to_copy` — أسماء الوسوم المراد نسخها. [`Array(String)`](/ar/reference/data-types/array)

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

تُعيد مجموعة وسوم تتضمن الوسوم من `dest_group` بالإضافة إلى الوسوم المنسوخة من `src_group`. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS dest_group,
       timeSeriesTagsToGroup([('code', '404'), ('message', 'Page not found')], '__name__', 'http_codes') AS src_group,
       timeSeriesCopyTags(dest_group, src_group, ['__name__', 'code', 'env']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesExtractTag">
  ## timeSeriesExtractTag
</div>

قُدِّمت في: v26.1.0

تستخرج قيمة وسم محدد من المجموعة. وتُرجِع NULL إذا لم تعثر عليه.
انظر أيضًا الدالة [timeSeriesGroupToTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags).

**البنية**

```sql theme={null}
timeSeriesExtractTag(group)
```

**الوسيطات**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)
* `tag_to_extract` — اسم الوسم المراد استخراجه من المجموعة [`String`](/ar/reference/data-types/string)

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

تُرجِع قيمة وسم محدد. [`Nullable(String)`](/ar/reference/data-types/nullable)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesExtractTag(group, '__name__'),
       timeSeriesExtractTag(group, 'env'),
       timeSeriesExtractTag(group, 'instance')
```

```response title=Response theme={null}
┌─group─┬─timeSeriesExtractTag(group, '__name__')─┬─timeSeriesExtractTag(group, 'env')─┬─timeSeriesExtractTag(group, 'instance')─┐
│     1 │ http_requests_count                     │ dev                                │ ᴺᵁᴸᴸ                                    │
└───────┴─────────────────────────────────────────┴────────────────────────────────────┴─────────────────────────────────────────┘
```

<div id="timeSeriesFromGrid">
  ## timeSeriesFromGrid
</div>

أُضيف في: v25.8.0

يحوّل مصفوفة من القيم `[x1, x2, x3, ...]` إلى مصفوفة من Tuples
`[(start_timestamp, x1), (start_timestamp + step, x2), (start_timestamp + 2 * step, x3), ...]`.

يُزاد الطابع الزمني الحالي بمقدار `step` حتى يصبح أكبر من `end_timestamp`
إذا لم يتطابق عدد القيم مع عدد الطوابع الزمنية، فإن الدالة تُطلق استثناءً.

يتم تخطي قيم NULL في `[x1, x2, x3, ...]`، ولكن يستمر مع ذلك زيادة الطابع الزمني الحالي.
على سبيل المثال، بالنسبة إلى `[value1, NULL, x2]` تُرجع الدالة `[(start_timestamp, x1), (start_timestamp + 2 * step, x2)]`.

**البنية**

```sql theme={null}
timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)
```

**الوسيطات**

* `start_timestamp` — بداية الشبكة. [`DateTime64`](/ar/reference/data-types/datetime64) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`UInt32`](/ar/reference/data-types/int-uint)
* `end_timestamp` — نهاية الشبكة. [`DateTime64`](/ar/reference/data-types/datetime64) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`UInt32`](/ar/reference/data-types/int-uint)
* `step` — خطوة الشبكة بالثواني [`Decimal64`](/ar/reference/data-types/decimal) أو [`Decimal32`](/ar/reference/data-types/decimal) أو [`UInt32/64`](/ar/reference/data-types/int-uint)
* `values` — مصفوفة من القيم [`Array(Float*)`](/ar/reference/data-types/array) أو [`Array(Nullable(Float*))`](/ar/reference/data-types/array)

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

تعيد قيماً من مصفوفة القيم المصدر، مدمجة مع الطوابع الزمنية على شبكة زمنية منتظمة يحددها `start_timestamp` و`step`. [`Array(Tuple(DateTime64, Float64))`](/ar/reference/data-types/array)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT timeSeriesFromGrid('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:30.000'::DateTime64(3), 30, [10, 20, NULL, 30]) AS result;
```

```response title=Response theme={null}
┌─────────────────────────────────────────────result─────────────────────────────────────────────┐
│ [('2025-06-01 00:00:00.000',10),('2025-06-01 00:00:30.000',20),('2025-06-01 00:01:30.000',30)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesGroupToSamplingKey">
  ## timeSeriesGroupToSamplingKey
</div>

تم تقديمه في: v26.4.0

يعيد مفتاح أخذ عينات `UInt64` ثابتًا مشتقًا من وسوم مجموعة محددة.

القيمة حتمية: فالوسوم المدخلة المتطابقة تُنتج دائمًا المفتاح نفسه.
وهو مخصّص ليكون مفتاح ترتيب لعمليات أخذ العينات مثل `limitk` و`limit_ratio`.

**الصياغة**

```sql theme={null}
timeSeriesGroupToSamplingKey(group)
```

**الوسائط**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)

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

قيمة تجزئة `UInt64` ثابتة مشتقة من الوسوم المرتبطة بالمجموعة. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToSamplingKey(group) AS sampling_key
```

```response title=Response theme={null}
┌─group─┬─────────sampling_key─┐
│     1 │ 12876543210987654321 │
└───────┴──────────────────────┘
```

<div id="timeSeriesGroupToTags">
  ## timeSeriesGroupToTags
</div>

أُضيفت في: v26.1.0

تعيد أسماء الوسوم وقيمها المرتبطة بمجموعة محددة.
راجع أيضًا الدالة [timeSeriesTagsToGroup()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesTagsToGroup).

**البنية**

```sql theme={null}
timeSeriesGroupToTags(group)
```

**الأسماء البديلة**: `timeSeriesTagsGroupToTags`

**الوسيطات**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)

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

تُرجع مصفوفة من الأزواج `(tag_name, tag_value)`.
تكون المصفوفة المُعادة مرتبة دائمًا حسب `tag_name`، ولا تتضمن أبدًا `tag_name` نفسه أكثر من مرة.
[`Array(Tuple(String, String))`](/ar/reference/data-types/array)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToTags(group) AS sorted_tags,
       timeSeriesTagsToGroup(sorted_tags) AS same_group,
       throwIf(same_group != group)
```

```response title=Response theme={null}
┌─group─┬─sorted_tags────────────────────────────────────────────────────────┬─same_group─┬─throwIf(notE⋯up, group))─┐
│     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │          1 │                        0 │
└───────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────┘
```

<div id="timeSeriesIdToGroup">
  ## timeSeriesIdToGroup
</div>

قُدِّمت في: v26.1.0

تعيد أسماء الوسوم وقيمها المرتبطة بمُعرّف محدد لسلسلة زمنية.
انظر أيضًا الدالة [timeSeriesStoreTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags).

**الصياغة**

```sql theme={null}
timeSeriesIdToGroup(id)
```

**الأسماء المستعارة**: `timeSeriesIdToTagsGroup`

**الوسائط**

* `id` — معرّف سلسلة زمنية. [`UInt64`](/ar/reference/data-types/int-uint) أو [`UInt128`](/ar/reference/data-types/int-uint) أو [`UUID`](/ar/reference/data-types/uuid) أو [`FixedString(16)`](/ar/reference/data-types/fixedstring)

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

تعيد مجموعة من الوسوم المرتبطة بالمعرّف `id` لسلسلة زمنية. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToGroup(same_id) AS group,
       timeSeriesGroupToTags(group)
```

```response title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─group─┬─timeSeriesGroupToTags(group)───────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴───────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesIdToTags">
  ## timeSeriesIdToTags
</div>

أُضيف في: v25.8.0

يعيد الوسوم المرتبطة بمُعرّف محدد لسلسلة زمنية.
راجع أيضًا الدالة [timeSeriesStoreTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags).

**البنية**

```sql theme={null}
timeSeriesIdToTags(id)
```

**الوسيطات**

* `id` — معرّف سلسلة زمنية. [`UInt64`](/ar/reference/data-types/int-uint) أو [`UInt128`](/ar/reference/data-types/int-uint) أو [`UUID`](/ar/reference/data-types/uuid) أو [`FixedString(16)`](/ar/reference/data-types/fixedstring)

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

تُرجِع مصفوفة من الأزواج `(tag_name, tag_value)`.
تكون المصفوفة المعادة مرتبة دائمًا حسب `tag_name`، ولا تحتوي أبدًا على `tag_name` نفسه أكثر من مرة.
[`Array(Tuple(String, String))`](/ar/reference/data-types/array)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id)
```

```response title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesJoinTags">
  ## timeSeriesJoinTags
</div>

أُضيفت في: v26.1.0

تجمع هذه الدالة قيم الوسوم المحددة والمستخرجة من مجموعة وسوم.
وتُدرِج فاصلاً بين القيم المجمّعة وتُرجع مجموعة وسوم جديدة
يُضبط فيها الوسم `dest_tag` على القيمة المجمّعة.
وتحاكي هذه الدالة منطق دالة Prometheus
[label\_join()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_join).

**البنية**

```sql theme={null}
timeSeriesJoinTags(group, dest_tag, separator, src_tags)
```

**الوسائط**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)
* `dest_tag` — اسم وسم لنتيجة الربط، وسيُضاف إلى `group`. [`String`](/ar/reference/data-types/string)
* `separator` — فاصل يُدرج بين القيم المربوطة. [`String`](/ar/reference/data-types/string)
* `src_tags` — أسماء وسوم المصدر التي تحتوي على القيم التي سيجري ربطها. [`Array(String)`](/ar/reference/data-types/array)

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

يعيد مجموعة وسوم جديدة مع تعيين الوسم `dest_tag` إلى نتيجة الربط. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('src1', 'a'), ('src2', 'b'), ('src3', 'c')]) AS group,
       timeSeriesJoinTags(group, 'foo', ',', ['src1', 'src2', 'src3']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─────────────────────────────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a,b,c'),('job','api-server'),('src1','a'),('src2','b'),('src3','c')] │
└───────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesRange">
  ## timeSeriesRange
</div>

أُضيف في: v25.8.0

يُنشئ نطاقًا من الطوابع الزمنية \[start\_timestamp, start\_timestamp + step, start\_timestamp + 2 \* step, ..., end\_timestamp].

إذا كان `start_timestamp` مساويًا لـ `end_timestamp`، فستُرجِع الدالة مصفوفة من عنصر واحد تحتوي على `[start_timestamp]`.

الدالة `timeSeriesRange()` مشابهة للدالة [range](/ar/reference/functions/regular-functions/array-functions#range).

**البنية**

```sql theme={null}
timeSeriesRange(start_timestamp, end_timestamp, step)
```

**الوسيطات**

* `start_timestamp` — بداية النطاق. [`DateTime64`](/ar/reference/data-types/datetime64) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`UInt32`](/ar/reference/data-types/int-uint)
* `end_timestamp` — نهاية النطاق. [`DateTime64`](/ar/reference/data-types/datetime64) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`UInt32`](/ar/reference/data-types/int-uint)
* `step` — خطوة النطاق بالثواني. [`UInt32/64`](/ar/reference/data-types/int-uint) أو [`Decimal32/64`](/ar/reference/data-types/decimal)

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

تُرجِع نطاقًا من الطوابع الزمنية. [`Array(DateTime64)`](/ar/reference/data-types/array)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30)
```

```response title=Response theme={null}
┌────────────────────────────────────result─────────────────────────────────────────┐
│ ['2025-06-01 00:00:00.000', '2025-06-01 00:00:30.000', '2025-06-01 00:01:00.000'] │
└───────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesRemoveAllTagsExcept">
  ## timeSeriesRemoveAllTagsExcept
</div>

أُضيفت في: v26.1.0

يزيل كل الوسوم من مجموعة وسوم باستثناء الوسوم المحددة.
راجع أيضًا الدالة [timeSeriesRemoveTag()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags).

**الصياغة**

```sql theme={null}
timeSeriesRemoveAllTagsExcept(group, tags_to_keep)
```

**الوسيطات**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)
* `tags_to_keep` — أسماء الوسوم المطلوب الاحتفاظ بها في المجموعة. [`Array(String)`](/ar/reference/data-types/array)

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

مجموعة جديدة من الوسوم لا يُحتفَظ فيها إلا بالوسوم المحددة. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesRemoveAllTagsExcept(group, ['env']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─┐
│     1 │            2 │ [('env','dev')]                     │
└───────┴──────────────┴─────────────────────────────────────┘
```

<div id="timeSeriesRemoveTag">
  ## timeSeriesRemoveTag
</div>

أُضيف في: v26.1.0

يزيل وسمًا محددًا من مجموعة من الوسوم.
إذا لم يكن هذا الوسم موجودًا في المجموعة، فستُعاد المجموعة كما هي.
انظر أيضًا الدالة [timeSeriesRemoveTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags)،
[timeSeriesRemoveAllTagsExcept()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept).

**الصيغة**

```sql theme={null}
timeSeriesRemoveTag(group, tag_to_remove)
```

**الوسيطات**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)
* `tag_to_remove` — اسم الوسم المراد إزالته من المجموعة. [`String`](/ar/reference/data-types/string)

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

مجموعة جديدة من الوسوم من دون الوسم المحدد. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group_of_3,
       timeSeriesRemoveTag(group_of_3, '__name__') AS group_of_2,
       timeSeriesGroupToTags(group_of_2),
       timeSeriesRemoveTag(group_of_2, 'env') AS group_of_1,
       timeSeriesGroupToTags(group_of_1),
       timeSeriesRemoveTag(group_of_1, 'region') AS empty_group,
       timeSeriesGroupToTags(empty_group)
```

```response title=Response theme={null}
┌─group_of_3─┬─group_of_2─┬─timeSeriesGroupToTags(group_of_2)─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)─┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('env','dev'),('region','eu')]   │          3 │ [('region','eu')]                 │           0 │ []                                 │
└────────────┴────────────┴───────────────────────────────────┴────────────┴───────────────────────────────────┴─────────────┴────────────────────────────────────┘
```

<div id="timeSeriesRemoveTags">
  ## timeSeriesRemoveTags
</div>

أُضيفت في: v26.1.0

تزيل الوسوم المحددة من مجموعة وسوم.
إذا لم تكن بعض الوسوم المحددة موجودة في مجموعة الوسوم، فستتجاهلها الدالة.
راجع أيضًا الدالة [timeSeriesRemoveTag()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveAllTagsExcept()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept).

**البنية**

```sql theme={null}
timeSeriesRemoveTags(group, tags_to_remove)
```

**الوسيطات**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)
* `tags_to_remove` — أسماء الوسوم المطلوب إزالتها من المجموعة. [`Array(String)`](/ar/reference/data-types/array)

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

مجموعة وسوم جديدة من دون الوسوم المحددة. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group_of_3,
       timeSeriesRemoveTags(group_of_3, ['env', 'region']) AS group_of_1,
       timeSeriesGroupToTags(group_of_1),
       timeSeriesRemoveTags(group_of_1, ['__name__', 'nonexistent']) AS empty_group,
       timeSeriesGroupToTags(empty_group)
```

```response title=Response theme={null}
┌─group_of_3─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)────┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('__name__','http_requests_count')] │           0 │ []                                 │
└────────────┴────────────┴──────────────────────────────────────┴─────────────┴────────────────────────────────────┘
```

<div id="timeSeriesReplaceTag">
  ## timeSeriesReplaceTag
</div>

أُضيف في: v26.1.0

يطابق التعبير النمطي `regex` قيمة الوسم `src_tag`.
إذا تحقق تطابق، فستكون قيمة الوسم `dest_tag` في المجموعة المُعادة هي الناتج عن توسيع `replacement`،
إلى جانب الوسوم الأصلية في الإدخال.
تحاكي هذه الدالة منطق دالة prometheus
[label\_replace()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_replace).

**الصيغة**

```sql theme={null}
timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)
```

**الوسيطات**

* `group` — مجموعة من الوسوم. [`UInt64`](/ar/reference/data-types/int-uint)
* `dest_tag` — اسم وسم الوجهة الذي ستُحفَظ فيه المجموعة الناتجة. [`String`](/ar/reference/data-types/string)
* `replacement` — نمط استبدال، ويمكن أن يحتوي على $1 أو $2 أو \$name للإشارة إلى المجموعات الملتقطة في التعبير النمطي 'regex'. [`String`](/ar/reference/data-types/string)
* `src_tag` — اسم وسم تُستخدم قيمته لمطابقة التعبير النمطي 'regex'. [`String`](/ar/reference/data-types/string)
* `regex` — تعبير نمطي. [`String`](/ar/reference/data-types/string)

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

مجموعة وسوم جديدة قد يُضاف إليها `dest_tag`. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('service', 'a:c')]) AS group,
       timeSeriesReplaceTag(group, 'foo', '$1', 'service', '(.*):.*') AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a'),('job','api-server'),('service','a:c')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesStoreTags">
  ## timeSeriesStoreTags
</div>

أُضيف في: v25.8.0

يخزّن في سياق الاستعلام تعيينًا بين معرّف محدد لسلسلة زمنية ومجموعة من الوسوم.
يمكن استخدام الدالتين [timeSeriesIdToTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesIdToTags)
و[timeSeriesIdToGroup()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesIdToGroup)
للوصول إلى هذا التعيين لاحقًا أثناء تنفيذ الاستعلام.

**الصياغة**

```sql theme={null}
timeSeriesStoreTags(id, tags_array, separate_tag_name_1, separate_tag_value_1, ...)
```

**الوسائط**

* `id` — معرّف سلسلة زمنية. [`UInt64`](/ar/reference/data-types/int-uint) أو [`UInt128`](/ar/reference/data-types/int-uint) أو [`UUID`](/ar/reference/data-types/uuid) أو [`FixedString(16)`](/ar/reference/data-types/fixedstring)
* `tags_array` — مصفوفة من الأزواج (tag\_name, tag\_value). [`Array(Tuple(String, String))`](/ar/reference/data-types/array) أو [`NULL`](/ar/reference/syntax#null)
* `separate_tag_name_i` — اسم وسم. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring)
* `separate_tag_value_i` — قيمة وسم. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring) أو [`Nullable(String)`](/ar/reference/data-types/nullable)

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

يُرجع معرّف سلسلة زمنية (أي الوسيط الأول فقط).

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id),
       timeSeriesGroupToTags(timeSeriesIdToGroup(same_id))
```

```response title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notEquals(same_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┬─timeSeriesGroupToTags(timeSeriesIdToGroup(same_id))────────────────┐
│ 8374283493092 │ 8374283493092 │                               0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴─────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesTagsToGroup">
  ## timeSeriesTagsToGroup
</div>

قُدِّمت في: v26.1.0

تُرجع مجموعة من الوسوم المرتبطة بالوسوم المحددة.
إذا عُثر على مجموعة الوسوم نفسها عدة مرات أثناء تنفيذ الاستعلام، فستُرجع الدالة المجموعة نفسها.
إذا كانت مجموعة الوسوم فارغة، فستُرجع الدالة دائمًا 0.
انظر أيضًا الدالة [timeSeriesGroupToTags()](/ar/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags).

**البنية**

```sql theme={null}
timeSeriesTagsToGroup(tags_array, tag_name_1, tag_value_1, tag_name2, tag_value2, ...)
```

**الوسيطات**

* `tags_array` — مصفوفة من الأزواج (tag\_name, tag\_value). [`Array(Tuple(String, String))`](/ar/reference/data-types/array) أو [`NULL`](/ar/reference/syntax#null)
* `tag_name_i` — اسم وسم. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring)
* `tag_value_i` — قيمة الوسم. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring) أو [`Nullable(String)`](/ar/reference/data-types/nullable)

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

يُرجع مجموعة وسوم مرتبطة بالوسوم المحددة. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group1,
       timeSeriesTagsToGroup([], '__name__', 'http_failures') AS group2,
       timeSeriesTagsToGroup([]) AS empty_group,
       timeSeriesTagsToGroup([], '__name__', 'http_failures') AS same_group2,
       throwIf(same_group2 != group2),
       timeSeriesGroupToTags(group2)
```

```response title=Response theme={null}
┌─group1─┬─group2─┬─empty_group─┬─same_group2─┬─throwIf(notEquals(same_group2, group2))─┬─timeSeriesGroupToTags(group2)──┐
│      1 │      2 │           0 │           2 │                                       0 │ [('__name__','http_failures')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘
```

<div id="timeSeriesThrowDuplicateSeriesIf">
  ## timeSeriesThrowDuplicateSeriesIf
</div>

أُضيفت في: v26.2.0

تتحقق الدالة من `condition`، وإذا كانت `true` فإنها تثير استثناءً بالرسالة التالية
`Multiple series have the same tags <tags>, duplicate series in the same result set are not allowed`.
إذا كانت `condition` هي `false`، فتعيد الدالة `0`.
تشبه هذه الدالة [throwIf()](/ar/reference/functions/regular-functions/other-functions#throwIf)،
لكنها تستخدم رمز خطأ مختلفًا وتنسّق رسالة الخطأ بشكل مختلف.

**البنية**

```sql theme={null}
timeSeriesThrowDuplicateSeriesIf(condition, group)
```

**الوسيطات**

* `condition` — الشرط المراد التحقق منه، ويحتوي عادةً على الدالة [count()](/ar/reference/functions/aggregate-functions/count#count) [`UInt8`](/ar/reference/data-types/int-uint)
* `group` — مجموعة وسوم. [`UInt64`](/ar/reference/data-types/int-uint)

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

تعيد `0`. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال**

```sql title=Query theme={null}
CREATE TABLE test(tags Array(Tuple(String, String))) engine=Memory;

INSERT INTO test VALUES ([('__name__', 'up')]);

SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0;  -- OK

INSERT INTO test VALUES ([('__name__', 'up')]);

SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0;  -- Throws exception "Multiple series have the same tags {'__name__': 'up'}"
```

```response title=Response theme={null}
```