> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> نسّق استعلامات ClickHouse وعمليات تحميل البيانات من Apache Airflow باستخدام موفّر ClickHouse

# ربط Apache Airflow بـ ClickHouse

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            متوافق مع ClickHouse
        </div>;
};

<ClickHouseSupportedBadge />

تُعد [Apache Airflow](https://airflow.apache.org/) منصة مفتوحة المصدر لتأليف سير العمل وجدولته ومراقبته على شكل شيفرة. ويُعرَّف سير العمل على هيئة رسوم بيانية موجهة لا دورية (DAGs) تتكوّن من مهام مكتوبة بلغة بايثون.

يربط موفّر `apache-airflow-providers-clickhousedb` بين Airflow وClickHouse، مما يتيح لك تشغيل الاستعلامات وإنشاء الجداول وتحميل البيانات كجزء من DAG. ويتصل عبر [واجهة HTTP](/docs/ar/concepts/features/interfaces/http) باستخدام عميل [`clickhouse-connect`](/docs/ar/integrations/language-clients/python/index)، كما يوفّر ClickHouse من خلال إطار SQL الشائع في Airflow، بحيث يتولى `SQLExecuteQueryOperator` القياسي تنفيذ استعلامات DDL وDML والاستعلامات التحليلية من دون الحاجة إلى مشغّل خاص بـ ClickHouse.

<div id="install-the-provider">
  ## ثبّت الموفّر
</div>

ثبّت الموفّر في البيئة التي يعمل فيها مجدول Airflow والعمّال لديك:

```bash theme={null}
pip install apache-airflow-providers-clickhousedb
```

يعتمد هذا الموفّر على `apache-airflow-providers-common-sql` و`clickhouse-connect`، ويُثبَّتان معه. لتمرير نتائج الاستعلام إلى كائنات DataFrame في pandas أو polars، ثبّت الإضافات الاختيارية التالية:

```bash theme={null}
pip install 'apache-airflow-providers-common-sql[pandas,polars]'
```

<div id="create-a-clickhouse-connection">
  ## إنشاء اتصال ClickHouse
</div>

يسجّل الموفّر نوع اتصال باسم `clickhouse`. أنشئ اتصالًا من واجهة Airflow ضمن **Admin > Connections**، أو عرّفه عبر CLI أو من خلال متغير بيئة.

في واجهة المستخدم، اختر **ClickHouse** كنوع الاتصال واملأ الحقول التالية:

| الحقل        | الوصف                                                                                                                                          | القيمة الافتراضية           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Host**     | اسم مضيف خادم ClickHouse، على سبيل المثال `abc123.clickhouse.cloud`                                                                            | `localhost`                 |
| **Port**     | منفذ HTTP(S)                                                                                                                                   | `8123` (عادي)، `8443` (TLS) |
| **Login**    | اسم مستخدم ClickHouse                                                                                                                          | `default`                   |
| **Password** | كلمة مرور مستخدم ClickHouse                                                                                                                    | (فارغة)                     |
| **Database** | قاعدة البيانات الافتراضية للاتصال. تعرض واجهة المستخدم هذا الحقل باسم **Database**؛ وهو الحقل `schema` عند تعريف الاتصال باستخدام URI أو JSON. | `default`                   |

بالنسبة إلى [ClickHouse Cloud](/docs/ar/products/cloud/getting-started/intro) أو أي عنقود مستضاف ذاتيًا مع تمكين TLS، اضبط `secure` على `true` في حقل **Extra** واستخدم منفذ TLS (`8443`).

<div id="extra-connection-options">
  ### خيارات الاتصال الإضافية
</div>

يوفّر الموفّر خيارات إضافية كحقول مخصّصة في نموذج الاتصال. وإذا عرّفت الاتصال باستخدام URI أو JSON أو متغيّر بيئة بدلًا من ذلك، فأرسلها كمفاتيح ضمن كائن JSON ‏`extra`. جميعها اختيارية:

| `extra` key            | UI field                  | Default | Description                                                                                                                                                          |
| ---------------------- | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secure`               | استخدام TLS ‏(HTTPS)      | `false` | يفعّل HTTPS/TLS.                                                                                                                                                     |
| `verify`               | التحقق من SSL certificate | `true`  | يتحقق من certificate الخاصة بـ TLS على server عندما تكون قيمة `secure` هي `true`. اضبطه على `false` عند استخدام شهادات موقّعة ذاتيًا.                                |
| `connect_timeout`      | مهلة الاتصال (بالثواني)   | `10`    | مهلة HTTP اتصال بالثواني.                                                                                                                                            |
| `send_receive_timeout` | مهلة الاستعلام (seconds)  | `300`   | مهلة القراءة/الكتابة الخاصة بالاستعلام بالثواني. زِد هذه القيمة للاستعلامات التحليلية طويلة التشغيل.                                                                 |
| `compress`             | تفعيل ضغط LZ4             | `true`  | يفعّل ضغط نتائج LZ4.                                                                                                                                                 |
| `client_name`          | اسم Client                | (empty) | تسمية تُلحَق بمعرّف إصدار Airflow في `User-Agent` الخاص بـ ClickHouse وفي العمود `client_name` من [`system.query_log`](/docs/ar/reference/system-tables/query_log).       |
| `session_settings`     | إعدادات الجلسة (JSON)     | (empty) | [إعدادات الجلسة في ClickHouse](/docs/ar/reference/settings/session-settings) التي تُطبَّق على كل استعلام في الاتصال، مثل `{"max_execution_time": 300, "max_threads": 8}`. |
| `client_kwargs`        | Client kwargs (JSON)      | (empty) | keyword arguments إضافية تُمرَّر إلى `clickhouse_connect.get_client()`، مثل `http_proxy`.                                                                            |

<div id="define-a-connection-without-the-ui">
  ### حدِّد اتصالًا من دون واجهة المستخدم
</div>

اضبط الاتصال عبر متغيّر بيئة. ويشمل تنسيق URI كلًا من المضيف وبيانات الاعتماد وقاعدة البيانات:

```bash theme={null}
export AIRFLOW_CONN_CLICKHOUSE_DEFAULT='clickhouse://default:password@localhost:8123/my_database'
```

يجب ترميز جميع مكوّنات URI باستخدام ترميز URL. بالنسبة إلى TLS ومهلات الانتظار وإعدادات الجلسة، استخدم صيغة JSON التي تُظهر حقول **Extra**:

```bash theme={null}
export AIRFLOW_CONN_CLICKHOUSE_DEFAULT='{
    "conn_type": "clickhouse",
    "host": "abc123.clickhouse.cloud",
    "port": 8443,
    "login": "default",
    "password": "secret",
    "schema": "my_database",
    "extra": {
        "secure": true,
        "session_settings": {
            "max_execution_time": 300,
            "max_memory_usage": 10000000000
        }
    }
}'
```

تستخدم جميع الـ hooks والـ operators معرّف الاتصال `clickhouse_default` ما لم تحدد معرّفًا آخر.

<div id="run-queries">
  ## تشغيل الاستعلامات باستخدام SQLExecuteQueryOperator
</div>

اضبط قيمة `conn_id` للمشغّل بحيث تشير إلى اتصال ClickHouse لديك. ينشئ DAG التالي جدولًا، ويدرج صفوفًا، ثم يقرؤها مرة أخرى، ثم يحذف الجدول:

```python theme={null}
from datetime import datetime

