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

# الدوال المعرّفة من قبل المستخدم في Cloud

> أضف دوال بايثون التنفيذية الخاصة بك إلى Cloud

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                ميزة Beta. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        مزيد من المعلومات.
                    </a>
                </u>
            </span>
        </div>;
};

تتيح الدوال المعرّفة من قبل المستخدم (UDF) للمستخدمين توسيع إمكانات ClickHouse بما يتجاوز ما توفره أكثر من ألف [دالة](/ar/reference/functions/regular-functions/regular-functions-index) جاهزة.

في ClickHouse Cloud، توجد طريقتان لإنشاء الدوال المعرّفة من قبل المستخدم:

1. باستخدام SQL
2. باستخدام UI والتعليمات البرمجية الخاصة بك (الإصدار التجريبي العام)

<div id="sql-udfs">
  ## الدوال المعرّفة من قبل المستخدم في SQL
</div>

يمكن إنشاء UDFs في SQL باستخدام عبارة [`CREATE FUNCTION`](/ar/reference/statements/create/function) انطلاقًا من تعبير lambda.

في هذا المثال، سننشئ دالة معرّفة من قبل المستخدم قابلة للتنفيذ وبسيطة باسم `isBusinessHours`.
ستتحقق الدالة مما إذا كان طابع زمني معيّن يقع ضمن ساعات العمل المعتادة، وستُرجع true إذا كان كذلك، وإلا false.

1. سجّل الدخول إلى Cloud Console وافتح SQL Console
2. اكتب استعلام SQL التالي لإنشاء الدالة `isBusinessHours`:

```sql theme={null}
CREATE FUNCTION isBusinessHours AS (ts) ->
toDayOfWeek(ts) BETWEEN 1 AND 5
AND toHour(ts) BETWEEN 9 AND 17;
```

3. نفّذ ما يلي لاختبار UDF الذي أنشأته للتو:

```sql theme={null}
SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);
```

من المفترض أن تظهر لك النتيجة التالية:

```response theme={null}
1   0
```

4. يمكنك استخدام الأمر `DROP FUNCTION` لإزالة دالة UDF التي أنشأتها للتو:

```sql theme={null}
DROP FUNCTION isBusinessHours
```

<Warning>
  **مهم**

  إن UDFs في ClickHouse Cloud **لا ترث الإعدادات على مستوى المستخدم**. وتُنفَّذ باستخدام إعدادات النظام الافتراضية.
</Warning>

هذا يعني:

* لا تنتقل الإعدادات على مستوى الجلسة (المعيَّنة عبر عبارة `SET`) إلى سياق تنفيذ UDF
* لا ترث UDFs إعدادات ملف تعريف المستخدم
* لا تنطبق الإعدادات على مستوى الاستعلام ضمن تنفيذ UDF

<div id="ui-udfs">
  ## الدوال المُعرَّفة من قبل المستخدم المُنشأة عبر UI
</div>

يوفّر ClickHouse Cloud واجهة إعداد عبر UI لإنشاء الدوال المُعرَّفة من قبل المستخدم.

في هذا المثال، سننشئ الدالة البسيطة نفسها المُعرَّفة من قبل المستخدم والقابلة للتنفيذ `isBusinessHours`، والتي تتحقق مما إذا كان `timestamp` معيّن يقع ضمن ساعات العمل المعتادة.
سبق أن أنشأناها باستخدام SQL، ولكن هذه المرة سننشئها باستخدام بايثون ونُعدّها عبر UI.

