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

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

تتيح الدوال المعرّفة من قبل المستخدم (UDF) للمستخدمين توسيع إمكانات ClickHouse بما يتجاوز ما توفره أكثر من ألف دالة جاهزة.

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

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

​

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

يمكن إنشاء UDFs في SQL باستخدام عبارة CREATE FUNCTION انطلاقًا من تعبير lambda.

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

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

CREATE FUNCTION isBusinessHours AS (ts) ->
toDayOfWeek(ts) BETWEEN 1 AND 5
AND toHour(ts) BETWEEN 9 AND 17;

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

SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);

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

1   0

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

DROP FUNCTION isBusinessHours

مهم

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

هذا يعني:

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

​

الدوال المُعرَّفة من قبل المستخدم المُنشأة عبر UI

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

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

1. ​

   أنشئ ملف بايثون

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

   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 الخيار الأبسط. على سبيل المثال:

   requests>=2.28.0
   numpy>=1.23.0
   

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

2. ​

   تجميع التبعيات والملفات المحلية

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

   zip is_business_hours.zip main.py requirements.txt
   

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

   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:

   zip is_business_hours.zip main.py
   

   الروابط الرمزية غير مسموح بها

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

3. ​

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

   1. من الصفحة الرئيسية لـ Cloud Console، انقر على اسم مؤسستك في القائمة السفلية اليسرى.
   2. اختر الدوال المعرّفة من قبل المستخدم من القائمة.
   3. في صفحة الدوال المعرّفة من قبل المستخدم، انقر على Set up a UDF. ستُفتح لوحة إعدادات على الجانب الأيمن من الشاشة.
   4. أدخل اسمًا للدالة. في هذا المثال، استخدم isBusinessHours.
   5. اختر نوع الدالة: إما Executable pool أو Executable:
      • Executable pool: يُحفَظ pool من العمليات المستمرة، وتُؤخَذ منه عملية لتنفيذ reads.
      • Executable: يُشغَّل السكربت مع كل query.
   6. في هذا المثال، استخدم الإعدادات الافتراضية. للاطلاع على القائمة الكاملة لمعلمات الإعداد، راجع الدوال المعرّفة من قبل المستخدم التنفيذية.
   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.
4. ​

   اختبر UDF الخاص بك

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

   SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);
   

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

   true    false
   
5. ​

   إنشاء إصدار جديد

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

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

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