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

> توثيق دوال المصفوفات

# دوال المصفوفات

{/*AUTOGENERATED_START*/}

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

أُضيف في: v1.1.0

ينشئ مصفوفة من وسيطات الدالة.

يجب أن تكون الوسيطات ثوابت، وأن تكون أنواعها قابلة للاشتراك في نوع أعلى مشترك.
يجب تمرير وسيطة واحدة على الأقل، لأن نوع المصفوفة المطلوب إنشاؤها لن يكون واضحًا بخلاف ذلك.
وهذا يعني أنه لا يمكنك استخدام هذه الدالة لإنشاء مصفوفة فارغة. ولتنفيذ ذلك، استخدم الدالة `emptyArray*`.

استخدم العامل `[ ]` للحصول على الوظيفة نفسها.

**الصيغة**

```sql theme={null}
array(x1 [, x2, ..., xN])
```

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

* `x1` — قيمة ثابتة من أي نوع `T`. إذا تم توفير هذا الوسيط فقط، فستكون المصفوفة من النوع `T`. - `[, x2, ..., xN]` — `N` قيم ثابتة إضافية لها نوع أعلى مشترك مع `x1`

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

تعيد مصفوفة، حيث إن 'T' هو أصغر نوع مشترك بين الوسيطات المُمرَّرة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**استخدام صحيح**

```sql title=Query theme={null}
SELECT array(toInt32(1), toUInt16(2), toInt8(3)) AS a, toTypeName(a)
```

```response title=Response theme={null}
┌─a───────┬─toTypeName(a)─┐
│ [1,2,3] │ Array(Int32)  │
└─────────┴───────────────┘
```

**استخدام غير صحيح**

```sql title=Query theme={null}
SELECT array(toInt32(5), toDateTime('1998-06-16'), toInt8(5)) AS a, toTypeName(a)
```

```response title=Response theme={null}
Received exception from server (version 25.4.3):
Code: 386. DB::Exception: Received from localhost:9000. DB::Exception:
There is no supertype for types Int32, DateTime, Int8 ...
```

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

أُضيفت في: v20.4.0

