الدوال المعرّفة من قبل المستخدم (UDFs)

• تبدأ UDFs القابلة للتنفيذ برنامجًا خارجيًا أو برنامجًا نصيًا (بايثون، Bash، إلخ)، وتُمرِّر إليه blocks من البيانات عبر STDIN / STDOUT. استخدمها لدمج التعليمات البرمجية أو الأدوات الحالية دون الحاجة إلى إعادة تجميع ClickHouse. وهي تفرض overhead أعلى لكل استدعاء مقارنةً بالخيارات التي تعمل داخل العملية، لذا فهي الأنسب للمنطق الأثقل أو عند الحاجة إلى runtime مختلف.
• تُعرَّف SQL UDFs باستخدام CREATE FUNCTION بالكامل ضمن SQL. وتُضمَّن/تُوسَّع داخل query plan (من دون حدٍّ فاصل على مستوى العملية)، مما يجعلها lightweight ومثالية لإعادة استخدام منطق expression أو تبسيط columns المحسوبة المعقدة.
• تُشغِّل Experimental WebAssembly UDFs تعليمات برمجية مُجمَّعة إلى WebAssembly داخل sandbox ضمن server process. وهي توفّر overhead أقل لكل استدعاء مقارنةً بالبرامج التنفيذية الخارجية، مع عزل أفضل من الامتدادات native، مما يجعلها مناسبة للخوارزميات المخصّصة المكتوبة بلغات يمكنها الاستهداف إلى WASM (مثل C/C++/Rust).
• تتيح Experimental UDFs القابلة للتنفيذ المعتمدة على برامج التشغيل لـ برنامج التشغيل يوفّره المشغّل أن يحوّل مقطع شيفرة مُقدَّمًا في CREATE FUNCTION ... ENGINE = DriverName(...) AS '...' إلى UDF قابلة للتنفيذ عند وقت إنشاء الدالة (على سبيل المثال، عن طريق تجميعه). وهي تستند إلى UDFs القابلة للتنفيذ وتتطلب إعداد برنامج التشغيل على جانب server.

​

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

​

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

​

أمثلة

​

UDF من برنامج نصي مضمن

<functions>
    <function>
        <type>executable</type>
        <name>test_function_sum</name>
        <return_type>UInt64</return_type>
        <argument>
            <type>UInt64</type>
            <name>lhs</name>
        </argument>
        <argument>
            <type>UInt64</type>
            <name>rhs</name>
        </argument>
        <format>TabSeparated</format>
        <command>cd /; clickhouse-local --input-format TabSeparated --output-format TabSeparated --structure 'x UInt64, y UInt64' --query "SELECT x + y FROM table"</command>
        <execute_direct>0</execute_direct>
        <deterministic>true</deterministic>
    </function>
</functions>

functions:
  type: executable
  name: test_function_sum
  return_type: UInt64
  argument:
    - type: UInt64
      name: lhs
    - type: UInt64
      name: rhs
  format: TabSeparated
  command: 'cd /; clickhouse-local --input-format TabSeparated --output-format TabSeparated --structure ''x UInt64, y UInt64'' --query "SELECT x + y FROM table"'
  execute_direct: 0
  deterministic: true

SELECT test_function_sum(2, 2);

┌─test_function_sum(2, 2)─┐
│                       4 │
└─────────────────────────┘

​

UDF من برنامج نصي بايثون

<functions>
    <function>
        <type>executable</type>
        <name>test_function_python</name>
        <return_type>String</return_type>
        <argument>
            <type>UInt64</type>
            <name>value</name>
        </argument>
        <format>TabSeparated</format>
        <command>test_function.py</command>
    </function>
</functions>

functions:
  type: executable
  name: test_function_python
  return_type: String
  argument:
    - type: UInt64
      name: value
  format: TabSeparated
  command: test_function.py

#!/usr/bin/python3

import sys

if __name__ == '__main__':
    for line in sys.stdin:
        print("Value " + line, end='')
        sys.stdout.flush()

SELECT test_function_python(toUInt64(2));

┌─test_function_python(2)─┐
│ Value 2                 │
└─────────────────────────┘

​

اقرأ قيمتين من STDIN وأعِد مجموعهما على شكل كائن JSON