<Steps>
  <Step>
    ### أنشئ ملف بايثون

    أنشئ ملفًا جديدًا باسم `main.py` على جهازك المحلي:

    ```python theme={null}
    cat > main.py << 'EOF'
    import sys
    from datetime import datetime

    for line in sys.stdin:
        ts = datetime.fromisoformat(line.strip())
        result = 1 if (0 <= ts.weekday() <= 4 and 9 <= ts.hour <= 17) else 0
        print(result)
        sys.stdout.flush()
    EOF
    ```

    إذا كان سكربت بايثون لديك يستورد حزمًا تابعة لجهات خارجية، فأدرجها في ملف `requirements.txt` وسيتولى ClickHouse Cloud تثبيتها لك. ويمكنك بدلًا من ذلك تضمين التبعيات مباشرةً في ملف ZIP، لكن عندئذٍ يجب تضمين الحزم المخزنة مؤقتًا لكلتا معماريتَي CPU، لذا يُعد `requirements.txt` الخيار الأبسط. على سبيل المثال:

    ```text theme={null}
    requests>=2.28.0
    numpy>=1.23.0
    ```

    <Note>
      تتوقع ClickHouse Cloud أن يكون الملف `main.py` موجودًا داخل ملف zip الذي سترفعه عبر واجهة المستخدم في الخطوة التالية.
      إذا منحت الملف اسمًا آخر، فستواجه خطأً.
    </Note>
  </Step>

  <Step>
    ### تجميع التبعيات والملفات المحلية

    لتضمين حزم التبعيات وأي ملفات محلية إضافية (مثل ملفات wheel أو ملفات الإعداد أو ملفات البيانات)، ضعها في المجلد نفسه إلى جانب `main.py` و`requirements.txt`. عند إنشاء أرشيف ZIP، ضمّن جميع الملفات:

    ```bash theme={null}
    zip is_business_hours.zip main.py requirements.txt
    ```

    يمكنك الإشارة إلى الدليل الأساسي للمسار المحلي المضمَّن في شيفرة بايثون الخاصة بك باستخدام `os.path.dirname(os.path.abspath(__file__))`. يُرجع هذا التعبير المسار المطلق إلى الدليل الذي يوجد فيه ملف `main.py` داخل أرشيف ZIP، مما يتيح لك الوصول إلى الملفات المضمَّنة الأخرى:

    ```python theme={null}
    import os

    # Get the base directory of the bundled files
    base_dir = os.path.dirname(os.path.abspath(__file__))
    config_path = os.path.join(base_dir, 'config.json')
    ```

    يكون ذلك مفيدًا عندما تحتاج إلى:

    * الوصول إلى ملفات التهيئة المضمّنة مع UDF الخاصة بك
    * تحميل حزم wheel للتبعيات المخصّصة
    * الإشارة إلى نصوص برمجية إضافية أو ملفات بيانات

    الآن قم بضغط الملف في أرشيف ZIP:

    ```bash theme={null}
    zip is_business_hours.zip main.py
    ```

    <Warning>
      **الروابط الرمزية غير مسموح بها**

      يرفض ClickHouse Cloud أرشيفات UDF التي تحتوي على روابط رمزية. تأكد من أن حزمة ZIP تحتوي فقط على ملفات ومجلدات عادية — ستفشل عملية التحقق من أي عملية رفع تتضمن روابط رمزية.
    </Warning>
  </Step>

  <Step>
    ### أنشئ UDF عبر واجهة المستخدم

    1. من الصفحة الرئيسية لـ Cloud Console، انقر على اسم مؤسستك في القائمة السفلية اليسرى.
    2. اختر **الدوال المعرّفة من قبل المستخدم** من القائمة.
    3. في صفحة الدوال المعرّفة من قبل المستخدم، انقر على **Set up a UDF**. ستُفتح لوحة إعدادات على الجانب الأيمن من الشاشة.
    4. أدخل اسمًا للدالة. في هذا المثال، استخدم `isBusinessHours`.
    5. اختر نوع الدالة: إما **Executable pool** أو **Executable**:
       * **Executable pool**: يُحفَظ pool من العمليات المستمرة، وتُؤخَذ منه عملية لتنفيذ reads.
       * **Executable**: يُشغَّل السكربت مع كل query.
    6. في هذا المثال، استخدم الإعدادات الافتراضية. للاطلاع على القائمة الكاملة لمعلمات الإعداد، راجع [الدوال المعرّفة من قبل المستخدم التنفيذية](/ar/reference/functions/regular-functions/udf#executable-user-defined-functions).
    7. انقر على **Browse File** لتحميل ملف `.zip` الذي أُنشئ في بداية هذا الدليل.
    8. أضف argument جديدًا. في هذا المثال، أضف argument باسم `timestamp` من النوع `DateTime`.
    9. اختر return type. في هذا المثال، اختر `Bool`.
    10. انقر على **Create UDF**. سيعرض مربع حوار حالة build الحالية.
        * إذا كانت هناك أي مشكلات، فستتغير الحالة إلى **error**.
        * بخلاف ذلك، ستنتقل الحالة من **building** إلى **provisioning**. يجب أن تكون الخدمة في حالة تشغيل لإكمال provisioning. إذا كانت الخدمة في حالة idle، فانقر على **Wake Up Service** في لوحة **UDF details** بجوار اسم الخدمة.
        * عند اكتمال العملية، ستتغير الحالة إلى **deployed**.
  </Step>

  <Step>
    ### اختبر UDF الخاص بك

    1. ارجع إلى الصفحة الرئيسية في **SQL Console** بالنقر على **Settings - return to your service view** من الزاوية العلوية اليسرى للصفحة
    2. انقر على **SQL Console** في القائمة الجانبية اليسرى
    3. اكتب الاستعلام التالي:

    ```sql theme={null}
    SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);
    ```

    من المفترض أن تظهر لك النتيجة:

    ```response theme={null}
    true    false
    ```
  </Step>

  <Step>
    ### إنشاء إصدار جديد

    لتغيير شيفرة UDF، أنشئ إصدارًا جديدًا. لا تُستخدم لوحة **Edit** إلا لإدارة الخدمات المُسنَدة إلى UDF؛ ولن يؤدي رفع ملف من خلالها إلى استبدال الشيفرة المنشورة.

    1. من الصفحة الرئيسية في Cloud Console، انقر على اسم مؤسستك في القائمة السفلية اليسرى.
    2. اختر **الدوال المعرّفة من قبل المستخدم** من القائمة.
    3. انقر على النقاط الثلاث ضمن **الإجراءات** الخاصة بـ UDF ‏`isBusinessHours`، ثم انقر على **إنشاء إصدار جديد**
    4. ارفع ملف zip يتضمن الشيفرة المعدّلة، أو غيّر الإعدادات ثم انقر على **إنشاء إصدار جديد**

    لقد أضفت بنجاح أول دالة معرّفة من قبل المستخدم عبر UI، وتحققت من أنها تعمل، ورأيت كيفية إنشاء إصدار جديد لها عند الحاجة.
  </Step>
</Steps>