from airflow import DAG
from airflow.providers.common.sql.hooks.sql import fetch_all_handler
from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator

CLICKHOUSE_CONN_ID = "clickhouse_default"
CLICKHOUSE_TABLE = "airflow_example"

with DAG(
    dag_id="example_clickhouse",
    start_date=datetime(2021, 1, 1),
    default_args={"conn_id": CLICKHOUSE_CONN_ID},
    schedule="@once",
    catchup=False,
) as dag:
    create_table = SQLExecuteQueryOperator(
        task_id="create_table",
        sql=f"""
            CREATE TABLE IF NOT EXISTS {CLICKHOUSE_TABLE} (
                id   UInt32,
                name String,
                ts   DateTime DEFAULT now()
            ) ENGINE = MergeTree()
            ORDER BY id
        """,
    )

    insert_rows = SQLExecuteQueryOperator(
        task_id="insert_rows",
        sql=f"""
            INSERT INTO {CLICKHOUSE_TABLE} (id, name) VALUES
                (1, 'Alice'),
                (2, 'Bob'),
                (3, 'Charlie')
        """,
    )

    read_rows = SQLExecuteQueryOperator(
        task_id="read_rows",
        sql=f"SELECT id, name FROM {CLICKHOUSE_TABLE} ORDER BY id",
        handler=fetch_all_handler,
    )

    drop_table = SQLExecuteQueryOperator(
        task_id="drop_table",
        sql=f"DROP TABLE IF EXISTS {CLICKHOUSE_TABLE}",
    )

    create_table >> insert_rows >> read_rows >> drop_table