<functions>
    <function>
        <type>executable</type>
        <name>test_function_sum_json</name>
        <return_type>UInt64</return_type>
        <return_name>result_name</return_name>
        <argument>
            <type>UInt64</type>
            <name>argument_1</name>
        </argument>
        <argument>
            <type>UInt64</type>
            <name>argument_2</name>
        </argument>
        <format>JSONEachRow</format>
        <command>test_function_sum_json.py</command>
    </function>
</functions>

functions:
  type: executable
  name: test_function_sum_json
  return_type: UInt64
  return_name: result_name
  argument:
    - type: UInt64
      name: argument_1
    - type: UInt64
      name: argument_2
  format: JSONEachRow
  command: test_function_sum_json.py

#!/usr/bin/python3

import sys
import json

if __name__ == '__main__':
    for line in sys.stdin:
        value = json.loads(line)
        first_arg = int(value['argument_1'])
        second_arg = int(value['argument_2'])
        result = {'result_name': first_arg + second_arg}
        print(json.dumps(result), end='\n')
        sys.stdout.flush()

SELECT test_function_sum_json(2, 2);

┌─test_function_sum_json(2, 2)─┐
│                            4 │
└──────────────────────────────┘

​

استخدام المعلمات في إعداد command

<functions>
    <function>
        <type>executable</type>
        <execute_direct>true</execute_direct>
        <name>test_function_parameter_python</name>
        <return_type>String</return_type>
        <argument>
            <type>UInt64</type>
        </argument>
        <format>TabSeparated</format>
        <command>test_function_parameter_python.py {test_parameter:UInt64}</command>
    </function>
</functions>

functions:
  type: executable
  execute_direct: true
  name: test_function_parameter_python
  return_type: String
  argument:
    - type: UInt64
  format: TabSeparated
  command: test_function_parameter_python.py {test_parameter:UInt64}

#!/usr/bin/python3

import sys

if __name__ == "__main__":
    for line in sys.stdin:
        print("Parameter " + str(sys.argv[1]) + " value " + str(line), end="")
        sys.stdout.flush()

SELECT test_function_parameter_python(1)(2);

┌─test_function_parameter_python(1)(2)─┐
│ Parameter 1 value 2                  │
└──────────────────────────────────────┘

​

UDF من برنامج نصي shell

<functions>
    <function>
        <type>executable</type>
        <name>test_shell</name>
        <return_type>String</return_type>
        <argument>
            <type>UInt8</type>
            <name>value</name>
        </argument>
        <format>TabSeparated</format>
        <command>test_shell.sh</command>
    </function>
</functions>

functions:
  type: executable
  name: test_shell
  return_type: String
  argument:
    - type: UInt8
      name: value
  format: TabSeparated
  command: test_shell.sh

#!/bin/bash

while read read_data;
    do printf "$(expr $read_data \* 2)\n";
done

SELECT test_shell(number) FROM numbers(10);

    ┌─test_shell(number)─┐
 1. │ 0                  │
 2. │ 2                  │
 3. │ 4                  │
 4. │ 6                  │
 5. │ 8                  │
 6. │ 10                 │
 7. │ 12                 │
 8. │ 14                 │
 9. │ 16                 │
10. │ 18                 │
    └────────────────────┘

​

معالجة الأخطاء

​

تقييم تعبيرات الوسائط

​

تنفيذ الدوال في معالجة الاستعلامات الموزعة

• إذا كان distributed_table يحتوي على shardين على الأقل، فستُنفَّذ الدالتان ‘g’ و ‘h’ على الخوادم البعيدة، بينما تُنفَّذ الدالة ‘f’ على الخادم الطالب.
• إذا كان distributed_table يحتوي على shard واحد فقط، فستُنفَّذ جميع الدوال ‘f’ و ‘g’ و ‘h’ على خادم هذا الـ shard.

​

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

​

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

​

البدء السريع

<clickhouse>
    <allow_experimental_webassembly_udf>true</allow_experimental_webassembly_udf>
</clickhouse>

INSERT INTO system.webassembly_modules (name, code)
SELECT 'my_module', base64Decode('AGFzbQEAAAA...');

CREATE FUNCTION my_function
LANGUAGE WASM
ABI ROW_DIRECT
FROM 'my_module'
ARGUMENTS (x UInt32, y UInt32)
RETURNS UInt32;

SELECT my_function(10, 20);

​

مزيد من المعلومات

