> ## 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.

> توثيق الدوال الشرطية

# الدوال الشرطية

<div id="overview">
  ## نظرة عامة
</div>

<div id="using-conditional-results-directly">
  ### استخدام النتائج الشرطية مباشرةً
</div>

تُرجع التعبيرات الشرطية دائمًا `0` أو `1` أو `NULL`. لذا يمكنك استخدام نتائجها مباشرةً كما يلي:

```sql theme={null}
SELECT left < right AS is_small
FROM LEFT_RIGHT

┌─is_small─┐
│     ᴺᵁᴸᴸ │
│        1 │
│        0 │
│        0 │
│     ᴺᵁᴸᴸ │
└──────────┘
```

<div id="null-values-in-conditionals">
  ### قيم `NULL` في التعبيرات الشرطية
</div>

عند وجود قيم `NULL` في التعبيرات الشرطية، تكون النتيجة أيضًا `NULL`.

```sql theme={null}
SELECT
    NULL < 1,
    2 < NULL,
    NULL < NULL,
    NULL = NULL

┌─less(NULL, 1)─┬─less(2, NULL)─┬─less(NULL, NULL)─┬─equals(NULL, NULL)─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ             │ ᴺᵁᴸᴸ               │
└───────────────┴───────────────┴──────────────────┴────────────────────┘
```

لذلك ينبغي إنشاء استعلاماتك بعناية إذا كانت الأنواع `Nullable`.

ويوضح المثال التالي ذلك، إذ يفشل بسبب عدم إضافة شرط `equals` إلى `multiIf`.

```sql theme={null}
SELECT
    left,
    right,
    multiIf(left < right, 'left is smaller', left > right, 'right is smaller', 'Both equal') AS faulty_result
FROM LEFT_RIGHT

┌─left─┬─right─┬─faulty_result────┐
│ ᴺᵁᴸᴸ │     4 │ Both equal       │
│    1 │     3 │ left is smaller  │
│    2 │     2 │ Both equal       │
│    3 │     1 │ right is smaller │
│    4 │  ᴺᵁᴸᴸ │ Both equal       │
└──────┴───────┴──────────────────┘
```

<div id="case-statement">
  ### عبارة CASE
</div>

يوفّر التعبير CASE في ClickHouse منطقًا شرطيًا مشابهًا لمعامل CASE في SQL. إذ يقيّم الشروط ويُرجع القيم بناءً على أول شرط متطابق.

يدعم ClickHouse شكلين لعبارة CASE:

1. `CASE WHEN ... THEN ... ELSE ... END`
   <br />
   يوفّر هذا الشكل مرونة كاملة، ويُنفَّذ داخليًا باستخدام الدالة [multiIf](/ar/reference/functions/regular-functions/conditional-functions#multiIf). ويُقيَّم كل شرط على نحو مستقل، ويمكن أن تتضمن التعبيرات قيمًا غير ثابتة.

```sql theme={null}
SELECT
    number,
    CASE
        WHEN number % 2 = 0 THEN number + 1
        WHEN number % 2 = 1 THEN number * 10
        ELSE number
    END AS result
FROM system.numbers
WHERE number < 5;

-- is translated to
SELECT
    number,
    multiIf((number % 2) = 0, number + 1, (number % 2) = 1, number * 10, number) AS result
FROM system.numbers
WHERE number < 5

┌─number─┬─result─┐
│      0 │      1 │
│      1 │     10 │
│      2 │      3 │
│      3 │     30 │
│      4 │      5 │
└────────┴────────┘

5 rows in set. Elapsed: 0.002 sec.
```

2. `CASE <expr> WHEN <val1> THEN ... WHEN <val2> THEN ... ELSE ... END`
   <br />
   هذا الشكل الأكثر اختصارًا مُحسَّن لمطابقة القيم الثابتة، ويستخدم داخليًا `caseWithExpression()`.

على سبيل المثال، ما يلي صحيح:

```sql theme={null}
SELECT
    number,
    CASE number
        WHEN 0 THEN 100
        WHEN 1 THEN 200
        ELSE 0
    END AS result
FROM system.numbers
WHERE number < 3;

-- is translated to

SELECT
    number,
    caseWithExpression(number, 0, 100, 1, 200, 0) AS result
FROM system.numbers
WHERE number < 3

┌─number─┬─result─┐
│      0 │    100 │
│      1 │    200 │
│      2 │      0 │
└────────┴────────┘

3 rows in set. Elapsed: 0.002 sec.
```

هذه الصيغة أيضًا لا تشترط أن تكون تعبيرات الإرجاع ثوابت.

```sql theme={null}
SELECT
    number,
    CASE number
        WHEN 0 THEN number + 1
        WHEN 1 THEN number * 10
        ELSE number
    END
FROM system.numbers
WHERE number < 3;

-- is translated to

SELECT
    number,
    caseWithExpression(number, 0, number + 1, 1, number * 10, number)
FROM system.numbers
WHERE number < 3

┌─number─┬─caseWithExpr⋯0), number)─┐
│      0 │                        1 │
│      1 │                       10 │
│      2 │                        2 │
└────────┴──────────────────────────┘

3 rows in set. Elapsed: 0.001 sec.
```

<div id="caveats">
  #### محاذير
</div>

يحدّد ClickHouse نوع نتيجة تعبير CASE (أو ما يكافئه داخليًا، مثل `multiIf`) قبل تقييم أي شروط. ويكتسب هذا أهمية عندما تختلف تعبيرات الإرجاع في النوع، مثل اختلاف المناطق الزمنية أو الأنواع الرقمية.

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

على سبيل المثال، في ما يلي تُرجع جميع الصفوف الطابع الزمني وفق المنطقة الزمنية لأول فرع مطابق، أي `Asia/Kolkata`

```sql theme={null}
SELECT
    number,
    CASE
        WHEN number = 0 THEN fromUnixTimestamp64Milli(0, 'Asia/Kolkata')
        WHEN number = 1 THEN fromUnixTimestamp64Milli(0, 'America/Los_Angeles')
        ELSE fromUnixTimestamp64Milli(0, 'UTC')
    END AS tz
FROM system.numbers
WHERE number < 3;

-- is translated to

SELECT
    number,
    multiIf(number = 0, fromUnixTimestamp64Milli(0, 'Asia/Kolkata'), number = 1, fromUnixTimestamp64Milli(0, 'America/Los_Angeles'), fromUnixTimestamp64Milli(0, 'UTC')) AS tz
FROM system.numbers
WHERE number < 3

┌─number─┬──────────────────────tz─┐
│      0 │ 1970-01-01 05:30:00.000 │
│      1 │ 1970-01-01 05:30:00.000 │
│      2 │ 1970-01-01 05:30:00.000 │
└────────┴─────────────────────────┘

3 rows in set. Elapsed: 0.011 sec.
```

هنا، يرى ClickHouse عدة أنواع إرجاع `DateTime64(3, <timezone>)`. ويستنتج أن النوع المشترك هو `DateTime64(3, 'Asia/Kolkata'` لأنه أول نوع يصادفه، ويحوّل الفروع الأخرى ضمنيًا إلى هذا النوع.

يمكن معالجة ذلك بالتحويل إلى سلسلة نصية للحفاظ على تنسيق المنطقة الزمنية المطلوب:

```sql theme={null}
SELECT
    number,
    multiIf(
        number = 0, formatDateTime(fromUnixTimestamp64Milli(0), '%F %T', 'Asia/Kolkata'),
        number = 1, formatDateTime(fromUnixTimestamp64Milli(0), '%F %T', 'America/Los_Angeles'),
        formatDateTime(fromUnixTimestamp64Milli(0), '%F %T', 'UTC')
    ) AS tz
FROM system.numbers
WHERE number < 3;

-- is translated to

SELECT
    number,
    multiIf(number = 0, formatDateTime(fromUnixTimestamp64Milli(0), '%F %T', 'Asia/Kolkata'), number = 1, formatDateTime(fromUnixTimestamp64Milli(0), '%F %T', 'America/Los_Angeles'), formatDateTime(fromUnixTimestamp64Milli(0), '%F %T', 'UTC')) AS tz
FROM system.numbers
WHERE number < 3

┌─number─┬─tz──────────────────┐
│      0 │ 1970-01-01 05:30:00 │
│      1 │ 1969-12-31 16:00:00 │
│      2 │ 1970-01-01 00:00:00 │
└────────┴─────────────────────┘

3 rows in set. Elapsed: 0.002 sec.
```

{/*AUTOGENERATED_START*/}

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

قُدِّم في: v24.5.0

يقيّد قيمة لتبقى ضمن الحدين الأدنى والأقصى المحددين.

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

يجب أن تكون جميع الوسيطات من أنواع قابلة للمقارنة. ويكون نوع النتيجة أكبر نوع متوافق بين جميع الوسيطات.

**الصيغة**

```sql theme={null}
clamp(value, min, max)
```

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

* `value` — القيمة المطلوب تقييدها. - `min` — الحد الأدنى. - `max` — الحد الأقصى.

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

تعيد القيمة بعد تقييدها ضمن النطاق \[min, max].

**أمثلة**

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

```sql title=Query theme={null}
SELECT clamp(5, 1, 10) AS result;
```

```response title=Response theme={null}
┌─result─┐
│      5 │
└────────┘
```

**القيمة دون الحد الأدنى**

```sql title=Query theme={null}
SELECT clamp(-3, 0, 7) AS result;
```

```response title=Response theme={null}
┌─result─┐
│      0 │
└────────┘
```

**القيمة أكبر من الحد الأقصى**

```sql title=Query theme={null}
SELECT clamp(15, 0, 7) AS result;
```

```response title=Response theme={null}
┌─result─┐
│      7 │
└────────┘
```

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

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

تعيد أكبر قيمة بين الوسيطات.
يتم تجاهل الوسيطات `NULL`.

* بالنسبة إلى المصفوفات، تعيد المصفوفة الأكبر ترتيبًا معجميًا.
* بالنسبة إلى أنواع `DateTime`، تتم ترقية نوع النتيجة إلى أكبر نوع (مثلًا، `DateTime64` عند مزجه مع `DateTime32`).

<Info>
  **استخدم الإعداد `least_greatest_legacy_null_behavior` لتغيير سلوك `NULL`**

  قدّم الإصدار [24.12](/ar/resources/changelogs/oss/2024#a-id2412a-clickhouse-release-2412-2024-12-19) تغييرًا غير متوافق مع الإصدارات السابقة، بحيث يتم تجاهل قيم `NULL`، بينما كان يُرجِع سابقًا `NULL` إذا كانت إحدى الوسيطات `NULL`.
  للاحتفاظ بالسلوك السابق، اضبط الإعداد `least_greatest_legacy_null_behavior` (الافتراضي: `false`) على `true`.
</Info>

**الصياغة**

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

**الوسائط**

* `x1[, x2, ...]` — قيمة واحدة أو عدة قيم للمقارنة. يجب أن تكون جميع الوسائط من أنواع قابلة للمقارنة. [`Any`](/ar/reference/data-types/index)

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

تُرجِع أكبر قيمة بين الوسائط، مع ترقيتها إلى أوسع نوع متوافق. [`Any`](/ar/reference/data-types/index)

**أمثلة**

**الأنواع الرقمية**

```sql title=Query theme={null}
SELECT greatest(1, 2, toUInt8(3), 3.) AS result, toTypeName(result) AS type;
-- The type returned is a Float64 as the UInt8 must be promoted to 64 bit for the comparison.
```

```response title=Response theme={null}
┌─result─┬─type────┐
│      3 │ Float64 │
└────────┴─────────┘
```

**المصفوفات**

```sql title=Query theme={null}
SELECT greatest(['hello'], ['there'], ['world']);
```

```response title=Response theme={null}
┌─greatest(['hello'], ['there'], ['world'])─┐
│ ['world']                                 │
└───────────────────────────────────────────┘
```

**أنواع DateTime**

```sql title=Query theme={null}
SELECT greatest(toDateTime32(now() + toIntervalDay(1)), toDateTime64(now(), 3));
-- The type returned is a DateTime64 as the DateTime32 must be promoted to 64 bit for the comparison.
```

```response title=Response theme={null}
┌─greatest(toD⋯(now(), 3))─┐
│  2025-05-28 15:50:53.000 │
└──────────────────────────┘
```

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

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

تنفّذ التفريع الشرطي.

* إذا قُيِّم الشرط `cond` إلى قيمة غير صفرية، فتعيد الدالة نتيجة التعبير `then`.
* إذا قُيِّم `cond` إلى صفر أو NULL، فتُعاد نتيجة التعبير `else`.

يتحكّم الإعداد [`short_circuit_function_evaluation`](/ar/reference/settings/session-settings#short_circuit_function_evaluation) في ما إذا كان التقييم المختصر مستخدمًا.

إذا كان مفعّلًا، فلا يُقيَّم التعبير `then` إلا على الصفوف التي تكون فيها قيمة `cond` هي `true`، ويُقيَّم التعبير `else` على الصفوف التي تكون فيها قيمة `cond` هي `false`.

على سبيل المثال، عند استخدام التقييم المختصر، لا يُطرَح استثناء القسمة على صفر عند تنفيذ الاستعلام التالي:

```sql theme={null}
SELECT if(number = 0, 0, intDiv(42, number)) FROM numbers(10)
```

يجب أن يكون `then` و `else` من نوعين متشابهين.

**الصيغة**

```sql theme={null}
if(cond, then, else)
```

**الوسائط**

* `cond` — الشرط الذي يجري تقييمه. [`UInt8`](/ar/reference/data-types/int-uint) أو [`Nullable(UInt8)`](/ar/reference/data-types/nullable) أو [`NULL`](/ar/reference/syntax#null)
* `then` — التعبير المُعاد إذا كانت `cond` تساوي `true`. - `else` — التعبير المُعاد إذا كانت `cond` تساوي `false` أو `NULL`.

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

ناتج أحد التعبيرين `then` أو `else`، حسب الشرط `cond`.

**أمثلة**

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

```sql title=Query theme={null}
SELECT if(1, 2 + 2, 2 + 6) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   4 │
└─────┘
```

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

أُضيف في: v1.1.0

يعيد أصغر قيمة بين الوسائط.
يتم تجاهل الوسائط `NULL`.

* بالنسبة إلى المصفوفات، يعيد المصفوفة الأصغر ترتيبًا معجميًا.
* بالنسبة إلى أنواع DateTime، يُرقّى نوع النتيجة إلى أكبر نوع (على سبيل المثال، DateTime64 عند دمجه مع DateTime32).

<Info>
  **استخدم الإعداد `least_greatest_legacy_null_behavior` لتغيير سلوك `NULL`**

  قدّم الإصدار [24.12](/ar/resources/changelogs/oss/2024#a-id2412a-clickhouse-release-2412-2024-12-19) تغييرًا غير متوافق مع الإصدارات السابقة، بحيث يتم تجاهل قيم `NULL`، بينما كان يعيد سابقًا القيمة `NULL` إذا كان أحد الوسائط `NULL`.
  للاحتفاظ بالسلوك السابق، اضبط الإعداد `least_greatest_legacy_null_behavior` (القيمة الافتراضية: `false`) على `true`.
</Info>

**الصيغة**

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

**الوسائط**

* `x1[, x2, ...]` — قيمة واحدة أو عدة قيم للمقارنة. يجب أن تكون جميع الوسائط من أنواع قابلة للمقارنة. [`Any`](/ar/reference/data-types/index)

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

تُعيد أصغر قيمة بين الوسائط، وتُرقّى إلى أكبر نوع متوافق. [`Any`](/ar/reference/data-types/index)

**أمثلة**

**الأنواع الرقمية**

```sql title=Query theme={null}
SELECT least(1, 2, toUInt8(3), 3.) AS result, toTypeName(result) AS type;
-- The type returned is a Float64 as the UInt8 must be promoted to 64 bit for the comparison.
```

```response title=Response theme={null}
┌─result─┬─type────┐
│      1 │ Float64 │
└────────┴─────────┘
```

**المصفوفات**

```sql title=Query theme={null}
SELECT least(['hello'], ['there'], ['world']);
```

```response title=Response theme={null}
┌─least(['hell⋯ ['world'])─┐
│ ['hello']                │
└──────────────────────────┘
```

**أنواع DateTime**

```sql title=Query theme={null}
SELECT least(toDateTime32(now() + toIntervalDay(1)), toDateTime64(now(), 3));
-- The type returned is a DateTime64 as the DateTime32 must be promoted to 64 bit for the comparison.
```

```response title=Response theme={null}
┌─least(toDate⋯(now(), 3))─┐
│  2025-05-27 15:55:20.000 │
└──────────────────────────┘
```

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

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

يتيح كتابة العامل [`CASE`](/ar/reference/operators/index#conditional-expression) بصورة أكثر اختصارًا في الاستعلام.
يُقيِّم كل شرط بالترتيب. وبالنسبة إلى أول شرط يكون صحيحًا (غير صفري وليس `NULL`)، يُرجِع قيمة الفرع المقابلة.
إذا لم يكن أي من الشروط صحيحًا، فسيُرجِع قيمة `else`.

يتحكم الإعداد [`short_circuit_function_evaluation`](/ar/reference/settings/session-settings#short_circuit_function_evaluation) في
ما إذا كان التقييم المختصر مستخدمًا. وإذا كان مفعّلًا، فلن يُقيَّم التعبير `then_i` إلا على الصفوف التي تكون فيها
`((NOT cond_1) AND ... AND (NOT cond_{i-1}) AND cond_i)` صحيحة.

على سبيل المثال، مع التقييم المختصر، لا يحدث استثناء قسمة على صفر عند تنفيذ الاستعلام التالي:

```sql theme={null}
SELECT multiIf(number = 2, intDiv(1, number), number = 5) FROM numbers(10)
```

يجب أن يكون لجميع تعبيرات الفروع و`else` نوع فائق مشترك. تُعامل الشروط ذات القيمة `NULL` على أنها `false`.

**الصيغة**

```sql theme={null}
multiIf(cond_1, then_1, cond_2, then_2, ..., else)
```

**الأسماء البديلة**: `caseWithoutExpression`, `caseWithoutExpr`

**الوسائط**

* `cond_N` — الشرط المُقيَّم رقم N الذي يحدد ما إذا كانت `then_N` ستُعاد. [`UInt8`](/ar/reference/data-types/int-uint) أو [`Nullable(UInt8)`](/ar/reference/data-types/nullable) أو [`NULL`](/ar/reference/syntax#null)
* `then_N` — ناتج الدالة عندما تكون `cond_N` صحيحة. - `else` — ناتج الدالة إذا لم يتحقق أي من الشروط.

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

تُعيد ناتج `then_N` الموافق لـ `cond_N` المطابق، وإلا فتُعيد قيمة `else`.

**أمثلة**

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

```sql title=Query theme={null}
CREATE TABLE LEFT_RIGHT (left Nullable(UInt8), right Nullable(UInt8)) ENGINE = Memory;
INSERT INTO LEFT_RIGHT VALUES (NULL, 4), (1, 3), (2, 2), (3, 1), (4, NULL);

SELECT
    left,
    right,
    multiIf(left < right, 'left is smaller', left > right, 'left is greater', left = right, 'Both equal', 'Null value') AS result
FROM LEFT_RIGHT;
```

```response title=Response theme={null}
┌─left─┬─right─┬─result──────────┐
│ ᴺᵁᴸᴸ │     4 │ Null value      │
│    1 │     3 │ left is smaller │
│    2 │     2 │ Both equal      │
│    3 │     1 │ left is greater │
│    4 │  ᴺᵁᴸᴸ │ Null value      │
└──────┴───────┴─────────────────┘
```