تحسب المساحة تحت منحنى الدقة والاستدعاء (PR).
يُنشأ منحنى الدقة والاستدعاء برسم الدقة على المحور y والاستدعاء على المحور x عبر جميع العتبات.
تتراوح القيمة الناتجة بين 0 و1، وتشير القيمة الأعلى إلى أداء أفضل للنموذج.
تكون PR AUC مفيدة بشكل خاص مع مجموعات البيانات غير المتوازنة، إذ توفّر مقارنة أوضح للأداء من ROC AUC في هذه الحالات.
لمزيد من التفاصيل، يُرجى الاطلاع على [هنا](https://developers.google.com/machine-learning/glossary#pr-auc-area-under-the-pr-curve)، و[هنا](https://developers.google.com/machine-learning/crash-course/classification/roc-and-auc#expandable-1)، و[هنا](https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve).

**الصيغة**

```sql theme={null}
arrayAUCPR(scores, labels[, partial_offsets])
```

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

**الوسائط**

* `cores` — الدرجات التي ينتجها نموذج التنبؤ. [`Array((U)Int*)`](/ar/reference/data-types/array) أو [`Array(Float*)`](/ar/reference/data-types/array)
* `labels` — تسميات العينات، وعادةً ما تكون 1 للعينة الإيجابية و0 للعينة السلبية. [`Array((U)Int*)`](/ar/reference/data-types/array) أو [`Array(Enum)`](/ar/reference/data-types/array)
* `partial_offsets` —
* اختياري. مصفوفة [`Array(T)`](/ar/reference/data-types/array) تتكوّن من ثلاثة أعداد صحيحة غير سالبة لحساب مساحة جزئية تحت منحنى PR (وهو ما يعادل شريطًا رأسيًا في فضاء PR) بدلًا من حساب AUC بالكامل. يفيد هذا الخيار في الحساب الموزّع لـ PR AUC. يجب أن تحتوي المصفوفة على العناصر التالية \[`higher_partitions_tp`, `higher_partitions_fp`, `total_positives`].
  * `higher_partitions_tp`: عدد التسميات الإيجابية في الأقسام ذات الدرجات الأعلى.
  * `higher_partitions_fp`: عدد التسميات السلبية في الأقسام ذات الدرجات الأعلى.
  * `total_positives`: العدد الإجمالي للعينات الإيجابية في مجموعة البيانات بأكملها.

<Note>
  عند استخدام `arr_partial_offsets`، يجب أن يكون كل من `arr_scores` و`arr_labels` مجرد قسم من مجموعة البيانات بأكملها، ويحتوي على نطاق من الدرجات.
  يجب تقسيم مجموعة البيانات إلى أقسام متجاورة، بحيث يحتوي كل قسم على مجموعة فرعية من البيانات التي تقع درجاتها ضمن نطاق محدد.
  على سبيل المثال:

  * قد يحتوي أحد الأقسام على جميع الدرجات ضمن النطاق \[0, 0.5).
  * وقد يحتوي قسم آخر على الدرجات ضمن النطاق \[0.5, 1.0].
</Note>

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

تعيد المساحة تحت منحنى الدقة-الاستدعاء (PR). [`Float64`](/ar/reference/data-types/float)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayAUCPR([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1]);
```

```response title=Response theme={null}
┌─arrayAUCPR([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1])─┐
│                              0.8333333333333333 │
└─────────────────────────────────────────────────┘
```

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

أُضيف في: v1.1.0

يعيد `1` إذا أرجعت الدالة lambda ‏`func(x [, y1, y2, ... yN])` القيمة true لجميع العناصر. وإلا، فيعيد `0`.

**البنية**

```sql theme={null}
arrayAll(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — دالة لامبدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — مصفوفة المصدر المراد معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `cond1_arr, ...` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد `1` إذا كانت دالة لامبدا تُرجع true لجميع العناصر، وإلا فتُرجع `0` [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**جميع العناصر تستوفي الشرط**

```sql title=Query theme={null}
SELECT arrayAll(x, y -> x=y, [1, 2, 3], [1, 2, 3])
```

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

**لا تتطابق جميع العناصر**

```sql title=Query theme={null}
SELECT arrayAll(x, y -> x=y, [1, 2, 3], [1, 1, 1])
```

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

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

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

يحسب الارتباط الذاتي لمصفوفة.
إذا تم توفير `max_lag`، فسيحسب الارتباط فقط لقيم التأخر ضمن النطاق `[0, max_lag)`.
إذا لم يتم توفير `max_lag`، فسيحسبه لجميع قيم التأخر الممكنة.

**الصيغة**

```sql theme={null}
arrayAutocorrelation(arr, [max_lag])
```

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

* `arr` — مصفوفة من الأرقام. [`Array(T)`](/ar/reference/data-types/array)
* `max_lag` — اختياري. الحد الأقصى لعدد فترات التأخر المطلوب حسابها. يجب أن يكون عددًا صحيحًا غير سالب. [`Integer`](/ar/reference/data-types/int-uint)

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

يعيد مصفوفة من نوع Float64. ويعيد NaN إذا كان التباين يساوي 0. [`Array(Float64)`](/ar/reference/data-types/array)

**أمثلة**

**خطي**

```sql title=Query theme={null}
SELECT arrayAutocorrelation([1, 2, 3, 4, 5]);
```

```response title=Response theme={null}
[1, 0.4, -0.1, -0.4, -0.4]
```

**متناظر**

```sql title=Query theme={null}
SELECT arrayAutocorrelation([10, 20, 10]);
```

```response title=Response theme={null}
[1, -0.6666666666666669, 0.16666666666666674]
```

**ثابت**

```sql title=Query theme={null}
SELECT arrayAutocorrelation([5, 5, 5]);
```

```response title=Response theme={null}
[nan, nan, nan]
```

**محدود**

```sql title=Query theme={null}
SELECT arrayAutocorrelation([1, 2, 3, 4, 5], 2);
```

```response title=Response theme={null}
[1, 0.4]
```

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

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

يعيد متوسط عناصر المصفوفة المصدر.

إذا تم تحديد دالة لامدا `func`، فسيُعاد متوسط عناصر النتائج الناتجة عن اللامدا.

**الصيغة**

```sql theme={null}
arrayAvg([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — اختياري. دالة لامبدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — مصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد متوسط عناصر مصفوفة المصدر، أو متوسط عناصر ناتج دالة لامبدا إذا تم توفيرها. [`Float64`](/ar/reference/data-types/float)

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT arrayAvg([1, 2, 3, 4]);
```

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

**الاستخدام مع دالة لامدا**

```sql title=Query theme={null}
SELECT arrayAvg(x, y -> x*y, [2, 3], [2, 3]) AS res;
```

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

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

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

تعيد مصفوفة تضم أصغر K عنصرًا من مصفوفة الإدخال، مرتبة بترتيب تصاعدي.
إذا تم تحديد دالة لامدا `f`، فتُقارَن العناصر بناءً على نتيجة تطبيق `f` على كل عنصر.
إذا كانت `f` تقبل عدة وسائط، فستُمرَّر مصفوفات إضافية إلى `arrayBottomK`، وتكون عناصرها
مطابقةً لوسائط `f`.

يتم تخطي قيم `NULL` ولا تظهر في النتيجة. ويكون حجم النتيجة بحد أقصى `K`
وقد يكون أصغر إذا كانت مصفوفة الإدخال تحتوي على عدد من العناصر غير `NULL` أقل من `K`.
ويكون نوع عنصر النتيجة هو النظير غير القابل لأن تكون قيمته `NULL` لنوع عنصر الإدخال.

`arrayBottomK` هي [دالة عالية الرتبة](/ar/reference/functions/regular-functions/overview#higher-order-functions).

انظر أيضًا:

* `arrayTopK`، التي تعيد أكبر K عنصرًا بدلًا من ذلك.
* `arrayPartialSort`، التي تنتج عناصر K نفسها في المواضع `[1..K]` ولكن
  تُبقي أيضًا العناصر المتبقية بترتيب غير محدد، ولا تتخطى القيم الفارغة.

**الصياغة**

```sql theme={null}
arrayBottomK([f,] K, arr [, arr1, ... ,arrN])
```

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

* `f(arr[, arr1, ... ,arrN])` — اختياري. دالة لامدا لحساب مفتاح الفرز لكل عنصر. [`دالة لامدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `K` — عدد أصغر العناصر المطلوب إرجاعها. [`(U)Int8/16/32/64`](/ar/reference/data-types/int-uint)
* `arr` — مصفوفة. [`Array(T)`](/ar/reference/data-types/array)
* `arr1, ... ,arrN` — `N` من المصفوفات الإضافية، في حال كانت `f` تقبل عدة وسيطات. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد ما يصل إلى `K` من عناصر `arr` الأصغر قيمةً (أو أصغر نتائج لامدا)، مرتبة بترتيب تصاعدي.
يتم تخطي قيم `NULL`. وتكون المصفوفة المعادة من نوع العنصر `T` حتى عندما يكون الإدخال من النوع `Nullable(T)`.

**أمثلة**

**simple\_int**

```sql title=Query theme={null}
SELECT arrayBottomK(3, [1, 5, 2, 7, 3])
```

```response title=Response theme={null}
[1,2,3]
```

**skip\_nulls**

```sql title=Query theme={null}
SELECT arrayBottomK(3, [1, NULL, 5, 2, NULL, 7])
```

```response title=Response theme={null}
[1,2,5]
```

**fewer\_than\_k**

```sql title=Query theme={null}
SELECT arrayBottomK(5, [1, NULL, 2])
```

```response title=Response theme={null}
[1,2]
```

**lambda\_simple**

```sql title=Query theme={null}
SELECT arrayBottomK((x) -> -x, 2, [5, 9, 1, 3])
```

```response title=Response theme={null}
[9,5]
```

**lambda\_multi**

```sql title=Query theme={null}
SELECT arrayBottomK((x, y) -> y, 2, ['a', 'b', 'c'], [3, 1, 2])
```

```response title=Response theme={null}
['b','c']
```

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

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

تزيل العناصر المكررة المتتالية من المصفوفة، بما في ذلك قيم `null`. ويُحدَّد ترتيب القيم في المصفوفة الناتجة بحسب ترتيبها في المصفوفة المُدخلة.

**الصيغة**

```sql theme={null}
arrayCompact(arr)
```

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

* `arr` — مصفوفة تُزال منها القيم المكررة. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجع مصفوفةً من دون قيم مكررة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayCompact([1, 1, nan, nan, 2, 3, 3, 3]);
```

```response title=Response theme={null}
[1,nan,2,3]
```

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

ظهر لأول مرة في: v1.1.0

يدمج المصفوفات المُمرَّرة كوسيطات.

**البنية**

```sql theme={null}
arrayConcat(arr1 [, arr2, ... , arrN])
```

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

* `arr1 [, arr2, ... , arrN]` — عدد N من المصفوفات المراد ضمّها. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجع مصفوفة واحدة مدمجة من وسيطات المصفوفات المُدخلة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayConcat([1, 2], [3, 4], [5, 6]) AS res
```

```response title=Response theme={null}
[1, 2, 3, 4, 5, 6]
```

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

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

تعيد عدد العناصر التي تُرجِع `func(arr1[i], ..., arrN[i])` القيمة true لها.
إذا لم يتم تحديد `func`، فإنها تعيد عدد العناصر غير الصفرية في Array.

تُعد `arrayCount` [دالة عالية الرتبة](/ar/reference/functions/regular-functions/overview#higher-order-functions).

**الصياغة**

```sql theme={null}
arrayCount([func, ] arr1, ...)
```

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

* `func` — اختياري. الدالة المراد تطبيقها على كل عنصر في المصفوفة (أو المصفوفات). [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1, ..., arrN` — عددها N من المصفوفات. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد عدد العناصر التي تُرجع `func` لها القيمة true. وإلا، تعيد عدد العناصر غير الصفرية في المصفوفة. [`UInt32`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayCount(x -> (x % 2), groupArray(number)) FROM numbers(10)
```

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

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

تم تقديمها في: v1.1.0

تعيد مصفوفة تحتوي على المجاميع الجزئية (التراكمية) لعناصر مصفوفة الإدخال. إذا جرى تحديد دالة لامبدا، فيُحسب المجموع بتطبيق دالة لامبدا على عناصر المصفوفة في كل موضع.

**البنية**

```sql theme={null}
arrayCumSum([func,] arr1[, arr2, ... , arrN])
```

**الوسائط**

* `func` — اختياري. دالة لامبدا تُطبَّق على عناصر المصفوفة عند كل موضع. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1` — مصفوفة المصدر للقيم الرقمية. [`Array(T)`](/ar/reference/data-types/array)
* `[arr2, ..., arrN]` — اختياري. مصفوفات إضافية بالحجم نفسه، تُمرَّر كوسائط إلى دالة لامبدا إذا جرى تحديدها. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة من المجاميع الجزئية لعناصر مصفوفة المصدر. يتطابق نوع النتيجة مع النوع الرقمي لمصفوفة الإدخال. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT arrayCumSum([1, 1, 1, 1]) AS res
```

```response title=Response theme={null}
[1, 2, 3, 4]
```

**باستخدام دالة لامبدا**

```sql title=Query theme={null}
SELECT arrayCumSum(x -> x * 2, [1, 2, 3]) AS res
```

```response title=Response theme={null}
[2, 6, 12]
```

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

أُضيف في: v18.12.0

يعيد مصفوفة من المجاميع الجزئية (التراكمية) لعناصر مصفوفة المصدر، مع استبدال أي مجموع تراكمي سالب بالصفر. إذا جرى تحديد دالة لامبدا، يُحتسب المجموع عبر تطبيق دالة لامبدا على عناصر المصفوفة عند كل موضع.

**البنية**

```sql theme={null}
arrayCumSumNonNegative([func,] arr1[, arr2, ... , arrN])
```

**الوسائط**

* `func` — اختياري. دالة لامبدا تُطبَّق على عناصر المصفوفة عند كل موضع. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1` — مصفوفة المصدر للقيم الرقمية. [`Array(T)`](/ar/reference/data-types/array)
* `[arr2, ..., arrN]` — اختياري. مصفوفات إضافية بالحجم نفسه، تُمرَّر كوسائط إلى دالة لامبدا إذا جرى تحديدها. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة من المجاميع الجزئية لعناصر مصفوفة المصدر، مع استبدال أي مجموع تراكمي سالب بالصفر. يطابق نوع النتيجة النوع الرقمي لمصفوفة الإدخال. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT arrayCumSumNonNegative([1, 1, -4, 1]) AS res
```

```response title=Response theme={null}
[1, 2, 0, 1]
```

**باستخدام دالة لامبدا**

```sql title=Query theme={null}
SELECT arrayCumSumNonNegative(x -> x * 2, [1, -2, 3]) AS res
```

```response title=Response theme={null}
[2, 0, 6]
```

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

أُضيف في: v1.1.0

يحسب مصفوفة من الفروق بين عناصر المصفوفة المتجاورة.
سيكون العنصر الأول في المصفوفة الناتجة هو 0، والثاني `arr[1] - arr[0]`، والثالث `arr[2] - arr[1]`، وهكذا.
يُحدَّد نوع العناصر في المصفوفة الناتجة وفقًا لقواعد استدلال النوع الخاصة بالطرح (على سبيل المثال `UInt8` - `UInt8` = `Int16`).

**البنية**

```sql theme={null}
arrayDifference(arr)
```

**الوسائط**

* `arr` — المصفوفة التي تُحسَب لها الفروق بين العناصر المتجاورة. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد مصفوفة تحتوي على الفروق بين العناصر المتجاورة في المصفوفة [`UInt*`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayDifference([1, 2, 3, 4]);
```

```response title=Response theme={null}
[0,1,1,1]
```

**مثال على تجاوز السعة بسبب نوع النتيجة Int64**

```sql title=Query theme={null}
SELECT arrayDifference([0, 10000000000000000000]);
```

```response title=Response theme={null}
┌─arrayDifference([0, 10000000000000000000])─┐
│ [0,-8446744073709551616]                   │
└────────────────────────────────────────────┘
```

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

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

تُرجع مصفوفة لا تحتوي إلا على العناصر الفريدة في المصفوفة.

**البنية**

```sql theme={null}
arrayDistinct(arr)
```

**الوسائط**

* `arr` — المصفوفة التي تُستخرج منها العناصر الفريدة. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجِع مصفوفة تحتوي على العناصر الفريدة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayDistinct([1, 2, 2, 3, 1]);
```

```response title=Response theme={null}
[1,2,3]
```

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

ظهر في: v23.5.0

يعيد الجداء النقطي لمصفوفتين.

<Note>
  يجب أن يكون حجما المتجهين متساويين. كما يمكن أن تحتوي Array وTuple أيضًا على أنواع عناصر مختلطة.
</Note>

**البنية**

```sql theme={null}
arrayDotProduct(v1, v2)
```

**الوسائط**

* `v1` — المتجه الأول. [`Array((U)Int* | Float* | Decimal)`](/ar/reference/data-types/array) أو [`Tuple((U)Int* | Float* | Decimal)`](/ar/reference/data-types/tuple)
* `v2` — المتجه الثاني. [`Array((U)Int* | Float* | Decimal)`](/ar/reference/data-types/array) أو [`Tuple((U)Int* | Float* | Decimal)`](/ar/reference/data-types/tuple)

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

الجداء النقطي للمتجهين.

<Note>
  يتحدد نوع الإرجاع حسب نوع الوسائط. إذا كانت Arrays أو Tuples تحتوي على أنواع عناصر مختلطة، فسيكون نوع النتيجة هو النوع الفائق.
</Note>

[`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

**أمثلة**

**مثال على Array**

```sql title=Query theme={null}
SELECT arrayDotProduct([1, 2, 3], [4, 5, 6]) AS res, toTypeName(res);
```

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

**مثال على Tuple**

```sql title=Query theme={null}
SELECT dotProduct((1::UInt16, 2::UInt8, 3::Float32),(4::Int16, 5::Float32, 6::UInt8)) AS res, toTypeName(res);
```

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

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

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

تُرجِع عنصر المصفوفة المُعطاة عند الفهرس `n`، حيث يمكن أن يكون `n` أي نوع من الأعداد الصحيحة.
إذا كان الفهرس خارج حدود المصفوفة، فستُرجِع قيمة افتراضية (0 للأرقام، وسلسلة فارغة للنصوص، وما إلى ذلك)،
باستثناء وسيطات مصفوفة غير ثابتة وفهرس ثابت قيمته 0. في هذه الحالة سيظهر الخطأ `Array indices are 1-based`.

<Note>
  المصفوفات في ClickHouse تبدأ فهارسها من 1.
</Note>

الفهارس السالبة مدعومة. في هذه الحالة، يُختار العنصر المقابل بعد العد من النهاية. على سبيل المثال، `arr[-1]` هو العنصر الأخير في المصفوفة.

يوفّر العامل `[n]` الوظيفة نفسها.

**الصياغة**

```sql theme={null}
arrayElement(arr, n)
```

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

* `arr` — المصفوفة المراد البحث فيها. [`Array(T)`](/ar/reference/data-types/array). - `n` — موضع العنصر المراد الحصول عليه. [`(U)Int*`](/ar/reference/data-types/int-uint).

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

يعيد مصفوفةً واحدةً مدمجة من وسيطات المصفوفات المُقدَّمة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayElement(arr, 2) FROM (SELECT [1, 2, 3] AS arr)
```

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

**الفهرسة بالمؤشرات السالبة**

```sql title=Query theme={null}
SELECT arrayElement(arr, -1) FROM (SELECT [1, 2, 3] AS arr)
```

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

**استخدام الصيغة \[n]**

```sql title=Query theme={null}
SELECT arr[2] FROM (SELECT [1, 2, 3] AS arr)
```

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

**الفهرس خارج نطاق المصفوفة**

```sql title=Query theme={null}
SELECT arrayElement(arr, 4) FROM (SELECT [1, 2, 3] AS arr)
```

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

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

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

تسترجع العنصر من المصفوفة المحددة عند الفهرس `n`، حيث يمكن أن يكون `n` من أي نوع عدد صحيح.
إذا كان الفهرس خارج حدود المصفوفة، فستُعاد `NULL` بدلًا من القيمة الافتراضية.

<Note>
  المصفوفات في ClickHouse تبدأ فهارسها من 1.
</Note>

الفهارس السالبة مدعومة. في هذه الحالة، يُختار العنصر المقابل عند العد من النهاية. على سبيل المثال، `arr[-1]` هو آخر عنصر في المصفوفة.

**الصيغة**

```sql theme={null}
arrayElementOrNull(arrays)
```

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

* `arrays` — عدد غير محدد من وسيطات المصفوفة. [`Array`](/ar/reference/data-types/array)

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

تُرجِع مصفوفةً واحدةً مدمجة من وسيطات المصفوفة المُمرَّرة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayElementOrNull(arr, 2) FROM (SELECT [1, 2, 3] AS arr)
```

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

**الفهرسة بالمؤشرات السالبة**

```sql title=Query theme={null}
SELECT arrayElementOrNull(arr, -1) FROM (SELECT [1, 2, 3] AS arr)
```

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

**الفهرس خارج نطاق المصفوفة**

```sql title=Query theme={null}
SELECT arrayElementOrNull(arr, 4) FROM (SELECT [1, 2, 3] AS arr)
```

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

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

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

يُرجع المصفوفة `[1, 2, 3, ..., length (arr)]`

تُستخدم هذه الدالة عادةً مع عبارة [`ARRAY JOIN`](/ar/reference/statements/select/array-join). وهي تتيح احتساب شيءٍ ما
مرة واحدة فقط لكل مصفوفة بعد تطبيق `ARRAY JOIN`.
ويمكن أيضًا استخدام هذه الدالة في الدوال عالية الرتبة. على سبيل المثال، يمكنك استخدامها للحصول على فهارس عناصر المصفوفة التي تطابق شرطًا.

**الصياغة**

```sql theme={null}
arrayEnumerate(arr)
```

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

* `arr` — المصفوفة المطلوب تعداد عناصرها. [`Array`](/ar/reference/data-types/array)

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

تُرجِع المصفوفة `[1, 2, 3, ..., length (arr)]`. [`Array(UInt32)`](/ar/reference/data-types/array)

**أمثلة**

**مثال أساسي مع ARRAY JOIN**

```sql title=Query theme={null}
CREATE TABLE test
(
    `id` UInt8,
    `tag` Array(String),
    `version` Array(String)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test VALUES (1, ['release-stable', 'dev', 'security'], ['2.4.0', '2.6.0-alpha', '2.4.0-sec1']);

SELECT
    id,
    tag,
    version,
    seq
FROM test
ARRAY JOIN
    tag,
    version,
    arrayEnumerate(tag) AS seq
```

```response title=Response theme={null}
┌─id─┬─tag────────────┬─version─────┬─seq─┐
│  1 │ release-stable │ 2.4.0       │   1 │
│  1 │ dev            │ 2.6.0-alpha │   2 │
│  1 │ security       │ 2.4.0-sec1  │   3 │
└────┴────────────────┴─────────────┴─────┘
```

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

استُحدثت في: v18.12.0

تعيد مصفوفة بالحجم نفسه مثل المصفوفة المصدر، وتُشير إلى موضع أول ظهور لكل عنصر في المصفوفة المصدر.

**البنية**

```sql theme={null}
arrayEnumerateDense(arr)
```

**الوسائط**

* `arr` — المصفوفة المطلوب ترقيم عناصرها. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد مصفوفة بنفس حجم `arr`، وتشير إلى الموضع الذي يظهر فيه كل عنصر لأول مرة في المصفوفة الأصلية [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayEnumerateDense([10, 20, 10, 30])
```

```response title=Response theme={null}
[1,2,1,3]
```

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

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

تُرجِع مصفوفة بالحجم نفسه مثل المصفوفة المصدر، مع الإشارة إلى الموضع الذي يظهر فيه كل عنصر لأول مرة في المصفوفة المصدر. وتتيح تعداد مصفوفة متعددة الأبعاد مع إمكانية تحديد مدى العمق المطلوب النظر إليه داخل المصفوفة.

**البنية**

```sql theme={null}
arrayEnumerateDenseRanked(clear_depth, arr, max_array_depth)
```

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

* `clear_depth` — عدِّد العناصر في المستوى المحدد كلٌّ على حدة. يجب أن تكون قيمته أقل من أو تساوي `max_arr_depth`. [`UInt*`](/ar/reference/data-types/int-uint)
* `arr` — مصفوفة متعددة الأبعاد N المطلوب تعدادها. [`Array(T)`](/ar/reference/data-types/array)
* `max_array_depth` — الحد الأقصى للعمق الفعّال. يجب أن يكون أقل من أو يساوي عمق `arr`. [`UInt*`](/ar/reference/data-types/int-uint)

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

تُعيد مصفوفةً تُبيّن موضع الظهور الأول لكل عنصر في المصفوفة المصدر [`Array`](/ar/reference/data-types/array)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
-- With clear_depth=1 and max_array_depth=1, the result is identical to what arrayEnumerateDense would give.

SELECT arrayEnumerateDenseRanked(1,[10, 20, 10, 30],1);
```

```response title=Response theme={null}
[1,2,1,3]
```

**الاستخدام مع مصفوفة متعددة الأبعاد**

```sql title=Query theme={null}
-- In this example, arrayEnumerateDenseRanked is used to obtain an array indicating, for each element of the
-- multidimensional array, what its position is among elements of the same value.
-- For the first row of the passed array, [10, 10, 30, 20], the corresponding first row of the result is [1, 1, 2, 3],
-- indicating that 10 is the first number encountered in position 1 and 2, 30 the second number encountered in position 3
-- and 20 is the third number encountered in position 4.
-- For the second row, [40, 50, 10, 30], the corresponding second row of the result is [4,5,1,2], indicating that 40
-- and 50 are the fourth and fifth numbers encountered in position 1 and 2 of that row, that another 10
-- (the first encountered number) is in position 3 and 30 (the second number encountered) is in the last position.

SELECT arrayEnumerateDenseRanked(1,[[10,10,30,20],[40,50,10,30]],2);
```

```response title=Response theme={null}
[[1,1,2,3],[4,5,1,2]]
```

**مثال مع زيادة قيمة clear\_depth**

```sql title=Query theme={null}
-- Changing clear_depth=2 results in the enumeration occurring separately for each row anew.

SELECT arrayEnumerateDenseRanked(2,[[10,10,30,20],[40,50,10,30]],2);
```

```response title=Response theme={null}
[[1, 1, 2, 3], [1, 2, 3, 4]]
```

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

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

تعيد مصفوفة بالحجم نفسه لمصفوفة المصدر، بحيث تبيّن لكل عنصر ترتيبه بين العناصر ذات القيمة نفسها.

تكون هذه الدالة مفيدة عند استخدام `ARRAY JOIN` وتجميع عناصر المصفوفة.

يمكن للدالة قبول عدة مصفوفات بالحجم نفسه كوسيطات. في هذه الحالة، يُحدَّد التفرد وفقًا لـ Tuple المكوَّن من العناصر الواقعة في المواضع نفسها عبر جميع المصفوفات.

**الصيغة**

```sql theme={null}
arrayEnumerateUniq(arr1[, arr2, ... , arrN])
```

**الوسائط**

* `arr1` — المصفوفة الأولى المراد معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `arr2, ...` — اختياري. مصفوفات إضافية بالحجم نفسه للتفرّد بحسب الـ tuple. [`Array(UInt32)`](/ar/reference/data-types/array)

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

يعيد مصفوفة يكون كل عنصر فيها هو ترتيبه بين العناصر ذات القيمة نفسها أو الـ tuple نفسه. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT arrayEnumerateUniq([10, 20, 10, 30]);
```

```response title=Response theme={null}
[1, 1, 2, 1]
```

**مصفوفات متعددة**

```sql title=Query theme={null}
SELECT arrayEnumerateUniq([1, 1, 1, 2, 2, 2], [1, 1, 2, 1, 1, 2]);
```

```response title=Response theme={null}
[1,2,1,1,2,1]
```

**التجميع باستخدام ARRAY JOIN**

```sql title=Query theme={null}
-- Each goal ID has a calculation of the number of conversions (each element in the Goals nested data structure is a goal that was reached, which we refer to as a conversion)
-- and the number of sessions. Without ARRAY JOIN, we would have counted the number of sessions as sum(Sign). But in this particular case,
-- the rows were multiplied by the nested Goals structure, so in order to count each session one time after this, we apply a condition to the
-- value of the arrayEnumerateUniq(Goals.ID) function.

SELECT
    Goals.ID AS GoalID,
    sum(Sign) AS Reaches,
    sumIf(Sign, num = 1) AS Visits
FROM test.visits
ARRAY JOIN
    Goals,
    arrayEnumerateUniq(Goals.ID) AS num
WHERE CounterID = 160656
GROUP BY GoalID
ORDER BY Reaches DESC
LIMIT 10
```

```response title=Response theme={null}
┌──GoalID─┬─Reaches─┬─Visits─┐
│   53225 │    3214 │   1097 │
│ 2825062 │    3188 │   1097 │
│   56600 │    2803 │    488 │
│ 1989037 │    2401 │    365 │
│ 2830064 │    2396 │    910 │
│ 1113562 │    2372 │    373 │
│ 3270895 │    2262 │    812 │
│ 1084657 │    2262 │    345 │
│   56599 │    2260 │    799 │
│ 3271094 │    2256 │    812 │
└─────────┴─────────┴────────┘
```

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

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

تُرجع مصفوفة (أو مصفوفة متعددة الأبعاد) بالأبعاد نفسها مثل المصفوفة المصدر،
وتوضّح، لكل عنصر، ترتيبه بين العناصر ذات القيمة نفسها.
وتتيح تعداد مصفوفة متعددة الأبعاد مع إمكانية تحديد عمق البحث داخل المصفوفة.

**الصيغة**

```sql theme={null}
arrayEnumerateUniqRanked(clear_depth, arr, max_array_depth)
```

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

* `clear_depth` — رقّم العناصر في المستوى المحدد كلٌّ على حدة. عدد صحيح موجب أصغر من أو يساوي `max_arr_depth`. [`UInt*`](/ar/reference/data-types/int-uint)
* `arr` — مصفوفة متعددة الأبعاد المطلوب ترقيمها. [`Array(T)`](/ar/reference/data-types/array)
* `max_array_depth` — الحد الأقصى للعمق الفعّال. عدد صحيح موجب أصغر من أو يساوي عمق `arr`. [`UInt*`](/ar/reference/data-types/int-uint)

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

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

**أمثلة**

**المثال 1**

```sql title=Query theme={null}
-- With clear_depth=1 and max_array_depth=1, the result of arrayEnumerateUniqRanked
-- is identical to that which arrayEnumerateUniq would give for the same array.

SELECT arrayEnumerateUniqRanked(1, [1, 2, 1], 1);
```

```response title=Response theme={null}
[1, 1, 2]
```

**مثال 2**

```sql title=Query theme={null}
-- with clear_depth=1 and max_array_depth=1, the result of arrayEnumerateUniqRanked
-- is identical to that which arrayEnumerateUniqwould give for the same array.

SELECT arrayEnumerateUniqRanked(1, [[1, 2, 3], [2, 2, 1], [3]], 2);", "[[1, 1, 1], [2, 3, 2], [2]]
```

```response title=Response theme={null}
[1, 1, 2]
```

**مثال 3**

```sql title=Query theme={null}
-- In this example, arrayEnumerateUniqRanked is used to obtain an array indicating,
-- for each element of the multidimensional array, what its position is among elements
-- of the same value. For the first row of the passed array, [1, 2, 3], the corresponding
-- result is [1, 1, 1], indicating that this is the first time 1, 2 and 3 are encountered.
-- For the second row of the provided array, [2, 2, 1], the corresponding result is [2, 3, 3],
-- indicating that 2 is encountered for a second and third time, and 1 is encountered
-- for the second time. Likewise, for the third row of the provided array [3] the
-- corresponding result is [2] indicating that 3 is encountered for the second time.

SELECT arrayEnumerateUniqRanked(1, [[1, 2, 3], [2, 2, 1], [3]], 2);
```

```response title=Response theme={null}
[[1, 1, 1], [2, 3, 2], [2]]
```

**مثال 4**

```sql title=Query theme={null}
-- Changing clear_depth=2, results in elements being enumerated separately for each row.
SELECT arrayEnumerateUniqRanked(2,[[1, 2, 3],[2, 2, 1],[3]], 2);
```

```response title=Response theme={null}
[[1, 1, 1], [1, 2, 1], [1]]
```

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

أُضيف في: v25.9.0

يُرجع مصفوفة تحتوي على العناصر الموجودة في `source` وغير الموجودة في `except`، مع الحفاظ على ترتيبها الأصلي.

تُجري هذه الدالة عملية فرق بين مصفوفتين. ولكل عنصر في `source`، تتحقق مما إذا كان هذا العنصر موجودًا في `except` (باستخدام مقارنة تامة). وإذا لم يكن موجودًا، فسيُدرج في النتيجة.

تحافظ هذه العملية على الخصائص التالية:

1. يُحفَظ ترتيب العناصر القادمة من `source`
2. تُحفَظ العناصر المكررة في `source` إذا لم تكن موجودة في `except`
3. يُتعامل مع NULL بوصفه قيمة مستقلة

**الصياغة**

```sql theme={null}
arrayExcept(source, except)
```

**الوسائط**

* `source` — مصفوفة المصدر التي تحتوي على العناصر المطلوب تصفيتها.  [`Array(T)`](/ar/reference/data-types/array)
* `except` — المصفوفة التي تحتوي على العناصر المطلوب استبعادها من النتيجة.  [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة من النوع نفسه لمصفوفة الإدخال، وتحتوي على عناصر من `source` لم يُعثر عليها في `except`.  [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**أساسي**

```sql title=Query theme={null}
SELECT arrayExcept([1, 2, 3, 2, 4], [3, 5])
```

```response title=Response theme={null}
[1, 2, 2, 4]
```

**with\_nulls1**

```sql title=Query theme={null}
SELECT arrayExcept([1, NULL, 2, NULL], [2])
```

```response title=Response theme={null}
[1, NULL, NULL]
```

**with\_nulls2**

```sql title=Query theme={null}
SELECT arrayExcept([1, NULL, 2, NULL], [NULL, 2, NULL])
```

```response title=Response theme={null}
[1]
```

**السلاسل النصية**

```sql title=Query theme={null}
SELECT arrayExcept(['apple', 'banana', 'cherry'], ['banana', 'date'])
```

```response title=Response theme={null}
['apple', 'cherry']
```

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

قُدِّم في: v1.1.0

يعيد `1` إذا وُجد عنصر واحد على الأقل في المصفوفة المصدر بحيث تُعيد `func(x[, y1, y2, ... yN])` القيمة true. وإلا، يعيد `0`.

**البنية**

```sql theme={null}
arrayExists(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — دالة لامدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد `1` إذا أعادت دالة لامدا القيمة `true` لعنصر واحد على الأقل، و`0` خلاف ذلك [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayExists(x, y -> x=y, [1, 2, 3], [0, 0, 0])
```

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

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

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

تعالج الدالة `arrayFill` مصفوفة المصدر بالتسلسل من العنصر الأول
إلى العنصر الأخير، مع تقييم شرط دالة lambda عند كل موضع باستخدام عناصر من
مصفوفة المصدر ومصفوفات الشرط. عندما يُقيَّم شرط دالة lambda إلى false عند
الموضع i، تستبدل الدالة ذلك العنصر بالعنصر الموجود عند الموضع i-1
من الحالة الحالية للمصفوفة. ويُحفَظ العنصر الأول دائمًا
بغضّ النظر عن أي شرط.

**البنية**

```sql theme={null}
arrayFill(func(x [, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x [, y1, ..., yN])` — دالة لامدا `func(x [, y1, y2, ... yN]) → F(x [, y1, y2, ... yN])` تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشروط (`y`). [`دالة لامدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`دالة لامدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشروط التي توفّر وسائط إضافية لدالة لامدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال باستخدام مصفوفة واحدة**

```sql title=Query theme={null}
SELECT arrayFill(x -> not isNull(x), [1, null, 2, null]) AS res
```

```response title=Response theme={null}
[1, 1, 2, 2]
```

**مثال على مصفوفتين**

```sql title=Query theme={null}
SELECT arrayFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res
```

```response title=Response theme={null}
[5, 5, 6, 6]
```

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

متوفّرة منذ: v1.1.0

تُرجع مصفوفة تحتوي فقط على العناصر في المصفوفة المصدر التي تُرجع لها دالة لامبدا القيمة true.

**البنية**

```sql theme={null}
arrayFilter(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])]
```

**الوسائط**

* `func(x[, y1, ..., yN])` — دالة لامبدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — مصفوفة المصدر المراد معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسائط إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مجموعة فرعية من مصفوفة المصدر [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال 1**

```sql title=Query theme={null}
SELECT arrayFilter(x -> x LIKE '%World%', ['Hello', 'abc World']) AS res
```

```response title=Response theme={null}
['abc World']
```

**مثال 2**

```sql title=Query theme={null}
SELECT
    arrayFilter(
        (i, x) -> x LIKE '%World%',
        arrayEnumerate(arr),
        ['Hello', 'abc World'] AS arr)
    AS res
```

```response title=Response theme={null}
[2]
```

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

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

تُعيد أول عنصر في المصفوفة المصدر تُرجع له `func(x[, y1, y2, ... yN])` القيمة `true`، وإلا فتُعيد القيمة الافتراضية.

**الصيغة**

```sql theme={null}
arrayFirst(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x[, y1, ..., yN])` — دالة لامدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [دالة لامدا](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — مصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسائط إضافية لدالة لامدا. [`Array(T)`](/ar/reference/data-types/array).

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

تعيد أول عنصر من مصفوفة المصدر تتحقق له `λ`، وإلا تُعيد القيمة الافتراضية لـ `T`.

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayFirst(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```

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

**لا توجد مطابقة**

```sql title=Query theme={null}
SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```

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

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

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

تُرجِع فهرس أول عنصر في مصفوفة المصدر تُرجِع له `func(x[, y1, y2, ... yN])` القيمة `true`، وإلا فتُرجِع '0'.

**الصيغة**

```sql theme={null}
arrayFirstIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — دالة لامبدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [دالة لامبدا](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر معاملات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array).

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

يعيد فهرس أول عنصر في المصفوفة المصدر تكون فيه `func` مساوية لـ true، وإلا يعيد `0` [`UInt32`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```

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

**لا يوجد تطابق**

```sql title=Query theme={null}
SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f'])
```

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

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

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

تُرجع أول عنصر في مصفوفة المصدر تُرجع له الدالة `func(x[, y1, y2, ... yN])` القيمة `true`، وإلا فتُرجع `NULL`.

**البنية**

```sql theme={null}
arrayFirstOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — دالة لامبدا تعمل على عناصر المصفوفة المصدر (`x`) والمصفوفات الشرطية (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من المصفوفات الشرطية التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد العنصر الأول من المصفوفة المصدر الذي تكون `func` بالنسبة إليه `true`، وإلا فيعيد `NULL`.

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayFirstOrNull(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```

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

**لا يوجد تطابق**

```sql title=Query theme={null}
SELECT arrayFirstOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```

```response title=Response theme={null}
NULL Nullable(UInt8)
```

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

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

تحوّل مصفوفة من المصفوفات إلى مصفوفة مسطّحة.

الدالة:

* تنطبق على أي مستوى من تداخل المصفوفات.
* لا تغيّر المصفوفات المسطّحة أصلًا.

تحتوي المصفوفة المسطّحة على جميع العناصر من كل المصفوفات المُدخلة.

**البنية**

```sql theme={null}
arrayFlatten(arr)
```

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

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

* `arr` — مصفوفة متعددة الأبعاد. [`Array(Array(T))`](/ar/reference/data-types/array)

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

تُرجع مصفوفة مُسطَّحة من المصفوفة متعددة الأبعاد [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayFlatten([[[1]], [[2], [3]]]);
```

```response title=Response theme={null}
[1, 2, 3]
```

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

تم تقديمه في: v23.10.0

يطبّق دالة لامدا على مصفوفة واحدة أو أكثر من المصفوفات متساوية الحجم، ويجمع النتيجة في مُراكِم.

**الصيغة**

```sql theme={null}
arrayFold(λ(acc, x1 [, x2, x3, ... xN]), arr1 [, arr2, arr3, ... arrN], acc)
```

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

* `λ(x, x1 [, x2, x3, ... xN])` — دالة لامدا `λ(acc, x1 [, x2, x3, ... xN]) → F(acc, x1 [, x2, x3, ... xN])`، حيث تمثل `F` عمليةً تُطبَّق على `acc` وعلى قيم المصفوفة من `x`، مع إعادة استخدام الناتج في `acc`. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1 [, arr2, arr3, ... arrN]` — عدد N من المصفوفات التي تُطبَّق عليها العملية. [`Array(T)`](/ar/reference/data-types/array)
* `acc` — قيمة المُجمِّع، ويكون نوعها مطابقًا لنوع الإرجاع الخاص بدالة لامدا.

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

تُرجع القيمة النهائية `acc`.

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayFold(acc,x -> acc + x*2, [1, 2, 3, 4], 3::Int64) AS res;
```

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

**متتالية فيبوناتشي**

```sql title=Query theme={null}
SELECT arrayFold(acc, x -> (acc.2, acc.2 + acc.1),range(number),(1::Int64, 0::Int64)).1 AS fibonacci FROM numbers(1,10);
```

```response title=Response theme={null}
┌─fibonacci─┐
│         0 │
│         1 │
│         1 │
│         2 │
│         3 │
│         5 │
│         8 │
│        13 │
│        21 │
│        34 │
└───────────┘
```

**مثال على استخدام عدة مصفوفات**

```sql title=Query theme={null}
SELECT arrayFold(
(acc, x, y) -> acc + (x * y),
[1, 2, 3, 4],
[10, 20, 30, 40],
0::Int64
) AS res;
```

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

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

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

تأخذ عدة مصفوفات وتُرجِع مصفوفة تضم العناصر الموجودة في جميع المصفوفات المصدر. ولا تحتوي النتيجة إلا على قيم فريدة.

**البنية**

```sql theme={null}
arrayIntersect(arr, arr1, ..., arrN)
```

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

* `arrN` — ‏N من المصفوفات التي تُنشأ منها المصفوفة الجديدة. [`Array(T)`](/ar/reference/data-types/array).

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

تعيد مصفوفة تحتوي على عناصر مميزة موجودة في جميع المصفوفات N [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT
arrayIntersect([1, 2], [1, 3], [2, 3]) AS empty_intersection,
arrayIntersect([1, 2], [1, 3], [1, 4]) AS non_empty_intersection
```

```response title=Response theme={null}
┌─empty_intersection─┬─non_empty_intersection─┐
│ []                 │ [1]                    │
└────────────────────┴────────────────────────┘
```

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

أُضيف في: v23.7.0

يعيد [مؤشر Jaccard](https://en.wikipedia.org/wiki/Jaccard_index) لمصفوفتين.

**البنية**

```sql theme={null}
arrayJaccardIndex(arr_x, arr_y)
```

**الوسائط**

* `arr_x` — المصفوفة الأولى. [`Array(T)`](/ar/reference/data-types/array)
* `arr_y` — المصفوفة الثانية. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد قيمة مؤشر جاكارد لـ `arr_x` و`arr_y` من النوع [`Float64`](/ar/reference/data-types/float)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayJaccardIndex([1, 2], [2, 3]) AS res
```

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

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

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

تأخذ الدالة `arrayJoin` صفًا يحتوي على مصفوفة وتبسطه إلى عدة صفوف، بحيث يقابل كل عنصر في المصفوفة صفٌّ واحد.
وهذا بخلاف الدوال العادية في ClickHouse التي تربط قيم الإدخال بقيم الإخراج داخل الصف نفسه،
والدوال التجميعية التي تأخذ مجموعة من الصفوف وتقوم "بضغطها" أو "اختزالها" إلى صف تلخيصي واحد
(أو إلى قيمة واحدة داخل صف تلخيصي إذا استُخدمت مع `GROUP BY`).

تُنسخ جميع القيم في الأعمدة كما هي، باستثناء القيم الموجودة في العمود الذي تُطبَّق عليه هذه الدالة؛
إذ تُستبدل هذه القيم بقيمة العنصر المقابل في المصفوفة.

**الصياغة**

```sql theme={null}
arrayJoin(arr)
```

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

**الوسائط**

* `arr` — مصفوفة يُراد فردها. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجِع مجموعة من الصفوف الناتجة عن فرد `arr`.

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT arrayJoin([1, 2, 3] AS src) AS dst, 'Hello', src
```

```response title=Response theme={null}
┌─dst─┬─\'Hello\'─┬─src─────┐
│   1 │ Hello     │ [1,2,3] │
│   2 │ Hello     │ [1,2,3] │
│   3 │ Hello     │ [1,2,3] │
└─────┴───────────┴─────────┘
```

**arrayJoin يؤثر في جميع أجزاء الاستعلام**

```sql title=Query theme={null}
-- The arrayJoin function affects all sections of the query, including the WHERE section. Notice the result 2, even though the subquery returned 1 row.

SELECT sum(1) AS impressions
FROM
(
    SELECT ['Istanbul', 'Berlin', 'Bobruisk'] AS cities
)
WHERE arrayJoin(cities) IN ['Istanbul', 'Berlin'];
```

```response title=Response theme={null}
┌─impressions─┐
│           2 │
└─────────────┘
```

**استخدام دوال arrayJoin متعددة**

```sql title=Query theme={null}
- A query can use multiple arrayJoin functions. In this case, the transformation is performed multiple times and the rows are multiplied.

SELECT
    sum(1) AS impressions,
    arrayJoin(cities) AS city,
    arrayJoin(browsers) AS browser
FROM
(
    SELECT
        ['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
        ['Firefox', 'Chrome', 'Chrome'] AS browsers
)
GROUP BY
    2,
    3
```

```response title=Response theme={null}
┌─impressions─┬─city─────┬─browser─┐
│           2 │ Istanbul │ Chrome  │
│           1 │ Istanbul │ Firefox │
│           2 │ Berlin   │ Chrome  │
│           1 │ Berlin   │ Firefox │
│           2 │ Bobruisk │ Chrome  │
│           1 │ Bobruisk │ Firefox │
└─────────────┴──────────┴─────────┘
```

**نتائج غير متوقعة بسبب التحسينات**

```sql title=Query theme={null}
-- Using multiple arrayJoin with the same expression may not produce the expected result due to optimizations.
-- For these cases, consider modifying the repeated array expression with extra operations that do not affect join result.
- e.g. arrayJoin(arraySort(arr)), arrayJoin(arrayConcat(arr, []))

SELECT
    arrayJoin(dice) as first_throw,
    /* arrayJoin(dice) as second_throw */ -- is technically correct, but will annihilate result set
    arrayJoin(arrayConcat(dice, [])) as second_throw -- intentionally changed expression to force re-evaluation
FROM (
    SELECT [1, 2, 3, 4, 5, 6] as dice
);
```

```response title=Response theme={null}
┌─first_throw─┬─second_throw─┐
│           1 │            1 │
│           1 │            2 │
│           1 │            3 │
│           1 │            4 │
│           1 │            5 │
│           1 │            6 │
│           2 │            1 │
│           2 │            2 │
│           2 │            3 │
│           2 │            4 │
│           2 │            5 │
│           2 │            6 │
│           3 │            1 │
│           3 │            2 │
│           3 │            3 │
│           3 │            4 │
│           3 │            5 │
│           3 │            6 │
│           4 │            1 │
│           4 │            2 │
│           4 │            3 │
│           4 │            4 │
│           4 │            5 │
│           4 │            6 │
│           5 │            1 │
│           5 │            2 │
│           5 │            3 │
│           5 │            4 │
│           5 │            5 │
│           5 │            6 │
│           6 │            1 │
│           6 │            2 │
│           6 │            3 │
│           6 │            4 │
│           6 │            5 │
│           6 │            6 │
└─────────────┴──────────────┘
```

**استخدام بنية ARRAY JOIN**

```sql title=Query theme={null}
-- Note the ARRAY JOIN syntax in the `SELECT` query below, which provides broader possibilities.
-- ARRAY JOIN allows you to convert multiple arrays with the same number of elements at a time.

SELECT
    sum(1) AS impressions,
    city,
    browser
FROM
(
    SELECT
        ['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
        ['Firefox', 'Chrome', 'Chrome'] AS browsers
)
ARRAY JOIN
    cities AS city,
    browsers AS browser
GROUP BY
    2,
    3
```

```response title=Response theme={null}
┌─impressions─┬─city─────┬─browser─┐
│           1 │ Istanbul │ Firefox │
│           1 │ Berlin   │ Chrome  │
│           1 │ Bobruisk │ Chrome  │
└─────────────┴──────────┴─────────┘
```

**استخدام Tuple**

```sql title=Query theme={null}
-- You can also use Tuple

SELECT
    sum(1) AS impressions,
    (arrayJoin(arrayZip(cities, browsers)) AS t).1 AS city,
    t.2 AS browser
FROM
(
    SELECT
        ['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
        ['Firefox', 'Chrome', 'Chrome'] AS browsers
)
GROUP BY
    2,
    3
```

```response title=Response theme={null}
┌─impressions─┬─city─────┬─browser─┐
│           1 │ Istanbul │ Firefox │
│           1 │ Berlin   │ Chrome  │
│           1 │ Bobruisk │ Chrome  │
└─────────────┴──────────┴─────────┘
```

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

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

تُرجِع آخر عنصر في المصفوفة المصدر تُرجِع له دالة لامبدا `func(x [, y1, y2, ... yN])` القيمة `true`، وإلا فتُرجِع قيمة افتراضية.

**الصياغة**

```sql theme={null}
arrayLast(func(x[, y1, ..., yN]), source[, cond1, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — دالة لامبدا تُطبَّق على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [دالة لامبدا](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source` — المصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array). - `[, cond1, ... , condN]` — اختياري. N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array).

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

تعيد آخر عنصر من المصفوفة المصدر تكون `func` صحيحةً له، وإلا فتعيد القيمة الافتراضية لـ `T`.

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayLast(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c'])
```

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

**لا يوجد تطابق**

```sql title=Query theme={null}
SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```

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

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

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

تُرجع فهرس آخر عنصر في المصفوفة المصدر تُرجع الدالة `func(x[, y1, y2, ... yN])` له القيمة `true`، وإلا فتُرجع '0'.

**البنية**

```sql theme={null}
arrayLastIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — دالة لامبدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — مصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد فهرس آخر عنصر في مصفوفة المصدر تكون الدالة `func` صحيحة له، وإلا يعيد `0` [`UInt32`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayLastIndex(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c']);
```

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

**لا توجد مطابقة**

```sql title=Query theme={null}
SELECT arrayLastIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f']);
```

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

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

أُضيف في: v1.1.0

يعيد آخر عنصر في المصفوفة الأصلية تُرجع له دالة lambda `func(x [, y1, y2, ... yN])` القيمة `true`، وإلا فيُرجع `NULL`.

**البنية**

```sql theme={null}
arrayLastOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x [, y1, ..., yN])` — دالة لامبدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [دالة لامبدا](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — المصفوفة المصدر المراد معالجتها. [`Array(T)`](/ar/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array).

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

تعيد آخر عنصر من المصفوفة المصدر لا تكون قيمة `λ` له `true`، وإلا فتعيد `NULL`.

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayLastOrNull(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c'])
```

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

**لا يوجد تطابق**

```sql title=Query theme={null}
SELECT arrayLastOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```

```response title=Response theme={null}
NULL Nullable(UInt8)
```

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

قُدِّمت في: v25.4.0

تحسب مسافة Levenshtein بين مصفوفتين.

**البنية**

```sql theme={null}
arrayLevenshteinDistance(from, to)
```

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

* `from` — المصفوفة الأولى. [`Array(T)`](/ar/reference/data-types/array). - `to` — المصفوفة الثانية. [`Array(T)`](/ar/reference/data-types/array).

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

مسافة Levenshtein بين المصفوفتين الأولى والثانية. [`Float64`](/ar/reference/data-types/float)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayLevenshteinDistance([1, 2, 4], [1, 2, 3])
```

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

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

قُدِّمت في: v25.4.0

تحسب مسافة ليفنشتاين لمصفوفتين باستخدام أوزان مخصصة لكل عنصر.
يجب أن يتطابق عدد عناصر المصفوفة مع عدد الأوزان الخاصة بها.

**الصيغة**

```sql theme={null}
arrayLevenshteinDistanceWeighted(from, to, from_weights, to_weights)
```

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

* `from` — المصفوفة الأولى. [`Array(T)`](/ar/reference/data-types/array). - `to` — المصفوفة الثانية. [`Array(T)`](/ar/reference/data-types/array). - `from_weights` — أوزان المصفوفة الأولى. [`Array((U)Int*|Float*)`](/ar/reference/data-types/array)
* `to_weights` — أوزان المصفوفة الثانية. [`Array((U)Int*|Float*)`](/ar/reference/data-types/array)

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

مسافة Levenshtein بين المصفوفتين الأولى والثانية مع أوزان مخصّصة لكل عنصر [`Float64`](/ar/reference/data-types/float)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayLevenshteinDistanceWeighted(['A', 'B', 'C'], ['A', 'K', 'L'], [1.0, 2, 3], [3.0, 4, 5])
```

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

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

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

تُرجِع مصفوفةً ناتجةً من المصفوفات الأصلية بتطبيق دالة لامدا على كل عنصر.

**البنية**

```sql theme={null}
arrayMap(func, arr)
```

**الوسائط**

* `func` — دالة لامبدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr` — عدد N من المصفوفات المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة من نتائج دالة لامبدا [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayMap(x -> (x + 2), [1, 2, 3]) as res;
```

```response title=Response theme={null}
[3, 4, 5]
```

**إنشاء tuple من عناصر مأخوذة من مصفوفات مختلفة**

```sql title=Query theme={null}
SELECT arrayMap((x, y) -> (x, y), [1, 2, 3], [4, 5, 6]) AS res
```

```response title=Response theme={null}
[(1, 4),(2, 5),(3, 6)]
```

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

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

تُرجع أكبر عنصر في مصفوفة الإدخال.

إذا جرى تحديد دالة لامدا `func`، فتُرجع أكبر عنصر من نتائج دالة لامدا.

**الصياغة**

```sql theme={null}
arrayMax([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — اختياري. دالة لامدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشروط (`y`). [`دالة لامدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. N من مصفوفات الشروط التي توفّر وسيطات إضافية لدالة لامدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد أكبر عنصر في المصفوفة المصدر، أو أكبر عنصر من نتائج دالة لامدا إذا تم توفيرها.

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT arrayMax([5, 3, 2, 7]);
```

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

**الاستخدام مع دالة Lambda**

```sql title=Query theme={null}
SELECT arrayMax(x, y -> x/y, [4, 8, 12, 16], [1, 2, 1, 2]);
```

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

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

ظهر لأول مرة في: v21.1.0

يُرجع أصغر عنصر في المصفوفة المصدر.

إذا تم تحديد دالة لامبدا `func`، فسيُرجع أصغر عنصر من نتائج دالة لامبدا.

**البنية**

```sql theme={null}
arrayMin([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x[, y1, ..., yN])` — اختياري. دالة لامبدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — مصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `cond1_arr, ...` — اختياري. عدد N من مصفوفات الشرط التي توفّر معاملات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد أصغر عنصر في مصفوفة المصدر، أو أصغر عنصر من نتائج دالة لامبدا إذا تم توفيرها.

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT arrayMin([5, 3, 2, 7]);
```

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

**الاستخدام مع دالة lambda**

```sql title=Query theme={null}
SELECT arrayMin(x, y -> x/y, [4, 8, 12, 16], [1, 2, 1, 2]);
```

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

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

قُدِّم في: v25.1.0

يحسب معامل جيني المُطبَّع.

**الصيغة**

```sql theme={null}
arrayNormalizedGini(predicted, label)
```

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

* `predicted` — القيمة المتوقعة. [`Array(T)`](/ar/reference/data-types/array)
* `label` — القيمة الفعلية. [`Array(T)`](/ar/reference/data-types/array)

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

`Tuple` يحتوي على معاملات جيني للقيم المتوقعة، ومعامل جيني للقيم المُطبَّعة، ومعامل جيني المُطبَّع (= نسبة معاملي جيني السابقين) [`Tuple(Float64, Float64, Float64)`](/ar/reference/data-types/tuple)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayNormalizedGini([0.9, 0.3, 0.8, 0.7],[6, 1, 0, 2]);
```

```response title=Response theme={null}
(0.18055555555555558, 0.2638888888888889, 0.6842105263157896)
```

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

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

هذه الدالة مماثلة لـ `arrayReverseSort`، ولكنها تتضمن وسيطة `limit` إضافية تتيح الفرز الجزئي.

<Tip>
  للاحتفاظ بالعناصر المُرتَّبة فقط، استخدم `arrayResize`.
</Tip>

**البنية**

```sql theme={null}
arrayPartialReverseSort([f,] limit, arr [, arr1, ... ,arrN])
```

**الوسائط**

* `f(arr[, arr1, ... ,arrN])` — دالة لامدا المطلوب تطبيقها على عناصر المصفوفة `x`. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — قيمة الفهرس التي يُجرى الفرز حتى الوصول إليها. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `arr` — المصفوفة المطلوب فرزها. [`Array(T)`](/ar/reference/data-types/array)
* `arr1, ... ,arrN` — `N` من المصفوفات الإضافية، في حال كانت `f` تقبل عدة وسائط. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفةً بالحجم نفسه للمصفوفة الأصلية، بحيث تكون العناصر ضمن النطاق `[1..limit]` مرتبة
ترتيبًا تنازليًا. أما العناصر المتبقية `(limit..N]` فتكون بترتيب غير محدد.

**أمثلة**

**simple\_int**

```sql title=Query theme={null}
SELECT arrayPartialReverseSort(2, [5, 9, 1, 3])
```

```response title=Response theme={null}
[9, 5, 1, 3]
```

**simple\_string**

```sql title=Query theme={null}
SELECT arrayPartialReverseSort(2, ['expenses','lasso','embolism','gladly'])
```

```response title=Response theme={null}
['lasso','gladly','expenses','embolism']
```

**retain\_sorted**

```sql title=Query theme={null}
SELECT arrayResize(arrayPartialReverseSort(2, [5, 9, 1, 3]), 2)
```

```response title=Response theme={null}
[9, 5]
```

**lambda\_simple**

```sql title=Query theme={null}
SELECT arrayPartialReverseSort((x) -> -x, 2, [5, 9, 1, 3])
```

```response title=Response theme={null}
[1, 3, 5, 9]
```

**lambda\_complex**

```sql title=Query theme={null}
SELECT arrayPartialReverseSort((x, y) -> -y, 1, [0, 1, 2], [1, 2, 3]) as res
```

```response title=Response theme={null}
[0, 1, 2]
```

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

أُضيف في: v23.2.0

تعيد هذه الدالة مصفوفة بالحجم نفسه للمصفوفة الأصلية، بحيث تكون العناصر ضمن النطاق `[1..limit]` مجموعة فرعية عشوائية
من المصفوفة الأصلية. أما العناصر المتبقية ضمن `(limit..n]` فتحتوي على العناصر غير الموجودة في النطاق `[1..limit]` بترتيب غير محدد.
يجب أن تكون قيمة `limit` ضمن النطاق `[1..n]`. أما القيم الواقعة خارج هذا النطاق فتعادل تنفيذ `arrayShuffle` بالكامل:

<Note>
  لن تُجسِّد هذه الدالة الثوابت.

  يجب أن تكون قيمة `limit` ضمن النطاق `[1..N]`. أما القيم الواقعة خارج هذا النطاق فتعادل تنفيذ [`arrayShuffle`](#arrayShuffle) بالكامل.
</Note>

**الصياغة**

```sql theme={null}
arrayPartialShuffle(arr [, limit[, seed]])
```

**الوسائط**

* `arr` — المصفوفة المراد خلط عناصرها. [`Array(T)`](/ar/reference/data-types/array)
* `seed` — اختياري. البذرة المستخدمة في توليد الأرقام العشوائية. وإذا لم تُوفَّر، تُستخدم بذرة عشوائية. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `limit` — اختياري. العدد الذي يُستخدم لتقييد عدد تبديلات العناصر، ضمن النطاق `[1..N]`. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

مصفوفة عناصرها مخلوطة جزئيًا. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**no\_limit1**

```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4], 0)
```

```response title=Response theme={null}
[2, 4, 3, 1]
```

**no\_limit2**

```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4])
```

```response title=Response theme={null}
[4, 1, 3, 2]
```

**random\_seed**

```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4], 2)
```

```response title=Response theme={null}
[3, 4, 1, 2]
```

**explicit\_seed**

```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4], 2, 41)
```

```response title=Response theme={null}
[3, 2, 1, 4]
```

**materialize**

```sql title=Query theme={null}
SELECT arrayPartialShuffle(materialize([1, 2, 3, 4]), 2, 42), arrayPartialShuffle([1, 2, 3], 2, 42) FROM numbers(10)
```

```response title=Response theme={null}
┌─arrayPartial⋯4]), 2, 42)─┬─arrayPartial⋯ 3], 2, 42)─┐
│ [3,2,1,4]                │ [3,2,1]                  │
│ [3,2,1,4]                │ [3,2,1]                  │
│ [4,3,2,1]                │ [3,2,1]                  │
│ [1,4,3,2]                │ [3,2,1]                  │
│ [3,4,1,2]                │ [3,2,1]                  │
│ [1,2,3,4]                │ [3,2,1]                  │
│ [1,4,3,2]                │ [3,2,1]                  │
│ [1,4,3,2]                │ [3,2,1]                  │
│ [3,1,2,4]                │ [3,2,1]                  │
│ [1,3,2,4]                │ [3,2,1]                  │
└──────────────────────────┴──────────────────────────┘
```

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

تم تقديمها في: v23.2.0

هذه الدالة مماثلة لـ `arraySort`، ولكنها تتضمن وسيطة `limit` إضافية تتيح الفرز الجزئي.

<Tip>
  للاحتفاظ بالعناصر المفروزة فقط، استخدم `arrayResize`.
</Tip>

**الصياغة**

```sql theme={null}
arrayPartialSort([f,] limit, arr [, arr1, ... ,arrN])
```

**الوسائط**

* `f(arr[, arr1, ... ,arrN])` — دالة لامبدا المُطبَّقة على عناصر المصفوفة `x`. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — قيمة الفهرس التي سيجري الفرز حتى الوصول إليها. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `arr` — المصفوفة المطلوب فرزها. [`Array(T)`](/ar/reference/data-types/array)
* `arr1, ... ,arrN` — عدد N من المصفوفات الإضافية، في حال كانت `f` تقبل عدة وسائط. [`Array(T)`](/ar/reference/data-types/array)

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

تُعيد مصفوفة بالحجم نفسه للمصفوفة الأصلية، بحيث تكون العناصر ضمن النطاق `[1..limit]` مرتبة
ترتيبًا تصاعديًا. أما العناصر المتبقية `(limit..N]` فتكون بترتيب غير محدد.

**أمثلة**

**simple\_int**

```sql title=Query theme={null}
SELECT arrayPartialSort(2, [5, 9, 1, 3])
```

```response title=Response theme={null}
[1, 3, 5, 9]
```

**simple\_string**

```sql title=Query theme={null}
SELECT arrayPartialSort(2, ['expenses', 'lasso', 'embolism', 'gladly'])
```

```response title=Response theme={null}
['embolism', 'expenses', 'gladly', 'lasso']
```

**retain\_sorted**

```sql title=Query theme={null}
SELECT arrayResize(arrayPartialSort(2, [5, 9, 1, 3]), 2)
```

```response title=Response theme={null}
[1, 3]
```

**lambda\_simple**

```sql title=Query theme={null}
SELECT arrayPartialSort((x) -> -x, 2, [5, 9, 1, 3])
```

```response title=Response theme={null}
[9, 5, 1, 3]
```

**lambda\_complex**

```sql title=Query theme={null}
SELECT arrayPartialSort((x, y) -> -y, 1, [0, 1, 2], [1, 2, 3]) as res
```

```response title=Response theme={null}
[2, 1, 0]
```

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

تم تقديمه في: v1.1.0

يزيل العنصر الأخير من المصفوفة.

**الصيغة**

```sql theme={null}
arrayPopBack(arr)
```

**الوسائط**

* `arr` — المصفوفة التي يُزال منها العنصر الأخير. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد مصفوفة مطابقة لـ `arr` ولكن من دون العنصر الأخير منها [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayPopBack([1, 2, 3]) AS res;
```

