> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> دمج ClickHouse مع Databricks

# دمج ClickHouse مع Databricks

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>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

يعمل موصل ClickHouse Spark بسلاسة مع Databricks. يوضّح هذا الدليل كيفية الإعداد والتثبيت وأساليب الاستخدام الخاصة بـ Databricks.

<div id="api-selection">
  ## اختيار واجهة برمجة تطبيقات لـ Databricks
</div>

افتراضيًا، يستخدم Databricks ‏Unity Catalog، مما يمنع تسجيل الكتالوج في Spark. في هذه الحالة، **يجب** عليك استخدام **واجهة برمجة تطبيقات TableProvider** (الوصول المستند إلى التنسيق).

ومع ذلك، إذا عطّلت Unity Catalog عبر إنشاء عنقود باستخدام وضع الوصول **No isolation shared**، يمكنك استخدام **واجهة برمجة تطبيقات Catalog** بدلًا من ذلك. توفّر **واجهة برمجة تطبيقات Catalog** تهيئة مركزية وتكاملًا أصليًا مع Spark SQL.

| حالة Unity Catalog              | واجهة برمجة تطبيقات الموصى بها                        | ملاحظات                                         |
| ------------------------------- | ----------------------------------------------------- | ----------------------------------------------- |
| **مُمكّن** (افتراضيًا)          | واجهة برمجة تطبيقات TableProvider (مستند إلى التنسيق) | تمنع Unity Catalog تسجيل الكتالوج في Spark      |
| **معطّل** (No isolation shared) | واجهة برمجة تطبيقات Catalog                           | يتطلب عنقودًا بوضع الوصول "No isolation shared" |

<div id="installation">
  ## التثبيت في Databricks
</div>

<div id="installation-ui">
  ### الخيار 1: رفع JAR عبر واجهة مستخدم Databricks
</div>

