دمج ClickHouse مع Databricks

متوافق مع ClickHouse

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

اختيار واجهة برمجة تطبيقات لـ Databricks

افتراضيًا، يستخدم 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"

التثبيت في Databricks

الخيار 1: رفع JAR عبر واجهة مستخدم Databricks

ابنِ ملف JAR الخاص ببيئة التشغيل أو نزّله:

clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar

ارفع ملف JAR إلى مساحة العمل في Databricks:
- انتقل إلى Workspace → ثم إلى المجلد المطلوب
- انقر على Upload → ثم اختر ملف JAR
- سيُحفَظ ملف JAR في مساحة العمل الخاصة بك
ثبّت المكتبة على العنقود:
- انتقل إلى Compute → ثم اختر العنقود الخاص بك
- انقر على علامة التبويب Libraries
- انقر على Install New
- اختر DBFS أو Workspace → ثم انتقل إلى ملف JAR الذي رفعته
- انقر على Install

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

الخيار 2: التثبيت باستخدام Databricks CLI

# 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

الخيار 3: إحداثيات Maven (موصى به)

انتقل إلى مساحة العمل الخاصة بـ Databricks:
- انتقل إلى Compute → اختر العنقود الخاص بك
- انقر على علامة التبويب Libraries
- انقر على Install New
- اختر علامة التبويب Maven
أضف إحداثيات Maven:

com.clickhouse.spark:clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}:{{ stable_version }}

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

استخدام TableProvider API

عندما يكون Unity Catalog مفعّلًا (افتراضيًا)، يجب عليك استخدام TableProvider API (الوصول المستند إلى التنسيق)، لأن Unity Catalog يمنع تسجيل الكتالوج في Spark. وإذا كنت قد عطّلت Unity Catalog باستخدام عنقود بوضع الوصول "No isolation shared"، فيمكنك استخدام Catalog API بدلًا من ذلك.

قراءة البيانات

# قراءة البيانات من 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()

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()

كتابة البيانات

# الكتابة إلى 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()

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()

اعتبارات خاصة بـ Databricks

متطلبات وضع الوصول

يتطلب 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)	معطّل	✅ نعم

إدارة الأسرار

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

# Access secrets
password = dbutils.secrets.get(scope="clickhouse", key="password")

للحصول على تعليمات الإعداد، راجع وثائق Databricks الخاصة بإدارة الأسرار.

الاتصال بـ ClickHouse Cloud

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

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

أمثلة

مثال كامل لسير العمل

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()

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()

دليل Spark Native Connector - الوثائق الكاملة للموصل
وثائق واجهة برمجة تطبيقات TableProvider - تفاصيل الوصول القائم على التنسيق
وثائق واجهة برمجة تطبيقات Catalog - تفاصيل الوصول القائم على الكتالوج