​

الدوال المعرّفة من قبل المستخدم القابلة للتنفيذ المعتمد على برامج التشغيل

​

تمكين برامج التشغيل

1. عيّن خيار Experimental في إعدادات الخادم:
   <clickhouse>
       <allow_experimental_executable_udf_drivers>true</allow_experimental_executable_udf_drivers>
   </clickhouse>
   
2. وجّه user_defined_executable_function_drivers_config إلى ملف configuration واحد أو أكثر لبرامج التشغيل (مع دعم نمط glob)، واضبط اختياريًا dynamic_user_defined_executable_functions_path، وهو الدليل الذي تُخزَّن فيه ملفات configuration المُولَّدة الخاصة بـ UDFs القابلة للتنفيذ:
   <clickhouse>
       <user_defined_executable_function_drivers_config>user_defined_executable_function_drivers_config.d/*_driver.xml</user_defined_executable_function_drivers_config>
       <dynamic_user_defined_executable_functions_path>/var/lib/clickhouse/dynamic_user_defined_executable_functions/</dynamic_user_defined_executable_functions_path>
   </clickhouse>
   

​

إعداد برنامج التشغيل

<clickhouse>
    <driver>
        <name>DockerC</name>
        <create_command>../user_defined_executable_function_drivers/docker_c_create.sh</create_command>
        <drop_command>../user_defined_executable_function_drivers/docker_c_drop.sh</drop_command>
        <engine_arguments>
            <opt_level><required>false</required></opt_level>
        </engine_arguments>
        <env>
            <CLICKHOUSE_C_DRIVER_MEMORY>256m</CLICKHOUSE_C_DRIVER_MEMORY>
            <CLICKHOUSE_C_DRIVER_CPUS>1.0</CLICKHOUSE_C_DRIVER_CPUS>
        </env>
    </driver>
</clickhouse>

​

بروتوكول استدعاء برنامج التشغيل

• --name <function_name>
• --return <return_type> (إذا وُجد بند RETURNS)
• --args <signature> (إذا وُجد بند ARGUMENTS)، حيث يمثّل التوقيع قائمة الوسيطات المعلنة، مثل x UInt8, y DateTime
• --<key> <value> لكل وسيط engine مُعلن وممرَّر في ENGINE = DriverName(key = value)

​

إنشاء function

CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS] name [ON CLUSTER cluster]
    ARGUMENTS (a UInt8, b String) RETURNS UInt64
    ENGINE = DriverName(key1 = 'value1', key2 = 42)
    AS '...code body...'

​

حذف دالة

DROP FUNCTION [IF EXISTS] name [ON CLUSTER cluster]

​

الاستمرارية وإعادة التشغيل

​

القيود

• هذه الميزة تجريبية ولا تتاح إلا عند تفعيل allow_experimental_executable_udf_drivers.
• الدوال المستندة إلى برامج التشغيل غير مدعومة مع التخزين المُكرَّر للدوال المعرّفة من قبل المستخدم (ON CLUSTER و <user_defined_zookeeper_path>)، لأن الاستعلام الأصلي فقط هو الذي يُكرَّر، وليس الملفات الناتجة.
• تؤدي عملية RESTORE لدالة مستندة إلى برنامج تشغيل جرى أخذ نسخة احتياطية لها إلى الاحتفاظ بالاستعلام، لكنها لا تعيد تشغيل برنامج التشغيل؛ إذ تُطبَّق التهيئة المُولَّدة وتُحفَظ لاحقًا أثناء استرداد إعادة التشغيل.

​

مثال على برامج تشغيل C

• DockerC - يترجم الشيفرة ويشغّلها داخل حاويات Docker معزولة (--network=none --read-only --cap-drop=ALL --security-opt=no-new-privileges، بالإضافة إلى حدود الذاكرة/CPU/PID)، ويُنتج UDF من النوع executable_pool.
• GVisorC - نسخة بديلة تشغّل الملف التنفيذي المترجم ضمن بيئة التشغيل gVisor runsc.
• UnsafeC - يترجم الشيفرة ويشغّلها مباشرة على المضيف من دون sandbox. وكما يوحي الاسم، فهو لا يوفّر أي عزل، وهو مخصّص فقط للبيئات الموثوقة ولأغراض الاختبار.

​

محتوى ذو صلة

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