1. ابنِ ملف JAR الخاص ببيئة التشغيل أو [نزّله](https://repo1.maven.org/maven2/com/clickhouse/spark/):
   ```bash theme={null}
   clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar
   ```

2. ارفع ملف JAR إلى مساحة العمل في Databricks:
   * انتقل إلى **Workspace** → ثم إلى المجلد المطلوب
   * انقر على **Upload** → ثم اختر ملف JAR
   * سيُحفَظ ملف JAR في مساحة العمل الخاصة بك

3. ثبّت المكتبة على العنقود:
   * انتقل إلى **Compute** → ثم اختر العنقود الخاص بك
   * انقر على علامة التبويب **Libraries**
   * انقر على **Install New**
   * اختر **DBFS** أو **Workspace** → ثم انتقل إلى ملف JAR الذي رفعته
   * انقر على **Install**

<Image img={require('@site/images/integrations/data-ingestion/apache-spark/databricks/databricks-libraries-tab.png')} alt="علامة التبويب Libraries في Databricks" />

<Image img={require('@site/images/integrations/data-ingestion/apache-spark/databricks/databricks-install-from-volume.png')} alt="تثبيت المكتبة من وحدة تخزين مساحة العمل" />

4. أعد تشغيل العنقود لتحميل المكتبة

<div id="installation-cli">
  ### الخيار 2: التثبيت باستخدام Databricks CLI
</div>

```bash theme={null}
# Upload JAR to DBFS
databricks fs cp clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar \
  dbfs:/FileStore/jars/

# Install on cluster
databricks libraries install \
  --cluster-id <your-cluster-id> \
  --jar dbfs:/FileStore/jars/clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar
```

<div id="installation-maven">
  ### الخيار 3: إحداثيات Maven (موصى به)
</div>

1. انتقل إلى مساحة عمل Databricks الخاصة بك:
   * انتقل إلى **Compute** → اختر العنقود الخاص بك
   * انقر على علامة التبويب **Libraries**
   * انقر على **Install New**
   * اختر علامة التبويب **Maven**

2. أضف إحداثيات Maven:

```text theme={null}
com.clickhouse.spark:clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}:{{ stable_version }}
```

<Image img={require('@site/images/integrations/data-ingestion/apache-spark/databricks/databricks-maven-tab.png')} alt="إعداد مكتبات Maven في Databricks" />

3. انقر على **تثبيت** ثم أعد تشغيل العنقود لتحميل المكتبة

<div id="tableprovider-api">
  ## استخدام TableProvider API
</div>

عندما يكون Unity Catalog مفعّلًا (افتراضيًا)، **يجب** عليك استخدام TableProvider API (الوصول المستند إلى التنسيق)، لأن Unity Catalog يمنع تسجيل الكتالوج في Spark. وإذا كنت قد عطّلت Unity Catalog باستخدام عنقود بوضع الوصول "No isolation shared"، فيمكنك استخدام [Catalog API](/ar/integrations/connectors/data-ingestion/apache-spark/spark-native-connector#register-the-catalog-required) بدلًا من ذلك.

<div id="reading-data-table-provider">
  ### قراءة البيانات
</div>

<Tabs>
  <Tab title="بايثون">
    ```python theme={null}
    # قراءة البيانات من ClickHouse باستخدام TableProvider API
    df = spark.read \
        .format("clickhouse") \
        .option("host", "your-clickhouse-cloud-host.clickhouse.cloud") \
        .option("protocol", "https") \
        .option("http_port", "8443") \
        .option("database", "default") \
        .option("table", "events") \
        .option("user", "default") \
        .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
        .option("ssl", "true") \
        .load()

    # يتم استنتاج المخطط تلقائيًا
    df.display()
    ```
  </Tab>

  <Tab title="سكالا">
    ```scala theme={null}
    val df = spark.read
      .format("clickhouse")
      .option("host", "your-clickhouse-cloud-host.clickhouse.cloud")
      .option("protocol", "https")
      .option("http_port", "8443")
      .option("database", "default")
      .option("table", "events")
      .option("user", "default")
      .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
      .option("ssl", "true")
      .load()

    df.show()
    ```
  </Tab>
</Tabs>

<div id="writing-data-unity">
  ### كتابة البيانات
</div>

<Tabs>
  <Tab title="بايثون">
    ```python theme={null}
    # الكتابة إلى ClickHouse - سيُنشأ الجدول تلقائيًا إذا لم يكن موجودًا
    df.write \
        .format("clickhouse") \
        .option("host", "your-clickhouse-cloud-host.clickhouse.cloud") \
        .option("protocol", "https") \
        .option("http_port", "8443") \
        .option("database", "default") \
        .option("table", "events_copy") \
        .option("user", "default") \
        .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
        .option("ssl", "true") \
        .option("order_by", "id") \  # مطلوب: حدِّد ORDER BY عند إنشاء جدول جديد
        .option("settings.allow_nullable_key", "1") \  # مطلوب في ClickHouse Cloud إذا كان ORDER BY يتضمن أعمدة Nullable
        .mode("append") \
        .save()
    ```
  </Tab>

  <Tab title="سكالا">
    ```scala theme={null}
    df.write
      .format("clickhouse")
      .option("host", "your-clickhouse-cloud-host.clickhouse.cloud")
      .option("protocol", "https")
      .option("http_port", "8443")
      .option("database", "default")
      .option("table", "events_copy")
      .option("user", "default")
      .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
      .option("ssl", "true")
      .option("order_by", "id")  // مطلوب: حدِّد ORDER BY عند إنشاء جدول جديد
      .option("settings.allow_nullable_key", "1")  // مطلوب في ClickHouse Cloud إذا كان ORDER BY يتضمن أعمدة Nullable
      .mode("append")
      .save()
    ```
  </Tab>
</Tabs>

<Note>
  يفترض هذا المثال وجود نطاقات الأسرار مُعدّة مسبقًا في Databricks. للحصول على إرشادات الإعداد، راجع وثائق إدارة الأسرار في Databricks: [Secret management documentation](https://docs.databricks.com/aws/en/security/secrets/).
</Note>

<div id="considerations">
  ## اعتبارات خاصة بـ Databricks
</div>

<div id="access-mode">
  ### متطلبات وضع الوصول
</div>

يتطلب ClickHouse Spark Connector وضع الوصول **Dedicated** (المعروف سابقًا باسم Single User). ولا يدعم وضع الوصول **Standard** (المعروف سابقًا باسم Shared) عند تمكين Unity Catalog، لأن Databricks يحظر موصلات DataSource V2 الخارجية في هذا الإعداد.

| وضع الوصول              | Unity Catalog | مدعوم |
| ----------------------- | ------------- | ----- |
| Dedicated (Single User) | مُمكّن        | ✅ نعم |
| Dedicated (Single User) | معطّل         | ✅ نعم |
| Standard (Shared)       | مُمكّن        | ❌ لا  |
| Standard (Shared)       | معطّل         | ✅ نعم |

<div id="secret-management">
  ### إدارة الأسرار
</div>

استخدم نطاقات الأسرار في Databricks لتخزين بيانات اعتماد ClickHouse بشكل آمن:

```python theme={null}
# Access secrets
password = dbutils.secrets.get(scope="clickhouse", key="password")
```

للحصول على تعليمات الإعداد، راجع [وثائق Databricks الخاصة بإدارة الأسرار](https://docs.databricks.com/aws/en/security/secrets/).

<div id="clickhouse-cloud">
  ### الاتصال بـ ClickHouse Cloud
</div>

عند الاتصال بـ ClickHouse Cloud من Databricks:

1. استخدم **بروتوكول HTTPS** (`protocol: https`, `http_port: 8443`)
2. فعِّل **SSL** (`ssl: true`)

<div id="examples">
  ## أمثلة
</div>

<div id="workflow-example">
  ### مثال كامل لسير العمل
</div>

<Tabs>
  <Tab title="بايثون">
    ```python theme={null}
    from pyspark.sql import SparkSession
    from pyspark.sql.functions import col

    # تهيئة Spark باستخدام موصل ClickHouse
    spark = SparkSession.builder \
        .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0") \
        .getOrCreate()

    # القراءة من ClickHouse
    df = spark.read \
        .format("clickhouse") \
        .option("host", "your-host.clickhouse.cloud") \
        .option("protocol", "https") \
        .option("http_port", "8443") \
        .option("database", "default") \
        .option("table", "source_table") \
        .option("user", "default") \
        .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
        .option("ssl", "true") \
        .load()

    # تحويل البيانات
    transformed_df = df.filter(col("status") == "active")

    # الكتابة إلى ClickHouse
    transformed_df.write \
        .format("clickhouse") \
        .option("host", "your-host.clickhouse.cloud") \
        .option("protocol", "https") \
        .option("http_port", "8443") \
        .option("database", "default") \
        .option("table", "target_table") \
        .option("user", "default") \
        .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
        .option("ssl", "true") \
        .option("order_by", "id") \
        .mode("append") \
        .save()
    ```
  </Tab>

  <Tab title="Scala">
    ```scala theme={null}
    import org.apache.spark.sql.SparkSession
    import org.apache.spark.sql.functions.col

    // تهيئة Spark باستخدام موصل ClickHouse
    val spark = SparkSession.builder
      .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0")
      .getOrCreate()

    // القراءة من ClickHouse
    val df = spark.read
      .format("clickhouse")
      .option("host", "your-host.clickhouse.cloud")
      .option("protocol", "https")
      .option("http_port", "8443")
      .option("database", "default")
      .option("table", "source_table")
      .option("user", "default")
      .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
      .option("ssl", "true")
      .load()

    // تحويل البيانات
    val transformedDF = df.filter(col("status") === "active")

    // الكتابة إلى ClickHouse
    transformedDF.write
      .format("clickhouse")
      .option("host", "your-host.clickhouse.cloud")
      .option("protocol", "https")
      .option("http_port", "8443")
      .option("database", "default")
      .option("table", "target_table")
      .option("user", "default")
      .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
      .option("ssl", "true")
      .option("order_by", "id")
      .mode("append")
      .save()
    ```
  </Tab>
</Tabs>

<div id="related">
  ## وثائق ذات صلة
</div>

* [دليل Spark Native Connector](/ar/integrations/connectors/data-ingestion/apache-spark/spark-native-connector) - الوثائق الكاملة للموصل
* [وثائق واجهة برمجة تطبيقات TableProvider](/ar/integrations/connectors/data-ingestion/apache-spark/spark-native-connector#using-the-tableprovider-api) - تفاصيل الوصول المستند إلى التنسيق
* [وثائق واجهة برمجة تطبيقات Catalog](/ar/integrations/connectors/data-ingestion/apache-spark/spark-native-connector#register-the-catalog-required) - تفاصيل الوصول القائم على الكتالوج