```response title=Response theme={null}
[1, 2]
```

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

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

يزيل العنصر الأول من المصفوفة.

**الصياغة**

```sql theme={null}
arrayPopFront(arr)
```

**الوسائط**

* `arr` — المصفوفة التي يُزال منها العنصر الأول. [`Array(T)`](/ar/reference/data-types/array)

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

يُرجع مصفوفة مطابقة لـ `arr` ولكن من دون العنصر الأول فيها [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayPopFront([1, 2, 3]) AS res;
```

```response title=Response theme={null}
[2, 3]
```

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

مُقدَّم في: v21.1.0

يُرجِع حاصل ضرب عناصر المصفوفة المصدر.

إذا جرى تحديد دالة لامبدا `func`، فإنه يُرجِع حاصل ضرب عناصر نتائج اللامبدا.

**الصياغة**

```sql theme={null}
arrayProduct([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x[, y1, ..., yN])` — اختياري. دالة لامدا تعمل على عناصر مصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — مصفوفة المصدر المراد معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. ‏N من مصفوفات الشرط التي توفّر وسائط إضافية لدالة لامدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد حاصل ضرب العناصر في مصفوفة المصدر، أو حاصل ضرب العناصر الناتجة عن دالة لامدا إذا تم توفيرها. [`Float64`](/ar/reference/data-types/float)

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT arrayProduct([1, 2, 3, 4]);
```

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

**الاستخدام مع دالة lambda**

```sql title=Query theme={null}
SELECT arrayProduct(x, y -> x+y, [2, 2], [2, 2]) AS res;
```

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

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

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

تُضيف عنصرًا واحدًا إلى نهاية المصفوفة.

**الصيغة**

```sql theme={null}
arrayPushBack(arr, x)
```

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

* `arr` — المصفوفة التي تُضاف القيمة `x` إلى نهايتها. [`Array(T)`](/ar/reference/data-types/array)
* `x` —
* قيمة واحدة تُضاف إلى نهاية المصفوفة. [`Array(T)`](/ar/reference/data-types/array).

<Note>
  - لا يمكن إضافة سوى الأرقام إلى مصفوفة أرقام، ولا يمكن إضافة سوى السلاسل النصية إلى مصفوفة سلاسل نصية.
  - عند إضافة الأرقام، يحدّد ClickHouse تلقائيًا نوع `x` وفقًا لنوع بيانات المصفوفة.
  - يمكن أن تكون `NULL`. تضيف الدالة عنصرًا من نوع `NULL` إلى المصفوفة، ويتحوّل نوع عناصر المصفوفة إلى `Nullable`.

  لمزيد من المعلومات حول أنواع البيانات في ClickHouse، راجع [أنواع البيانات](/ar/reference/data-types/index).
</Note>

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

تعيد مصفوفة مطابقة لـ `arr` ولكن مع إضافة القيمة `x` إلى نهاية المصفوفة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayPushBack(['a'], 'b') AS res;
```

```response title=Response theme={null}
['a','b']
```

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

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

تضيف عنصرًا واحدًا إلى بداية المصفوفة.

**الصياغة**

```sql theme={null}
arrayPushFront(arr, x)
```

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

* `arr` — المصفوفة التي تُضاف القيمة `x` إلى نهايتها. [`Array(T)`](/ar/reference/data-types/array). - `x` —
* قيمة مفردة تُضاف إلى بداية المصفوفة. [`Array(T)`](/ar/reference/data-types/array).

<Note>
  - لا يمكن إضافة سوى الأرقام إلى مصفوفة أرقام، ولا يمكن إضافة سوى السلاسل النصية إلى مصفوفة سلاسل نصية.
  - عند إضافة أرقام، يحدّد ClickHouse تلقائيًا نوع `x` وفقًا لنوع بيانات المصفوفة.
  - يمكن أن تكون `NULL`. تضيف الدالة عنصر `NULL` إلى المصفوفة، ويتحوّل نوع عناصر المصفوفة إلى `Nullable`.

  لمزيد من المعلومات حول أنواع البيانات في ClickHouse، راجع [أنواع البيانات](/ar/reference/data-types/index).
</Note>

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

تعيد مصفوفة مطابقة لـ `arr`، ولكن مع قيمة إضافية `x` في بداية المصفوفة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayPushFront(['b'], 'a') AS res;
```

```response title=Response theme={null}
['a','b']
```

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

استُحدث في: v20.4.0

يحسب المساحة تحت منحنى خصائص تشغيل المستقبِل (ROC).
يُنشأ منحنى ROC برسم معدل الإيجابيات الحقيقية (TPR) على المحور y ومعدل الإيجابيات الكاذبة (FPR) على المحور x عبر جميع العتبات.
وتتراوح القيمة الناتجة بين صفر وواحد، وتشير القيمة الأعلى إلى أداء أفضل للنموذج.

يُعد ROC AUC (ويُعرف أيضًا اختصارًا باسم AUC) مفهومًا في تعلّم الآلة.
لمزيد من التفاصيل، يُرجى الاطلاع [هنا](https://developers.google.com/machine-learning/glossary#pr-auc-area-under-the-pr-curve)، و[هنا](https://developers.google.com/machine-learning/crash-course/classification/roc-and-auc#expandable-1)، و[هنا](https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve).

**الصيغة**

```sql theme={null}
arrayROCAUC(scores, labels[, scale[, partial_offsets]])
```

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

**الوسائط**

* `scores` — الدرجات التي ينتجها نموذج التنبؤ. [`Array((U)Int*)`](/ar/reference/data-types/array) أو [`Array(Float*)`](/ar/reference/data-types/array)
* `labels` — تسميات العينات، وعادةً تكون 1 للعينة الإيجابية و0 للعينة السلبية. [`Array((U)Int*)`](/ar/reference/data-types/array) أو [`Enum`](/ar/reference/data-types/enum)
* `scale` — اختياري. يحدد ما إذا كان سيُرجِع المساحة المُطبَّعة. إذا كانت القيمة false، فسيُرجِع بدلًا من ذلك المساحة تحت منحنى TP (الإيجابيات الحقيقية) × FP (الإيجابيات الكاذبة). القيمة الافتراضية: true. [`Bool`](/ar/reference/data-types/boolean)
* `partial_offsets` —
* مصفوفة من أربعة أعداد صحيحة غير سالبة تُستخدم لحساب مساحة جزئية تحت منحنى ROC (وهو ما يعادل شريطًا رأسيًا في فضاء ROC) بدلًا من AUC بالكامل. يفيد هذا الخيار في الحساب الموزع لـ ROC AUC. يجب أن تحتوي المصفوفة على العناصر التالية \[`higher_partitions_tp`, `higher_partitions_fp`, `total_positives`, `total_negatives`]. [Array](/ar/reference/data-types/array) من [Integers](/ar/reference/data-types/int-uint) غير سالبة. اختياري.
  * `higher_partitions_tp`: عدد التسميات الإيجابية في الأقسام ذات الدرجات الأعلى.
  * `higher_partitions_fp`: عدد التسميات السلبية في الأقسام ذات الدرجات الأعلى.
  * `total_positives`: العدد الإجمالي للعينات الإيجابية في مجموعة البيانات بالكامل.
  * `total_negatives`: العدد الإجمالي للعينات السلبية في مجموعة البيانات بالكامل.

<Note>
  عند استخدام `arr_partial_offsets`، يجب أن يكون كل من `arr_scores` و `arr_labels` مجرد قسم من مجموعة البيانات بالكامل، وأن يحتوي على نطاق من الدرجات.
  يجب تقسيم مجموعة البيانات إلى أقسام متجاورة، بحيث يحتوي كل قسم على مجموعة فرعية من البيانات تقع درجاتها ضمن نطاق محدد.
  على سبيل المثال:

  * قد يحتوي أحد الأقسام على جميع الدرجات ضمن النطاق \[0, 0.5).
  * وقد يحتوي قسم آخر على الدرجات ضمن النطاق \[0.5, 1.0].
</Note>

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

تُرجِع المساحة تحت منحنى خصائص تشغيل المستقبل (ROC). [`Float64`](/ar/reference/data-types/float)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayROCAUC([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1]);
```

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

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

أُضيفت في: v23.10.0

تعيد مجموعة فرعية تضم `samples` عنصرًا عشوائيًا من مصفوفة الإدخال. وإذا كانت قيمة `samples` أكبر من حجم مصفوفة الإدخال، فسيُقتصر حجم العينة على حجم المصفوفة، أي ستُعاد جميع عناصر المصفوفة، ولكن من دون ضمان ترتيبها. ويمكن للدالة التعامل مع كلٍّ من المصفوفات المسطحة والمصفوفات المتداخلة.

**البنية**

```sql theme={null}
arrayRandomSample(arr, samples)
```

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

* `arr` — مصفوفة الإدخال أو المصفوفة متعددة الأبعاد التي تُؤخذ منها عيّنة من العناصر. [`Array(T)`](/ar/reference/data-types/array)
* `samples` — عدد العناصر التي ستُدرج في العيّنة العشوائية. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

مصفوفة تحتوي على عيّنة عشوائية من عناصر مصفوفة الإدخال [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayRandomSample(['apple', 'banana', 'cherry', 'date'], 2) as res;
```

```response title=Response theme={null}
['cherry','apple']
```

**استخدام مصفوفة متعددة الأبعاد**

```sql title=Query theme={null}
SELECT arrayRandomSample([[1, 2], [3, 4], [5, 6]], 2) as res;
```

```response title=Response theme={null}
[[3,4],[5,6]]
```

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

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

تُطبِّق دالة تجميع على عناصر المصفوفة وتُرجِع ناتجها.
يُمرَّر اسم دالة التجميع كسلسلة نصية بين علامتَي اقتباس مفردتَين `'max'`، `'sum'`.
عند استخدام الدوال التجميعية ذات المعلمات، تُحدَّد المعلمة بعد اسم الدالة بين قوسين `'uniqUpTo(6)'`.

**البنية**

```sql theme={null}
arrayReduce(agg_f, arr1[, arr2, ... , arrN])
```

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

* `agg_f` — اسم دالة تجميع، ويجب أن يكون قيمة ثابتة. [`String`](/ar/reference/data-types/string)
* `arr1[, arr2, ... , arrN]` — `N` مصفوفات تقابل وسيطات `agg_f`. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد ناتج دالة التجميع

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayReduce('max', [1, 2, 3]);
```

```response title=Response theme={null}
┌─arrayReduce('max', [1, 2, 3])─┐
│                             3 │
└───────────────────────────────┘
```

**مثال على استخدام دالة تجميعية بعدة وسيطات**

```sql title=Query theme={null}
--If an aggregate function takes multiple arguments, then this function must be applied to multiple arrays of the same size.

SELECT arrayReduce('maxIf', [3, 5], [1, 0]);
```

```response title=Response theme={null}
┌─arrayReduce('maxIf', [3, 5], [1, 0])─┐
│                                    3 │
└──────────────────────────────────────┘
```

**مثال على دالة تجميع مُعامِلية**

```sql title=Query theme={null}
SELECT arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
```

```response title=Response theme={null}
┌─arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])─┐
│                                                           4 │
└─────────────────────────────────────────────────────────────┘
```

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

قُدِّمت في: v20.4.0

تُطبِّق دالةً تجميعية على عناصر المصفوفة ضمن النطاقات المحددة، وتُرجِع مصفوفةً تتضمن النتيجة المقابلة لكل نطاق.
تُرجِع الدالة النتيجة نفسها كما لو استُخدم `arrayReduce(agg_func, arraySlice(arr1, index, length), ...)` عدة مرات.

**الصياغة**

```sql theme={null}
arrayReduceInRanges(agg_f, ranges, arr1[, arr2, ... ,arrN])
```

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

* `agg_f` — اسم الدالة التجميعية المراد استخدامها. [`String`](/ar/reference/data-types/string)
* `ranges` — النطاق الذي سيُجرى عليه التجميع. وهي مصفوفة من قيم Tuple، `(i, r)`، تحتوي على الفهرس `i` الذي يبدأ منه التجميع، والنطاق `r` الذي سيُجرى عليه التجميع. [`Array(T)`](/ar/reference/data-types/array) أو [`Tuple(T)`](/ar/reference/data-types/tuple)
* `arr1[, arr2, ... ,arrN]` — عدد N من المصفوفات كوسيطات للدالة التجميعية. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة تحتوي على نتائج الدالة التجميعية عبر النطاقات المحددة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayReduceInRanges(
    'sum',
    [(1, 5), (2, 3), (3, 4), (4, 4)],
    [1000000, 200000, 30000, 4000, 500, 60, 7]
) AS res
```

```response title=Response theme={null}
┌─res─────────────────────────┐
│ [1234500,234000,34560,4567] │
└─────────────────────────────┘
```

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

أُضيفت في: v25.11.0

تزيل جميع العناصر التي تساوي قيمةً معيّنة من المصفوفة.
تُعامل قيم NULL على أنها متساوية.

**الصيغة**

```sql theme={null}
arrayRemove(arr, elem)
```

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

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

* `arr` — Array(T) - `elem` — T

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

تعيد جزءًا فرعيًا من المصفوفة المصدر [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال 1**

```sql title=Query theme={null}
SELECT arrayRemove([1, 2, 2, 3], 2)
```

```response title=Response theme={null}
[1, 3]
```

**مثال 2**

```sql title=Query theme={null}
SELECT arrayRemove(['a', NULL, 'b', NULL], NULL)
```

```response title=Response theme={null}
['a', 'b']
```

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

أُضيف في: v1.1.0

يغيّر طول المصفوفة.

**الصياغة**

```sql theme={null}
arrayResize(arr, size[, extender])
```

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

* `arr` — المصفوفة المطلوب تغيير حجمها. [`Array(T)`](/ar/reference/data-types/array)
* `size` —
  -الطول الجديد للمصفوفة.
  إذا كانت `size` أصغر من الحجم الأصلي للمصفوفة، فسيتم اقتطاع المصفوفة من اليمين.
  إذا كانت `size` أكبر من الحجم الأصلي للمصفوفة، فسيتم تمديد المصفوفة إلى اليمين باستخدام قيم `extender` أو القيم الافتراضية لنوع بيانات عناصر المصفوفة.
* `extender` — القيمة المستخدمة لتمديد المصفوفة. يمكن أن تكون `NULL`.

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

مصفوفة بطول `size`. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال 1**

```sql title=Query theme={null}
SELECT arrayResize([1], 3);
```

```response title=Response theme={null}
[1,0,0]
```

**المثال 2**

```sql title=Query theme={null}
SELECT arrayResize([1], 3, NULL);
```

```response title=Response theme={null}
[1,NULL,NULL]
```

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

أُضيف في: v1.1.0

يعكس ترتيب عناصر المصفوفة المعطاة.

<Note>
  تؤدي الدالة `reverse(arr)` الوظيفة نفسها، لكنها تعمل أيضًا على أنواع بيانات أخرى
  بالإضافة إلى المصفوفات.
</Note>

**الصيغة**

```sql theme={null}
arrayReverse(arr)
```

**الوسائط**

* `arr` — المصفوفة المراد عكسها. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة بالحجم نفسه للمصفوفة الأصلية، وتحتوي على العناصر بترتيب عكسي. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayReverse([1, 2, 3])
```

```response title=Response theme={null}
[3,2,1]
```

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

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

تعالج الدالة `arrayReverseFill` مصفوفة المصدر تسلسليًا من العنصر
الأخير إلى الأول، مع تقييم شرط lambda عند كل موضع باستخدام عناصر
من مصفوفة المصدر ومصفوفات الشرط. عندما يُقيَّم الشرط إلى القيمة false عند
الموضع i، تستبدل الدالة ذلك العنصر بالعنصر الموجود عند الموضع i+1
من الحالة الحالية للمصفوفة. ويُحفَظ العنصر الأخير دائمًا
بغض النظر عن أي شرط.

**البنية**

```sql theme={null}
arrayReverseFill(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x[, y1, ..., yN])` — دالة لامبدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المراد معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — اختياري. N من مصفوفات الشرط التي توفّر وسائط إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفةً تُستبدل فيها عناصر المصفوفة المصدر بنتائج دالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال باستخدام مصفوفة واحدة**

```sql title=Query theme={null}
SELECT arrayReverseFill(x -> not isNull(x), [1, null, 2, null]) AS res
```

```response title=Response theme={null}
[1, 2, 2, NULL]
```

**مثال على مصفوفتين**

```sql title=Query theme={null}
SELECT arrayReverseFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res;
```

```response title=Response theme={null}
[5, 6, 6, 2]
```

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

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

ترتّب عناصر المصفوفة ترتيبًا تنازليًا.
إذا جرى تحديد الدالة `f`، فستُرتَّب المصفوفة المعطاة وفقًا لنتيجة
تطبيق الدالة على عناصر المصفوفة، ثم تُعكس المصفوفة بعد ترتيبها.
إذا كانت `f` تقبل عدة وسائط، فستُمرَّر عدة مصفوفات إلى الدالة `arrayReverseSort`
بحيث تقابل وسائط `func` هذه المصفوفات.

إذا كانت المصفوفة المطلوب ترتيبها تحتوي على `-Inf` أو `NULL` أو `NaN` أو `Inf`، فسيكون ترتيبها كما يلي:

1. `-Inf`
2. `Inf`
3. `NaN`
4. `NULL`

تُعد `arrayReverseSort` [دالة عالية الرتبة](/ar/reference/functions/regular-functions/overview#higher-order-functions).

**الصياغة**

```sql theme={null}
arrayReverseSort([f,] arr [, arr1, ... ,arrN])
```

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

* `f(y1[, y2 ... yN])` — دالة لامبدا تُطبَّق على عناصر المصفوفة `x`. - `arr` — مصفوفة مطلوب فرزها. [`Array(T)`](/ar/reference/data-types/array) - `arr1, ..., arrN` — اختياري. عدد N من المصفوفات الإضافية، في حال كانت `f` تقبل عدة وسيطات.

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

تعيد المصفوفة `x` مرتبةً ترتيبًا تنازليًا إذا لم يتم توفير دالة لامبدا، وإلا
فتعيد مصفوفة مرتبة وفقًا لمنطق دالة لامبدا المقدَّمة، ثم معكوسة. [`Array(T)`](/ar/reference/data-types/array).

**أمثلة**

**مثال 1**

```sql title=Query theme={null}
SELECT arrayReverseSort((x, y) -> y, [4, 3, 5], ['a', 'b', 'c']) AS res;
```

```response title=Response theme={null}
[5,3,4]
```

**مثال 2**

```sql title=Query theme={null}
SELECT arrayReverseSort((x, y) -> -y, [4, 3, 5], [1, 2, 3]) AS res;
```

```response title=Response theme={null}
[4,3,5]
```

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

تم تقديمه في: v20.1.0

قسّم مصفوفة المصدر إلى عدة مصفوفات. عندما تُرجِع `func(x[, y1, ..., yN])` قيمة غير صفرية، تُقسَّم المصفوفة إلى يمين ذلك العنصر. ولا تُقسَّم المصفوفة بعد العنصر الأخير.

**الصياغة**

```sql theme={null}
arrayReverseSplit(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x[, y1, ..., yN])` — دالة لامدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسائط إضافية لدالة لامدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة من المصفوفات. [`Array(Array(T))`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayReverseSplit((x, y) -> y, [1, 2, 3, 4, 5], [1, 0, 0, 1, 0]) AS res
```

```response title=Response theme={null}
[[1], [2, 3, 4], [5]]
```

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

أُضيف في: v23.8.0

يُدوِّر مصفوفة إلى اليسار بعدد العناصر المحدد. وتُعامَل القيم السالبة لـ `n` على أنها تدوير إلى اليمين بمقدار القيمة المطلقة للتدوير.

**الصياغة**

```sql theme={null}
arrayRotateLeft(arr, n)
```

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

* `arr` — المصفوفة التي تُدوَّر عناصرها.[`Array(T)`](/ar/reference/data-types/array). - `n` — عدد العناصر المراد تدويرها. [`(U)Int8/16/32/64`](/ar/reference/data-types/int-uint).

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

مصفوفة بعد تدويرها إلى اليسار بعدد العناصر المحدد [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayRotateLeft([1,2,3,4,5,6], 2) as res;
```

```response title=Response theme={null}
[3,4,5,6,1,2]
```

**القيمة السالبة لـ n**

```sql title=Query theme={null}
SELECT arrayRotateLeft([1,2,3,4,5,6], -2) as res;
```

```response title=Response theme={null}
[5,6,1,2,3,4]
```

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

تم تقديمه في: v23.8.0

يُدوِّر مصفوفة إلى اليمين بعدد العناصر المحدد. وتُعامَل القيم السالبة لـ `n` على أنها تدوير إلى اليسار بمقدار القيمة المطلقة.

**البنية**

```sql theme={null}
arrayRotateRight(arr, n)
```

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

* `arr` — المصفوفة المطلوب تدوير عناصرها.[`Array(T)`](/ar/reference/data-types/array). - `n` — عدد العناصر المطلوب تدويرها. [`(U)Int8/16/32/64`](/ar/reference/data-types/int-uint).

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

مصفوفة جرى تدويرها إلى اليمين بعدد العناصر المحدد [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayRotateRight([1,2,3,4,5,6], 2) as res;
```

```response title=Response theme={null}
[5,6,1,2,3,4]
```

**عندما تكون قيمة n سالبة**

```sql title=Query theme={null}
SELECT arrayRotateRight([1,2,3,4,5,6], -2) as res;
```

```response title=Response theme={null}
[3,4,5,6,1,2]
```

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

أُضيف في: v23.8.0

تُزاح المصفوفة إلى اليسار بعدد العناصر المحدد.
تُملأ العناصر الجديدة بالوسيطة المُمرَّرة أو بالقيمة الافتراضية لنوع عنصر المصفوفة.
إذا كان عدد العناصر سالبًا، تُزاح المصفوفة إلى اليمين.

**الصياغة**

```sql theme={null}
arrayShiftLeft(arr, n[, default])
```

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

* `arr` — المصفوفة المطلوب إزاحة عناصرها.[`Array(T)`](/ar/reference/data-types/array). - `n` — عدد العناصر المطلوب إزاحتها.[`(U)Int8/16/32/64`](/ar/reference/data-types/int-uint). - `default` — اختياري. القيمة الافتراضية للعناصر الجديدة.

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

مصفوفة مزاحة إلى اليسار بعدد العناصر المحدد [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayShiftLeft([1,2,3,4,5,6], 2) as res;
```

```response title=Response theme={null}
[3,4,5,6,0,0]
```

**القيمة السالبة لـ n**

```sql title=Query theme={null}
SELECT arrayShiftLeft([1,2,3,4,5,6], -2) as res;
```

```response title=Response theme={null}
[0,0,1,2,3,4]
```

**استخدام قيمة افتراضية**

```sql title=Query theme={null}
SELECT arrayShiftLeft([1,2,3,4,5,6], 2, 42) as res;
```

```response title=Response theme={null}
[3,4,5,6,42,42]
```

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

أُضيف في: v23.8.0

يُزيح مصفوفة إلى اليمين بعدد العناصر المحدد.
تُملأ العناصر الجديدة بالوسيطة المُمرَّرة أو بالقيمة الافتراضية لنوع عنصر المصفوفة.
إذا كان عدد العناصر سالبًا، فتُزاح المصفوفة إلى اليسار.

**البنية**

```sql theme={null}
arrayShiftRight(arr, n[, default])
```

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

* `arr` — المصفوفة المطلوب إزاحة عناصرها. [`Array(T)`](/ar/reference/data-types/array)
* `n` — عدد العناصر المراد إزاحتها. [`(U)Int8/16/32/64`](/ar/reference/data-types/int-uint)
* `default` — اختياري. القيمة الافتراضية للعناصر الجديدة.

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

مصفوفة مُزاحة إلى اليمين بعدد العناصر المحدد. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], 2) as res;
```

```response title=Response theme={null}
[0, 0, 1, 2, 3, 4]
```

**القيمة السالبة لـ n**

```sql title=Query theme={null}
SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], -2) as res;
```

```response title=Response theme={null}
[3, 4, 5, 6, 0, 0]
```

**استخدام قيمة افتراضية**

```sql title=Query theme={null}
SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], 2, 42) as res;
```

```response title=Response theme={null}
[42, 42, 1, 2, 3, 4]
```

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

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

تُنشئ مصفوفة من الشينغلز (على غرار `ngrams` في السلاسل النصية)، أي مصفوفات فرعية متتالية بطول محدد من مصفوفة الإدخال.

**البنية**

```sql theme={null}
arrayShingles(arr, l)
```

**الوسائط**

* `arr` — المصفوفة التي سيتم إنشاء مصفوفة من `shingles` منها. [`Array(T)`](/ar/reference/data-types/array)
* `l` — طول كل `shingle`. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

مصفوفة `shingles` المُنشأة [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayShingles([1, 2, 3, 4], 3) as res;
```

```response title=Response theme={null}
[[1, 2, 3], [2, 3, 4]]
```

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

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

تعيد مصفوفةً بالحجم نفسه للمصفوفة الأصلية، مع عناصرها بترتيب عشوائي.
تُعادُ ترتيب العناصر بحيث يكون لكل ترتيب ممكن لهذه العناصر الاحتمال نفسه للظهور.

<Note>
  لن تقوم هذه الدالة بتجسيد الثوابت.
</Note>

**البنية**

```sql theme={null}
arrayShuffle(arr [, seed])
```

**الوسائط**

* `arr` — المصفوفة المراد خلطها. [`Array(T)`](/ar/reference/data-types/array)
* `seed (optional)` — اختياري. البذرة المستخدمة في توليد الأرقام العشوائية. وإذا لم تُوفَّر، تُستخدم بذرة عشوائية. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

مصفوفة بعد خلط عناصرها [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال بدون seed (نتائج غير مستقرة)**

```sql title=Query theme={null}
SELECT arrayShuffle([1, 2, 3, 4]);
```

```response title=Response theme={null}
[1,4,2,3]
```

**مثال من دون seed (نتائج ثابتة)**

```sql title=Query theme={null}
SELECT arrayShuffle([1, 2, 3, 4], 41);
```

```response title=Response theme={null}
[3,2,1,4]
```

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

تم تقديمها في: v25.4.0

تحسب درجة التشابه بين مصفوفتين من `0` إلى `1` استنادًا إلى مسافة Levenshtein الموزونة.

**البنية**

```sql theme={null}
arraySimilarity(from, to, from_weights, to_weights)
```

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

* `from` — المصفوفة الأولى [`Array(T)`](/ar/reference/data-types/array)
* `to` — المصفوفة الثانية [`Array(T)`](/ar/reference/data-types/array)
* `from_weights` — الأوزان الخاصة بالمصفوفة الأولى. [`Array((U)Int*|Float*)`](/ar/reference/data-types/array)
* `to_weights` — الأوزان الخاصة بالمصفوفة الثانية. [`Array((U)Int*|Float*)`](/ar/reference/data-types/array)

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

يعيد قيمة التشابه بين المصفوفتين ضمن النطاق `0` إلى `1` استنادًا إلى مسافة Levenshtein الموزونة [`Float64`](/ar/reference/data-types/float)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arraySimilarity(['A', 'B', 'C'], ['A', 'K', 'L'], [1.0, 2, 3], [3.0, 4, 5]);
```

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

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

أُضيف في: v1.1.0

يعيد جزءًا من المصفوفة، مع تضمين عناصر `NULL`.

**الصياغة**

```sql theme={null}
arraySlice(arr, offset [, length])
```

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

* `arr` — المصفوفة المطلوب أخذ شريحة منها. [`Array(T)`](/ar/reference/data-types/array)
* `offset` — الإزاحة من طرف المصفوفة. تشير القيمة الموجبة إلى إزاحة من اليسار، وتشير القيمة السالبة إلى إزاحة من اليمين. يبدأ ترقيم عناصر المصفوفة من `1`. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `length` — طول الشريحة المطلوبة. إذا حددت قيمة سالبة، فستُرجع الدالة شريحة مفتوحة `[offset, array_length - length]`. وإذا حذفت القيمة، فستُرجع الدالة الشريحة `[offset, the_end_of_array]`. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

ترجع شريحة من المصفوفة تتكون من `length` عنصرًا بدءًا من `offset` المحدد [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arraySlice([1, 2, NULL, 4, 5], 2, 3) AS res;
```

```response title=Response theme={null}
[2, NULL, 4]
```

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

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

ترتّب عناصر المصفوفة المُعطاة بترتيب تصاعدي.
إذا جرى تحديد دالة لامبدا `f`، فإن ترتيب الفرز يتحدّد بناءً على نتيجة
تطبيق دالة لامبدا على كل عنصر من عناصر المصفوفة.
إذا كانت دالة لامبدا تقبل عدة وسائط، فسيُمرَّر إلى الدالة `arraySort` عدة
مصفوفات تقابل وسائط `f`.

إذا كانت المصفوفة المطلوب فرزها تحتوي على `-Inf` أو `NULL` أو `NaN` أو `Inf`، فسيجري فرزها بالترتيب التالي:

1. `-Inf`
2. `Inf`
3. `NaN`
4. `NULL`

`arraySort` هي [دالة عالية الرتبة](/ar/reference/functions/regular-functions/overview#higher-order-functions).

**البنية**

```sql theme={null}
arraySort([f,] arr [, arr1, ... ,arrN])
```

**الوسائط**

* `f(y1[, y2 ... yN])` — دالة لامدا تُطبَّق على عناصر المصفوفة `x`. - `arr` — المصفوفة المطلوب فرزها. [`Array(T)`](/ar/reference/data-types/array) - `arr1, ..., arrN` — اختياري. عدد N من المصفوفات الإضافية، وذلك عندما تقبل `f` عدة وسائط.

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

تُعيد المصفوفة `arr` مرتبةً ترتيبًا تصاعديًا إذا لم يتم توفير دالة لامدا، وإلا
فإنها تُعيد مصفوفة مرتبة وفقًا للمنطق الذي تحدده دالة لامدا المُقدَّمة. [`Array(T)`](/ar/reference/data-types/array).

**أمثلة**

**مثال 1**

```sql title=Query theme={null}
SELECT arraySort([1, 3, 3, 0]);
```

```response title=Response theme={null}
[0,1,3,3]
```

**مثال 2**

```sql title=Query theme={null}
SELECT arraySort(['hello', 'world', '!']);
```

```response title=Response theme={null}
['!','hello','world']
```

**مثال 3**

```sql title=Query theme={null}
SELECT arraySort([1, nan, 2, NULL, 3, nan, -4, NULL, inf, -inf]);
```

```response title=Response theme={null}
[-inf,-4,1,2,3,inf,nan,nan,NULL,NULL]
```

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

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

قسِّم المصفوفة المصدر إلى عدة مصفوفات. عندما تُرجِع `func(x [, y1, ..., yN])` قيمةً غير صفرية، ستُقسَّم المصفوفة إلى يسار ذلك العنصر. لن تُقسَّم المصفوفة قبل العنصر الأول.

**الصياغة**

```sql theme={null}
arraySplit(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**الوسائط**

* `func(x[, y1, ..., yN])` — دالة لامبدا تُطبَّق على عناصر المصفوفة المصدر (`x`) ومصفوفات الشروط (`y`).[دالة لامبدا](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — المصفوفة المصدر المطلوب تقسيمها [`Array(T)`](/ar/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشروط التي توفّر وسائط إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array).

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

تعيد مصفوفة من المصفوفات [`Array(Array(T))`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arraySplit((x, y) -> y, [1, 2, 3, 4, 5], [1, 0, 0, 1, 0]) AS res
```

```response title=Response theme={null}
[[1, 2, 3], [4, 5]]
```

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

تم تقديمه في: v21.1.0

يعيد مجموع عناصر المصفوفة المصدر.

إذا جرى تحديد دالة لامبدا `func`، فإنه يعيد مجموع عناصر نتائج لامبدا.

**البنية**

```sql theme={null}
arraySum([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```

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

* `func(x[, y1, ..., yN])` — اختياري. دالة لامبدا تعمل على عناصر المصفوفة المصدر (`x`) ومصفوفات الشرط (`y`). [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — المصفوفة المصدر المطلوب معالجتها. [`Array(T)`](/ar/reference/data-types/array)
* `, cond1_arr, ... , condN_arr]` — اختياري. عدد N من مصفوفات الشرط التي توفّر وسيطات إضافية لدالة لامبدا. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مجموع العناصر في المصفوفة المصدر، أو مجموع عناصر نتائج دالة لامبدا إذا تم توفيرها.

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT arraySum([1, 2, 3, 4]);
```

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

**الاستخدام مع دالة Lambda**

```sql title=Query theme={null}
SELECT arraySum(x, y -> x+y, [1, 1, 1, 1], [1, 1, 1, 1]);
```

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

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

أُضيفت في: v25.4.0

تأخذ هذه الدالة عدة مصفوفات وتُرجع مصفوفة بالعناصر غير الموجودة في جميع مصفوفات الإدخال. ولا تتضمن النتيجة إلا قيماً فريدة.

<Note>
  يُعرَّف الفرق المتماثل *لأكثر من مجموعتَين* [رياضياً](https://en.wikipedia.org/wiki/Symmetric_difference#n-ary_symmetric_difference)
  بأنه مجموعة جميع عناصر الإدخال التي تظهر في عدد فردي من مجموعات الإدخال.
  وعلى النقيض من ذلك، تُرجع الدالة `arraySymmetricDifference` ببساطة مجموعة عناصر الإدخال التي لا تظهر في جميع مجموعات الإدخال.
</Note>

**البنية**

```sql theme={null}
arraySymmetricDifference(arr1, arr2, ... , arrN)
```

**الوسائط**

* `arrN` — ‏N من المصفوفات التي ستُنشأ منها المصفوفة الجديدة. [`Array(T)`](/ar/reference/data-types/array).

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

يعيد مصفوفة من العناصر المميّزة غير الموجودة في جميع مصفوفات المصدر [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT
arraySymmetricDifference([1, 2], [1, 2], [1, 2]) AS empty_symmetric_difference,
arraySymmetricDifference([1, 2], [1, 2], [1, 3]) AS non_empty_symmetric_difference;
```

```response title=Response theme={null}
┌─empty_symmetric_difference─┬─non_empty_symmetric_difference─┐
│ []                         │ [3,2]                          │
└────────────────────────────┴────────────────────────────────┘
```

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

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

تُرجِع مصفوفة تحتوي على أكبر `K` عناصر من مصفوفة الإدخال، مرتبة ترتيبًا تنازليًا.
إذا جرى تحديد `lambda function` ‏`f`، فتُقارَن العناصر بناءً على ناتج تطبيق `f` على كل عنصر.
إذا كانت `f` تقبل عدة وسيطات، فستُمرَّر مصفوفات إضافية إلى `arrayTopK`، وتكون عناصرها
مطابقةً لوسيطات `f`.

تُتخطى القيم `NULL` ولا تظهر في النتيجة. ويكون حجم النتيجة بحد أقصى `K`
وقد يكون أصغر إذا كانت مصفوفة الإدخال تحتوي على عدد من العناصر غير `NULL` أقل من `K`.
ويكون نوع عنصر النتيجة هو النظير غير القابل لـ `NULL` لنوع عنصر الإدخال.

تُعد `arrayTopK` [دالة من الرتبة العليا](/ar/reference/functions/regular-functions/overview#higher-order-functions).

انظر أيضًا إلى `arrayBottomK`، التي تُرجِع أصغر `K` عناصر بدلًا من ذلك.

**الصياغة**

```sql theme={null}
arrayTopK([f,] K, arr [, arr1, ... ,arrN])
```

**الوسائط**

* `f(arr[, arr1, ... ,arrN])` — اختياري. دالة لامبدا لحساب مفتاح الترتيب لكل عنصر. [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `K` — عدد أكبر العناصر المراد إرجاعها. [`(U)Int8/16/32/64`](/ar/reference/data-types/int-uint)
* `arr` — مصفوفة. [`Array(T)`](/ar/reference/data-types/array)
* `arr1, ... ,arrN` — ‏N من المصفوفات الإضافية، إذا كانت `f` تقبل عدة وسائط. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجع ما يصل إلى `K` من عناصر `arr` ذات القيم الأكبر (أو أكبر نواتج دالة لامبدا)، مرتبة ترتيبًا تنازليًا.
تُتخطى قيم NULL. ويكون نوع عنصر المصفوفة المعادة هو `T` حتى عندما يكون الإدخال من النوع `Nullable(T)`.

**أمثلة**

**simple\_int**

```sql title=Query theme={null}
SELECT arrayTopK(3, [1, 5, 2, 7, 3])
```

```response title=Response theme={null}
[7,5,3]
```

**skip\_nulls**

```sql title=Query theme={null}
SELECT arrayTopK(3, [1, NULL, 5, 2, NULL, 7])
```

```response title=Response theme={null}
[7,5,2]
```

**fewer\_than\_k**

```sql title=Query theme={null}
SELECT arrayTopK(5, [1, NULL, 2])
```

```response title=Response theme={null}
[2,1]
```

**lambda\_simple**

```sql title=Query theme={null}
SELECT arrayTopK((x) -> -x, 2, [5, 9, 1, 3])
```

```response title=Response theme={null}
[1,3]
```

**lambda\_multi**

```sql title=Query theme={null}
SELECT arrayTopK((x, y) -> y, 2, ['a', 'b', 'c'], [3, 1, 2])
```

```response title=Response theme={null}
['a','c']
```

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

استُحدث في: v26.4.0

يبدّل صفوف المصفوفة ثنائية الأبعاد وأعمدتها.

يجب أن تكون جميع المصفوفات الداخلية بالطول نفسه.

**الصيغة**

```sql theme={null}
arrayTranspose(arr)
```

**الوسائط**

* `arr` — مصفوفة ثنائية الأبعاد يُراد نقلها. يجب أن يكون طول جميع المصفوفات الداخلية متماثلًا. [`Array(Array(T))`](/ar/reference/data-types/array)

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

مصفوفة ثنائية الأبعاد منقولة، بحيث يكون العنصر `[i][j]` في النتيجة مساويًا للعنصر `[j][i]` في المُدخل. [`Array(Array(T))`](/ar/reference/data-types/array)

**أمثلة**

**مصفوفة مربعة**

```sql title=Query theme={null}
SELECT arrayTranspose([[1, 2], [3, 4]])
```

```response title=Response theme={null}
[[1, 3], [2, 4]]
```

**مصفوفة غير مربعة**

```sql title=Query theme={null}
SELECT arrayTranspose([[1, 2, 3], [4, 5, 6]])
```

```response title=Response theme={null}
[[1, 4], [2, 5], [3, 6]]
```

**عناصر من النوع String**

```sql title=Query theme={null}
SELECT arrayTranspose([['a', 'b'], ['c', 'd']])
```

```response title=Response theme={null}
[['a', 'c'], ['b', 'd']]
```

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

أُضيف في: v24.10.0

يأخذ عدة مصفوفات ويُرجع مصفوفةً تتضمن جميع العناصر الموجودة في أيٍّ من المصفوفات المصدرية. وتحتوي النتيجة على قيم فريدة فقط.

**الصياغة**

```sql theme={null}
arrayUnion(arr1, arr2, ..., arrN)
```

**الوسائط**

* `arrN` — عدد N من المصفوفات التي تُنشأ منها المصفوفة الجديدة. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفة تضم عناصر مميزة من المصفوفات المصدر [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT
arrayUnion([-2, 1], [10, 1], [-2], []) as num_example,
arrayUnion(['hi'], [], ['hello', 'hi']) as str_example,
arrayUnion([1, 3, NULL], [2, 3, NULL]) as null_example
```

```response title=Response theme={null}
┌─num_example─┬─str_example────┬─null_example─┐
│ [10,-2,1]   │ ['hello','hi'] │ [3,2,1,NULL] │
└─────────────┴────────────────┴──────────────┘
```

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

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

عند تمرير وسيط واحد، تحسب عدد العناصر المختلفة في المصفوفة.
وعند تمرير عدة وسائط، تحسب عدد **tuples** المختلفة المتكوِّنة من العناصر الموجودة في المواضع المتطابقة عبر عدة مصفوفات.

على سبيل المثال، سيُنشئ `SELECT arrayUniq([1,2], [3,4], [5,6])` الـ tuples التالية:

* الموضع 1: (1,3,5)
* الموضع 2: (2,4,6)

بعد ذلك، ستحسب عدد الـ tuples الفريدة. في هذه الحالة تكون القيمة `2`.

يجب أن تكون جميع المصفوفات المُمرَّرة بالطول نفسه.

<Tip>
  إذا كنت تريد الحصول على قائمة بالعناصر الفريدة في المصفوفة، فيمكنك استخدام `arrayReduce('groupUniqArray', arr)`.
</Tip>

**الصياغة**

```sql theme={null}
arrayUniq(arr1[, arr2, ..., arrN])
```

**الوسائط**

* `arr1` — المصفوفة التي يُراد حساب عدد العناصر الفريدة فيها. [`Array(T)`](/ar/reference/data-types/array)
* `[, arr2, ..., arrN]` — اختياري. مصفوفات إضافية تُستخدم لحساب عدد Tuples الفريدة المتكوّنة من العناصر الموجودة في المواضع المناظرة عبر عدة مصفوفات. [`Array(T)`](/ar/reference/data-types/array)

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

عند استخدام وسيط واحد، تُرجِع عدد
العناصر الفريدة. وعند استخدام عدة وسائط، تُرجِع عدد Tuples الفريدة المتكوّنة من
العناصر الموجودة في المواضع المناظرة عبر المصفوفات.
[`UInt32`](/ar/reference/data-types/int-uint)

**أمثلة**

**وسيط واحد**

```sql title=Query theme={null}
SELECT arrayUniq([1, 1, 2, 2])
```

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

**وسائط متعددة**

```sql title=Query theme={null}
SELECT arrayUniq([1, 2, 3, 1], [4, 5, 6, 4])
```

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

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

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

ينشئ مصفوفة بطول `length` مملوءة بالقيمة الثابتة `x`.

**الصياغة**

```sql theme={null}
arrayWithConstant(N, x)
```

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

* `length` — عدد العناصر في المصفوفة. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `x` — قيمة العناصر `N` في المصفوفة، ويمكن أن تكون من أي نوع.

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

تعيد مصفوفة تضم `N` عنصرًا، قيمة كل منها `x`. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayWithConstant(3, 1)
```

```response title=Response theme={null}
[1, 1, 1]
```

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

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

تجمع عدة مصفوفات في مصفوفة واحدة. تحتوي المصفوفة الناتجة على العناصر المناظرة من مصفوفات الإدخال، مجمَّعةً في Tupleات وفق ترتيب الوسيطات المذكور.

**الصياغة**

```sql theme={null}
arrayZip(arr1, arr2, ... , arrN)
```

**الوسائط**

* `arr1, arr2, ... , arrN` — عدد N من المصفوفات لدمجها في مصفوفة واحدة. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفةً تحتوي على عناصر من المصفوفات المصدر، مجمّعةً في Tuples. تكون أنواع البيانات في الـ Tuple هي نفسها أنواع بيانات المصفوفات المُدخلة، وبالترتيب نفسه الذي تُمرَّر به المصفوفات [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayZip(['a', 'b', 'c'], [5, 2, 1]);
```

```response title=Response theme={null}
[('a', 5), ('b', 2), ('c', 1)]
```

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

أُضيف في: v20.1.0

يجمع عدة مصفوفات في مصفوفة واحدة، مع دعم المصفوفات غير المتحاذية (أي المصفوفات ذات الأطوال المختلفة). وتحتوي المصفوفة الناتجة على العناصر المناظرة من المصفوفات المصدر، مجمَّعة في Tuples وفق ترتيب الوسيطات المذكور.

**البنية**

```sql theme={null}
arrayZipUnaligned(arr1, arr2, ..., arrN)
```

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

* `arr1, arr2, ..., arrN` — عدد N من المصفوفات لدمجها في مصفوفة واحدة. [`Array(T)`](/ar/reference/data-types/array)

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

تعيد مصفوفةً تضم عناصر من مصفوفات المصدر مجمّعةً في قيم Tuple. وتكون أنواع البيانات داخل الـ Tuple مطابقةً لأنواع مصفوفات الإدخال وبالترتيب نفسه الذي تُمرَّر به المصفوفات. [`Array(T)`](/ar/reference/data-types/array) أو [`Tuple(T1, T2, ...)`](/ar/reference/data-types/tuple)

**أمثلة**

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

```sql title=Query theme={null}
SELECT arrayZipUnaligned(['a'], [1, 2, 3]);
```

```response title=Response theme={null}
[('a', 1),(NULL, 2),(NULL, 3)]
```

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

تم تقديمها في: v1.1.0

تعيد عدد العناصر في المصفوفة التي تساوي `x`. وهي مكافئة لـ `arrayCount(elem -> elem = x, arr)`.

تُعامَل عناصر `NULL` كقيم منفصلة.

**البنية**

```sql theme={null}
countEqual(arr, x)
```

**الوسائط**

* `arr` — المصفوفة المراد البحث فيها. [`Array(T)`](/ar/reference/data-types/array)
* `x` — القيمة المطلوب عدّها في المصفوفة. أي نوع.

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

يعيد عدد العناصر في المصفوفة التي تساوي `x` [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT countEqual([1, 2, NULL, NULL], NULL)
```

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

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

قُدِّم في: v1.1.0

يتحقق مما إذا كانت المصفوفة المُدخلة فارغة.

تُعد المصفوفة فارغة إذا كانت لا تحتوي على أي عناصر.

<Note>
  يمكن تحسين أداء هذه الدالة بتفعيل [إعداد `optimize_functions_to_subcolumns`](/ar/reference/settings/session-settings#optimize_functions_to_subcolumns). عند ضبط `optimize_functions_to_subcolumns = 1`، تقرأ الدالة فقط [العمود الفرعي size0](/ar/reference/data-types/array#array-size) بدلًا من قراءة عمود المصفوفة بالكامل ومعالجته. ويتحوّل الاستعلام `SELECT empty(arr) FROM TABLE;` إلى `SELECT arr.size0 = 0 FROM TABLE;`.
</Note>

تعمل هذه الدالة أيضًا مع Strings أو UUIDs.

**البنية**

```sql theme={null}
empty(arr)
```

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

* `arr` — مصفوفة الإدخال. [`Array(T)`](/ar/reference/data-types/array)

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

يعيد `1` للمصفوفة الفارغة، أو `0` للمصفوفة غير الفارغة [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT empty([]);
```

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

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

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

تُرجع مصفوفة Date فارغة

**البنية**

```sql theme={null}
emptyArrayDate()
```

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

* لا شيء.

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

مصفوفة Date فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayDate
```

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

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

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

تُرجع مصفوفة DateTime فارغة

**الصياغة**

```sql theme={null}
emptyArrayDateTime()
```

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

* لا شيء.

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

مصفوفة DateTime فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayDateTime
```

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

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

أُضيف في: v1.1.0

يعيد مصفوفة Float32 فارغة

**الصيغة**

```sql theme={null}
emptyArrayFloat32()
```

**الوسائط**

* لا شيء.

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

مصفوفة فارغة من نوع Float32. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayFloat32
```

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

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

قُدِّم في: v1.1.0

يعيد مصفوفة فارغة من نوع Float64

**الصيغة**

```sql theme={null}
emptyArrayFloat64()
```

**الوسائط**

* لا شيء.

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

مصفوفة Float64 فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayFloat64
```

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

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

أُضيف في: v1.1.0

تعيد مصفوفة Int16 فارغة

**البنية**

```sql theme={null}
emptyArrayInt16()
```

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

* لا شيء.

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

مصفوفة فارغة من النوع `Int16`. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayInt16
```

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

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

أُضيف في: v1.1.0

يُرجع مصفوفة Int32 فارغة

**الصيغة**

```sql theme={null}
emptyArrayInt32()
```

**الوسائط**

* لا شيء.

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

مصفوفة Int32 فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayInt32
```

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

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

أُضيف في: v1.1.0

يعيد مصفوفة Int64 فارغة

**الصيغة**

```sql theme={null}
emptyArrayInt64()
```

**الوسائط**

* لا شيء.

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

مصفوفة Int64 فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayInt64
```

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

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

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

تُرجِع مصفوفة Int8 فارغة

**الصياغة**

```sql theme={null}
emptyArrayInt8()
```

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

* لا شيء.

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

مصفوفة Int8 فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayInt8
```

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

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

أُضيف في: v1.1.0

يعيد مصفوفة String فارغة

**الصياغة**

```sql theme={null}
emptyArrayString()
```

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

* لا شيء.

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

مصفوفة فارغة من نوع String. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayString
```

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

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

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

تقبل مصفوفة فارغة وتُرجع مصفوفة من عنصر واحد تساوي القيمة الافتراضية.

**البنية**

```sql theme={null}
emptyArrayToSingle(arr)
```

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

* `arr` — مصفوفة فارغة. [`Array(T)`](/ar/reference/data-types/array)

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

مصفوفة تحتوي على قيمة واحدة من النوع الافتراضي للمصفوفة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
CREATE TABLE test (
  a Array(Int32),
  b Array(String),
  c Array(DateTime)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO test VALUES ([], [], []);

SELECT emptyArrayToSingle(a), emptyArrayToSingle(b), emptyArrayToSingle(c) FROM test;
```

```response title=Response theme={null}
┌─emptyArrayToSingle(a)─┬─emptyArrayToSingle(b)─┬─emptyArrayToSingle(c)───┐
│ [0]                   │ ['']                  │ ['1970-01-01 01:00:00'] │
└───────────────────────┴───────────────────────┴─────────────────────────┘
```

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

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

تُرجع مصفوفة UInt16 فارغة

**الصيغة**

```sql theme={null}
emptyArrayUInt16()
```

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

* لا شيء.

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

مصفوفة فارغة من نوع UInt16. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayUInt16
```

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

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

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

تعيد مصفوفة UInt32 فارغة

**البنية**

```sql theme={null}
emptyArrayUInt32()
```

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

* لا توجد.

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

مصفوفة فارغة من نوع UInt32. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayUInt32
```

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

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

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

تُرجع مصفوفة UInt64 فارغة

**البنية**

```sql theme={null}
emptyArrayUInt64()
```

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

* لا شيء.

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

مصفوفة UInt64 فارغة. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayUInt64
```

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

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

أُضيف في: v1.1.0

يعيد مصفوفة UInt8 فارغة

**البنية**

```sql theme={null}
emptyArrayUInt8()
```

**الوسائط**

* لا شيء.

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

مصفوفة فارغة من نوع UInt8. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT emptyArrayUInt8
```

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

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

تم تقديمه في: v1.1.0

يُرجع ما إذا كانت المصفوفة تحتوي على العنصر المحدد، أو ما إذا كان الـ Map يحتوي على المفتاح المحدد، أو ما إذا كان كائن JSON يحتوي على المسار المحدد.

في JSON، تكون المسارات المتداخلة مدعومة باستخدام صيغة النقطة (على سبيل المثال، 'a.b.c').

عندما تكون الوسيطة الأولى مصفوفة ثابتة وتكون الوسيطة الثانية عمودًا أو expression، فإن `has(constant_array, column)` يعمل مثل `column IN (constant_array)` ويمكنه استخدام المفتاح الأساسي وData-skipping indexes لتحسين الأداء. على سبيل المثال، يمكن أن يستفيد `has([1, 10, 100], id)` من فهرس المفتاح الأساسي إذا كان `id` جزءًا من `PRIMARY KEY`.

ينطبق هذا التحسين أيضًا عندما يكون العمود مغلفًا داخل دوال رتيبة (على سبيل المثال، `has([...], toDate(ts))`).

**البنية**

```sql theme={null}
has(haystack, needle)
```

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

* `haystack` — مصفوفة الإدخال أو الخريطة أو JSON. [`Array`](/ar/reference/data-types/array) أو [`Map`](/ar/reference/data-types/map) أو [`JSON`](/ar/reference/data-types/newjson)
* `needle` — القيمة المطلوب البحث عنها (عنصر في المصفوفة، أو مفتاح في الخريطة، أو سلسلة مسار في JSON).

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

يعيد `1` إذا كان `haystack` يحتوي على `needle` المحددة، وإلا فيعيد `0`. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**الاستخدام الأساسي لـ Array**

```sql title=Query theme={null}
SELECT has([1, 2, 3], 2)
```

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

**Array غير موجودة**

```sql title=Query theme={null}
SELECT has([1, 2, 3], 4)
```

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

**الاستخدام الأساسي لـ Map**

```sql title=Query theme={null}
SELECT has(map('a', 1, 'b', 2), 'b')
```

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

**مسار JSON**

```sql title=Query theme={null}
SELECT has('{"a": {"b": 1}}'::JSON, 'a.b')
```

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

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

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

يتحقق مما إذا كانت مصفوفة ما مجموعة فرعية من مصفوفة أخرى.

* المصفوفة الفارغة هي مجموعة فرعية من أي مصفوفة.
* تُعالَج `NULL` على أنها قيمة.
* لا يهم ترتيب القيم في أيٍّ من المصفوفتين.

**الصياغة**

```sql theme={null}
hasAll(set, subset)
```

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

* `set` — مصفوفة من أي نوع تحتوي على مجموعة من العناصر. [`Array(T)`](/ar/reference/data-types/array)
* `subset` — مصفوفة من أي نوع تشترك مع `set` في نوع أسمى مشترك، وتحتوي على العناصر المطلوب اختبار ما إذا كانت مجموعة فرعية من `set`. [`Array(T)`](/ar/reference/data-types/array)

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

* `1`، إذا كانت `set` تحتوي على جميع العناصر الموجودة في `subset`.
* `0`، بخلاف ذلك.

يُطلق استثناء `NO_COMMON_TYPE` إذا كانت عناصر `set` و`subset` لا تشترك في نوع أسمى مشترك.

**أمثلة**

**المصفوفات الفارغة**

```sql title=Query theme={null}
SELECT hasAll([], [])
```

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

**المصفوفات التي تتضمن قيم NULL**

```sql title=Query theme={null}
SELECT hasAll([1, Null], [Null])
```

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

**مصفوفات تحتوي على قيم من نوع آخر**

```sql title=Query theme={null}
SELECT hasAll([1.0, 2, 3, 4], [1, 3])
```

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

**مصفوفات تحتوي على قيم من النوع String**

```sql title=Query theme={null}
SELECT hasAll(['a', 'b'], ['a'])
```

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

**المصفوفات بلا نوع مشترك**

```sql title=Query theme={null}
SELECT hasAll([1], ['a'])
```

```response title=Response theme={null}
Raises a NO_COMMON_TYPE exception
```

**مصفوفة من المصفوفات**

```sql title=Query theme={null}
SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [3, 5]])
```

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

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

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

يتحقق مما إذا كان هناك تقاطع بين مصفوفتين في بعض العناصر.

* تُعامَل `Null` على أنها قيمة.
* لا يهم ترتيب القيم في أيٍّ من المصفوفتين.

**البنية**

```sql theme={null}
hasAny(arr_x, arr_y)
```

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

* `arr_x` — مصفوفة من أي نوع تضم مجموعة من العناصر. [`Array(T)`](/ar/reference/data-types/array)
* `arr_y` — مصفوفة من أي نوع تشترك مع المصفوفة `arr_x` في نوع أعلى مشترك. [`Array(T)`](/ar/reference/data-types/array)

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

* `1`، إذا كان لدى `arr_x` و`arr_y` عنصر واحد متشابه على الأقل.
* `0`، بخلاف ذلك.

يُطلق الاستثناء `NO_COMMON_TYPE` إذا كان أي عنصر من عناصر المصفوفتين لا يشترك في نوع أعلى مشترك.

**أمثلة**

**إحدى المصفوفتين فارغة**

```sql title=Query theme={null}
SELECT hasAny([1], [])
```

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

**المصفوفات التي تحتوي على قيم NULL**

```sql title=Query theme={null}
SELECT hasAny([Null], [Null, 1])
```

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

**المصفوفات التي تحتوي على قيم من نوع آخر**

```sql title=Query theme={null}
SELECT hasAny([-128, 1., 512], [1])
```

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

**مصفوفات بلا نوع مشترك**

```sql title=Query theme={null}
SELECT hasAny([[1, 2], [3, 4]], ['a', 'c'])
```

```response title=Response theme={null}
Raises a `NO_COMMON_TYPE` exception
```

**مصفوفة من مصفوفات**

```sql title=Query theme={null}
SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [1, 2]])
```

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

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

أُضيفت في: v20.6.0

تتحقق مما إذا كانت جميع عناصر array2 تظهر في array1 وبالترتيب نفسه تمامًا.
لذلك، تُرجع الدالة `1` إذا وفقط إذا كان array1 = بادئة + array2 + لاحقة.

بعبارة أخرى، تتحقق الدالة مما إذا كانت جميع عناصر array2 موجودة في array1 كما في الدالة `hasAll`.
بالإضافة إلى ذلك، تتحقق من أن العناصر تظهر بالترتيب نفسه في كلٍّ من array1 وarray2.

* تُرجع الدالة `1` إذا كانت array2 فارغة.
* تُعامَل `NULL` على أنها قيمة. بعبارة أخرى، تُرجع `hasSubstr([1, 2, NULL, 3, 4], [2,3])` القيمة `0`. ومع ذلك، تُرجع `hasSubstr([1, 2, NULL, 3, 4], [2,NULL,3])` القيمة `1`
* ترتيب القيم في كلتا المصفوفتين مهم.

يُطلق الاستثناء `NO_COMMON_TYPE` إذا كان أي عنصر من عناصر المصفوفتين لا يشترك في نوع أعلى مشترك.

**البنية**

```sql theme={null}
hasSubstr(arr1, arr2)
```

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

* `arr1` — مصفوفة من أي نوع تضم مجموعة من العناصر. [`Array(T)`](/ar/reference/data-types/array)
* `arr2` — مصفوفة من أي نوع تضم مجموعة من العناصر. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجِع `1` إذا كانت المصفوفة `arr1` تحتوي على المصفوفة `arr2`، وإلا فتُرجِع `0`. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**كلتا المصفوفتين فارغتان**

```sql title=Query theme={null}
SELECT hasSubstr([], [])
```

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

**مصفوفات تحتوي على قيم NULL**

```sql title=Query theme={null}
SELECT hasSubstr([1, Null], [Null])
```

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

**مصفوفات تحتوي على قيم من نوع مختلف**

```sql title=Query theme={null}
SELECT hasSubstr([1.0, 2, 3, 4], [1, 3])
```

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

**المصفوفات التي تحتوي على سلاسل نصية**

```sql title=Query theme={null}
SELECT hasSubstr(['a', 'b'], ['a'])
```

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

**المصفوفات ذات الترتيب الصحيح**

```sql title=Query theme={null}
SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'b'])
```

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

**المصفوفات ذات الترتيب غير الصحيح**

```sql title=Query theme={null}
SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'c'])
```

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

**مصفوفة من مصفوفات**

```sql title=Query theme={null}
SELECT hasSubstr([[1, 2], [3, 4], [5, 6]], [[1, 2], [3, 4]])
```

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

**المصفوفات بلا نوع مشترك**

```sql title=Query theme={null}
SELECT hasSubstr([1, 2, NULL, 3, 4], ['a'])
```

```response title=Response theme={null}
Raises a `NO_COMMON_TYPE` exception
```

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

أُضيف في: v1.1.0

يعيد موضع أول عنصر ذي القيمة 'x' (بدءًا من 1) إذا كان موجودًا في المصفوفة.
إذا كانت المصفوفة لا تحتوي على القيمة المطلوب البحث عنها، فستُرجِع الدالة `0`.

تُعامَل العناصر المعيّنة إلى `NULL` على أنها قيم عادية.

**البنية**

```sql theme={null}
indexOf(arr, x)
```

**الوسائط**

* `arr` — مصفوفة يُبحث فيها عن `x`. [`Array(T)`](/ar/reference/data-types/array)
* `x` — قيمة أول عنصر مطابق في `arr` يُراد إرجاع فهرسه. [`UInt64`](/ar/reference/data-types/int-uint)

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

يُرجع فهرس أول `x` في `arr` (مرقّمًا بدءًا من 1) إذا كان موجودًا. وإلا، يُرجع `0`. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT indexOf([5, 4, 1, 3], 3)
```

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

**مصفوفة بقيم NULL**

```sql title=Query theme={null}
SELECT indexOf([1, 3, NULL, NULL], NULL)
```

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

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

قُدِّمت في: v24.12.0

تُرجِع فهرس أول عنصر ذي القيمة 'x' (بدءًا من `1`) إذا كان موجودًا في المصفوفة.
إذا لم تحتوي المصفوفة على القيمة المطلوب البحث عنها، فستُرجِع الدالة `0`.

<Note>
  بخلاف الدالة `indexOf`، تفترض هذه الدالة أن المصفوفة مرتبة ترتيبًا
  تصاعديًا. وإذا لم تكن المصفوفة مرتبة، فالنتائج غير معرّفة.
</Note>

**البنية**

```sql theme={null}
indexOfAssumeSorted(arr, x)
```

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

* `arr` — مصفوفة مرتبة للبحث فيها. [`Array(T)`](/ar/reference/data-types/array)
* `x` — قيمة أول عنصر مطابق في `arr` المرتبة يُراد إرجاع فهرسه. [`UInt64`](/ar/reference/data-types/int-uint)

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

يعيد الفهرس (المرقّم بدءًا من واحد) لأول قيمة `x` في `arr` إذا كانت موجودة. وإلا، يعيد `0`. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال أساسي**

```sql title=Query theme={null}
SELECT indexOfAssumeSorted([1, 3, 3, 3, 4, 4, 5], 4)
```

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

<div id="kql_array_sort_asc">
  ## kql\_array\_sort\_asc
</div>

أُضيف في: v23.10.0

يرتّب مصفوفة واحدة أو أكثر بترتيب تصاعدي. تُرتَّب المصفوفة الأولى، ثم يُعاد ترتيب المصفوفات اللاحقة لتتوافق مع الترتيب المرتّب للمصفوفة الأولى. توضع القيم NULL في النهاية. هذه دالة توافق مع KQL ‏(Kusto Query Language).

**البنية**

```sql theme={null}
kql_array_sort_asc(array1[, array2, ..., nulls_last])
```

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

* `array1` — المصفوفة المراد فرزها. [`Array(T)`](/ar/reference/data-types/array)
* `array2` — اختياري. مصفوفات إضافية لإعادة ترتيبها وفقًا لترتيب فرز `array1`. [`Array(T)`](/ar/reference/data-types/array)
* `nulls_last` — اختياري. قيمة منطقية تشير إلى ما إذا كان يجب أن تظهر قيم NULL في النهاية. القيمة الافتراضية هي true. [`UInt8`](/ar/reference/data-types/int-uint)

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

يعيد Tuple من المصفوفات مرتبة ترتيبًا تصاعديًا. [`Tuple(Array, ...)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT kql_array_sort_asc([3, 1, 2])
```

```response title=Response theme={null}
([1, 2, 3])
```

<div id="kql_array_sort_desc">
  ## kql\_array\_sort\_desc
</div>

أُضيفت في: v23.10.0

ترتّب مصفوفة واحدة أو أكثر ترتيبًا تنازليًا. تُرتَّب المصفوفة الأولى، ثم تُعاد ترتيب المصفوفات اللاحقة لتتوافق مع الترتيب الناتج للمصفوفة الأولى. تُوضَع قيم NULL في النهاية. هذه دالة للتوافق مع KQL ‏(Kusto Query Language).

**البنية**

```sql theme={null}
kql_array_sort_desc(array1[, array2, ..., nulls_last])
```

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

* `array1` — المصفوفة المطلوب فرزها. [`Array(T)`](/ar/reference/data-types/array)
* `array2` — مصفوفات إضافية اختيارية يُعاد ترتيبها وفقًا لترتيب فرز `array1`. [`Array(T)`](/ar/reference/data-types/array)
* `nulls_last` — قيمة منطقية اختيارية تشير إلى ما إذا كان ينبغي أن تظهر قيم `NULL` أخيرًا. القيمة الافتراضية هي `true`. [`UInt8`](/ar/reference/data-types/int-uint)

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

يعيد Tuple من المصفوفات مرتبة ترتيبًا تنازليًا. [`Tuple(Array, ...)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT kql_array_sort_desc([3, 1, 2])
```

```response title=Response theme={null}
([3, 2, 1])
```

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

أُضيف في: v1.1.0

يحسب طول سلسلة نصية أو مصفوفة.

* بالنسبة إلى وسيطات String أو FixedString: يحسب عدد البايتات في السلسلة النصية.
* بالنسبة إلى وسيطات Array: يحسب عدد العناصر في المصفوفة.
* إذا طُبِّق على وسيطة FixedString، فإن الدالة تكون تعبيرًا ثابتًا.

يرجى ملاحظة أن عدد البايتات في السلسلة النصية لا يساوي عدد
Unicode "code points"، ولا يساوي عدد Unicode "grapheme clusters"
(ما نسمّيه عادةً "المحارف")، كما أنه لا يساوي العرض المرئي للسلسلة النصية.

لا بأس بوجود بايتات NULL من نوع ASCII في السلاسل النصية، وسيتم احتسابها أيضًا.

**الصياغة**

```sql theme={null}
length(x)
```

**الأسماء البديلة**: `CARDINALITY`, `OCTET_LENGTH`

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

* `x` — القيمة التي يُحسَب لها عدد البايتات (في String/FixedString) أو عدد العناصر (في Array). [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring) أو [`Array(T)`](/ar/reference/data-types/array)

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

يعيد عدد البايتات في String/FixedString `x` / عدد العناصر في المصفوفة `x` [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على String**

```sql title=Query theme={null}
SELECT length('Hello, world!')
```

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

**مثال على Array**

```sql title=Query theme={null}
SELECT length(['Hello', 'world'])
```

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

**مثال constexpr**

```sql title=Query theme={null}
WITH 'hello' || toString(number) AS str
SELECT str,
isConstant(length(str)) AS str_length_is_constant,
isConstant(length(str::FixedString(6))) AS fixed_str_length_is_constant
FROM numbers(3)
```

```response title=Response theme={null}
┌─str────┬─str_length_is_constant─┬─fixed_str_length_is_constant─┐
│ hello0 │                      0 │                            1 │
│ hello1 │                      0 │                            1 │
│ hello2 │                      0 │                            1 │
└────────┴────────────────────────┴──────────────────────────────┘
```

**مثال Unicode**

```sql title=Query theme={null}
SELECT 'ёлка' AS str1, length(str1), lengthUTF8(str1), normalizeUTF8NFKD(str1) AS str2, length(str2), lengthUTF8(str2)
```

```response title=Response theme={null}
┌─str1─┬─length(str1)─┬─lengthUTF8(str1)─┬─str2─┬─length(str2)─┬─lengthUTF8(str2)─┐
│ ёлка │            8 │                4 │ ёлка │           10 │                5 │
└──────┴──────────────┴──────────────────┴──────┴──────────────┴──────────────────┘
```

**مثال على ascii\_vs\_utf8**

```sql title=Query theme={null}
SELECT 'ábc' AS str, length(str), lengthUTF8(str)
```

```response title=Response theme={null}
┌─str─┬─length(str)──┬─lengthUTF8(str)─┐
│ ábc │            4 │               3 │
└─────┴──────────────┴─────────────────┘
```

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

أُضيف في: v1.1.0

يتحقق مما إذا كانت المصفوفة المُدخلة غير فارغة.

تُعدّ المصفوفة غير فارغة إذا كانت تحتوي على عنصر واحد على الأقل.

<Note>
  يمكن تحسينها عبر تمكين الإعداد [`optimize_functions_to_subcolumns`](/ar/reference/settings/session-settings#optimize_functions_to_subcolumns). عند ضبط `optimize_functions_to_subcolumns = 1`، تقرأ الدالة العمود الفرعي [size0](/ar/reference/data-types/array#array-size) فقط بدلًا من قراءة عمود المصفوفة بالكامل ومعالجته. ويتحوّل الاستعلام `SELECT notEmpty(arr) FROM table` إلى `SELECT arr.size0 != 0 FROM TABLE`.
</Note>

تعمل الدالة أيضًا مع السلاسل النصية أو معرّفات UUID.

**الصياغة**

```sql theme={null}
notEmpty(arr)
```

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

* `arr` — مصفوفة الإدخال. [`Array(T)`](/ar/reference/data-types/array)

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

تُرجع `1` للمصفوفة غير الفارغة، أو `0` للمصفوفة الفارغة [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
SELECT notEmpty([1,2]);
```

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

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

تم تقديمه في: v1.1.0

يعيد مصفوفة من الأرقام من `start` إلى `end - 1` بخطوة `step`.

الأنواع المدعومة هي:

* `UInt8/16/32/64`

* `Int8/16/32/64]`

* يجب أن تكون جميع الوسائط `start` و`end` و`step` من أحد الأنواع المدعومة أعلاه. وستكون عناصر المصفوفة المُعادة من نوع أعم مشتق من أنواع الوسائط.

* يُطرَح استثناء إذا أعادت الدالة مصفوفة يتجاوز طولها الإجمالي عدد العناصر المحدد في الإعداد [`function_range_max_elements_in_block`](/ar/reference/settings/session-settings#function_range_max_elements_in_block).

* يعيد `NULL` إذا كان أي وسيط من النوع Nullable(nothing). ويُطرَح استثناء إذا كانت قيمة أي وسيط هي `NULL` (من النوع Nullable(T)).

**البنية**

```sql theme={null}
range([start, ] end [, step])
```

**الوسائط**

* `start` — اختياري. العنصر الأول في المصفوفة. مطلوب إذا استُخدم `step`. القيمة الافتراضية: `0`. - `end` — مطلوب. الرقم الذي تُنشأ المصفوفة قبله. - `step` — اختياري. يحدّد مقدار الزيادة بين كل عنصر في المصفوفة. القيمة الافتراضية: `1`.

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

مصفوفة من الأرقام تبدأ من `start` حتى `end - 1` بخطوة `step`. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT range(5), range(1, 5), range(1, 5, 2), range(-1, 5, 2);
```

```response title=Response theme={null}
┌─range(5)────┬─range(1, 5)─┬─range(1, 5, 2)─┬─range(-1, 5, 2)─┐
│ [0,1,2,3,4] │ [1,2,3,4]   │ [1,3]          │ [-1,1,3]        │
└─────────────┴─────────────┴────────────────┴─────────────────┘
```

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

أُضيف في: v1.1.0

ينشئ مصفوفة تحتوي على قيمة واحدة.

**الصيغة**

```sql theme={null}
replicate(x, arr)
```

**الوسائط**

* `x` — القيمة التي ستُملأ بها مصفوفة النتيجة. [`Any`](/ar/reference/data-types/index)
* `arr` — مصفوفة. [`Array(T)`](/ar/reference/data-types/array)

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

تُعيد مصفوفةً بنفس طول `arr`، مملوءةً بالقيمة `x`. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

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

```sql title=Query theme={null}
SELECT replicate(1, ['a', 'b', 'c']);
```

```response title=Response theme={null}
┌─replicate(1, ['a', 'b', 'c'])───┐
│ [1, 1, 1]                       │
└─────────────────────────────────┘
```

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

أُضيف في: v1.1.0

يعكس ترتيب العناصر في مصفوفة الإدخال أو ترتيب الأحرف في سلسلة الإدخال.

**الصيغة**

```sql theme={null}
reverse(arr | str)
```

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

* `arr | str` — المصفوفة أو السلسلة النصية المُدخلة. [`Array(T)`](/ar/reference/data-types/array) أو [`String`](/ar/reference/data-types/string)

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

تعيد مصفوفة أو سلسلة نصية بترتيب معكوس للعناصر أو الأحرف.

**أمثلة**

**عكس المصفوفة**

```sql title=Query theme={null}
SELECT reverse([1, 2, 3, 4]);
```

```response title=Response theme={null}
[4, 3, 2, 1]
```

**عكس السلسلة النصية**

```sql title=Query theme={null}
SELECT reverse('abcd');
```

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

<div id="distance-functions">
  ## دوال المسافة
</div>

جميع الدوال المدعومة موضّحة في [وثائق دوال المسافة](/ar/reference/functions/regular-functions/distance-functions).