```

تُسترجَع نتائج الاستعلام باستخدام `handler` الافتراضي (`fetch_all_handler`). ولإرجاع شيء آخر غير مجموعة النتائج الكاملة، مرِّر معالجًا مختلفًا، مثل `fetch_one_handler` لإرجاع الصف الأول فقط.

<div id="target-a-different-database">
  ### استهدف قاعدة بيانات مختلفة لكل مهمة
</div>

عندما يكون اتصال واحد موجّهًا إلى عنقود وتنفّذ المهام الفردية استعلامات على قواعد بيانات مختلفة، فعيّن قاعدة البيانات عبر `hook_params` بدلًا من إنشاء اتصال منفصل:

```python theme={null}
read_rows = SQLExecuteQueryOperator(
    task_id="read_rows",
    conn_id=CLICKHOUSE_CONN_ID,
    sql="SELECT count() FROM events",
    hook_params={"database": "analytics"},
)
```

<div id="use-the-hook-directly">
  ## استخدم الخطاف مباشرة
</div>

بالنسبة إلى الأعمال التي لا تناسب مُعامل SQL — مثل الإدراجات المجمّعة، أو التدفق، أو استدعاءات العميل الخاصة بـ ClickHouse — استخدم `ClickHouseHook` داخل مهمة في بايثون.

تستخدم الطريقة `bulk_insert_rows` الخاصة بالخطاف مسار الإدراج العمودي الأصلي في `clickhouse-connect`، وهو أسرع بكثير من الإدراج صفًا بصف عند التعامل مع مجموعات بيانات كبيرة. اضبط `batch_size` للحد من ذروة الذاكرة عند التعامل مع مدخلات كبيرة جدًا:

```python theme={null}
from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook

hook = ClickHouseHook(clickhouse_conn_id="clickhouse_default")

hook.bulk_insert_rows(
    table="events",
    rows=[("user1", "click"), ("user2", "view")],
    column_names=["user_id", "action"],
    batch_size=1000,
)
```

استدعِ `get_client()` للوصول إلى عميل `clickhouse-connect` الداخلي لأي شيء لا يتيحه الخطاف مباشرةً:

```python theme={null}
client = hook.get_client()
total = client.query("SELECT count() FROM events").result_rows[0][0]
```

<div id="apply-session-settings">
  ### تطبيق إعدادات الجلسة
</div>

مرِّر [إعدادات الجلسة](/docs/ar/reference/settings/session-settings) عند إنشاء الـ خطاف، إما مباشرةً أو عبر `hook_params` الخاص بالمشغّل. وتُدمَج الإعدادات المُمرَّرة إلى المُنشئ مع أي `session_settings` مُعرَّفة في حقل **Extra** الخاص بالاتصال، وتكون لقيم المُنشئ الأولوية عند تعارض المفاتيح:

```python theme={null}
hook = ClickHouseHook(
    clickhouse_conn_id="clickhouse_default",
    session_settings={"max_execution_time": 60, "max_threads": 4},
)
```

<div id="related-content">
  ## محتوى مرتبط
</div>

* [`clickhouse-connect` عميل بايثون](/docs/ar/integrations/language-clients/python/index)
* [واجهة ClickHouse HTTP](/docs/ar/concepts/features/interfaces/http)
* [مرجع إعدادات جلسة ClickHouse](/docs/ar/reference/settings/session-settings)
* [الوثائق المرجعية لـ `apache-airflow-providers-clickhousedb`](https://airflow.apache.org/docs/apache-airflow-providers-clickhousedb/)
* [حزمة الموفّر على PyPI](https://pypi.org/project/apache-airflow-providers-clickhousedb/)