ربط dlt بـ ClickHouse

dlt هي مكتبة مفتوحة المصدر يمكنك إضافتها إلى برامجك النصية بلغة بايثون لتحميل البيانات من مصادر بيانات متنوعة، وغالبًا غير منظَّمة، إلى مجموعات بيانات منظَّمة ومحدَّثة باستمرار.

pip install "dlt[clickhouse]"

dlt init chess clickhouse

pip install -r requirements.txt

CREATE DATABASE IF NOT EXISTS dlt;
CREATE USER dlt IDENTIFIED WITH sha256_password BY 'Dlt*12345789234567';
GRANT CREATE, ALTER, SELECT, DELETE, DROP, TRUNCATE, OPTIMIZE, SHOW, INSERT, dictGet ON dlt.* TO dlt;
GRANT SELECT ON INFORMATION_SCHEMA.COLUMNS TO dlt;
GRANT CREATE TEMPORARY TABLE, S3 ON *.* TO dlt;

[destination.clickhouse.credentials]
database = "dlt"                         # اسم قاعدة البيانات التي أنشأتها
username = "dlt"                         # اسم مستخدم ClickHouse، وعادةً ما يكون الاسم الافتراضي هو "default"
password = "Dlt*12345789234567"          # كلمة مرور ClickHouse إن وجدت
host = "localhost"                       # مضيف خادم ClickHouse
port = 9000                              # منفذ HTTP في ClickHouse، والقيمة الافتراضية هي 9000
http_port = 8443                         # منفذ HTTP للاتصال بواجهة HTTP الخاصة بخادم ClickHouse. القيمة الافتراضية هي 8443.
secure = 1                               # اضبطه على 1 عند استخدام HTTPS، وإلا فاضبطه على 0.

[destination.clickhouse]
dataset_table_separator = "___"          # الفاصل المستخدم في أسماء جداول dataset المشتقة من dataset.

# أبقه في أعلى ملف toml لديك، قبل بدء أي قسم.
destination.clickhouse.credentials="clickhouse://dlt:Dlt*12345789234567@localhost:9000/dlt?secure=1"

جميع آليات الكتابة مدعومة.

تحدّد آليات الكتابة في مكتبة dlt كيفية كتابة البيانات إلى الوجهة. وهناك ثلاثة أنواع من آليات الكتابة:

الاستبدال: تستبدل هذه الآلية البيانات الموجودة في الوجهة بالبيانات القادمة من المورد. فهي تحذف جميع الأصناف والكائنات، ثم تعيد إنشاء المخطط قبل تحميل البيانات. يمكنك معرفة المزيد عنها هنا.

الدمج: تدمج آلية الكتابة هذه البيانات القادمة من المورد مع البيانات الموجودة في الوجهة. وبالنسبة إلى آلية merge، ستحتاج إلى تحديد primary_key للمورد. يمكنك معرفة المزيد عنها هنا.

الإلحاق: هذه هي الآلية الافتراضية. ستُلحق البيانات بالبيانات الموجودة بالفعل في الوجهة، مع تجاهل الحقل primary_key.

تُحمَّل البيانات إلى ClickHouse باستخدام الطريقة الأكثر كفاءةً وفقًا لمصدر البيانات:

• بالنسبة إلى الملفات المحلية، تُستخدم مكتبة clickhouse-connect لتحميل الملفات مباشرةً إلى جداول ClickHouse باستخدام الأمر INSERT.
• بالنسبة إلى الملفات الموجودة في التخزين البعيد مثل S3 وGoogle Cloud Storage وAzure Blob Storage، تُستخدم وظائف الجداول في ClickHouse مثل s3 وgcs وazureBlobStorage لقراءة الملفات وإدخال البيانات إلى الجداول.

لا يدعم ClickHouse وجود مجموعات بيانات متعددة داخل قاعدة بيانات واحدة، بينما يعتمد dlt على مجموعات البيانات لعدة أسباب. ولكي يعمل ClickHouse مع dlt، ستُضاف بادئة اسم مجموعة البيانات إلى أسماء الجداول التي ينشئها dlt في قاعدة بيانات ClickHouse لديك، مع فصلها باستخدام dataset_table_separator القابل للتهيئة. بالإضافة إلى ذلك، سيُنشأ جدول حارس خاص لا يحتوي على أي بيانات، ما يتيح لـ dlt التعرّف على مجموعات البيانات الافتراضية الموجودة بالفعل في وجهة ClickHouse.

• يُعدّ jsonl التنسيق المفضّل لكلٍّ من التحميل المباشر والتخزين المرحلي.
• يدعم parquet كلاً من التحميل المباشر والتخزين المرحلي.

تتضمن وجهة clickhouse بعض الاختلافات الخاصة عن وجهات sql الافتراضية:

1. يوفّر ClickHouse نوع البيانات التجريبي object، لكننا وجدناه غير مستقر إلى حدٍّ ما، لذلك ستقوم وجهة dlt لـ clickhouse بتحميل نوع البيانات المعقّد في عمود نصي. إذا كنت بحاجة إلى هذه الميزة، فتواصل مع مجتمعنا على Slack، وسننظر في إضافتها.
2. لا يدعم ClickHouse نوع البيانات time. لذلك ستُحمَّل قيم الوقت في عمود text.
3. لا يدعم ClickHouse نوع البيانات binary. وبدلاً من ذلك، ستُحمَّل البيانات الثنائية في عمود text. عند التحميل من jsonl، ستكون البيانات الثنائية سلسلة base64، وعند التحميل من parquet، سيُحوَّل الكائن binary إلى text.
4. يدعم ClickHouse إضافة أعمدة غير قابلة لأن تكون null إلى جدول يحتوي بالفعل على بيانات.
5. قد ينتج ClickHouse أخطاء تقريب في ظروف معيّنة عند استخدام نوع البيانات float أو double. إذا لم يكن بإمكانك تحمّل أخطاء التقريب، فتأكد من استخدام نوع البيانات decimal. على سبيل المثال، فإن تحميل القيمة 12.7001 إلى عمود double مع ضبط تنسيق ملف المُحمِّل على jsonl سيؤدي بشكل متوقّع إلى خطأ تقريب.

يدعم ClickHouse تلميحات الأعمدة التالية:

• primary_key - يحدّد هذا العمود كجزء من المفتاح الأساسي. ويمكن أن تحمل عدة أعمدة هذا التلميح لإنشاء مفتاح أساسي مركب.

بشكل افتراضي، تُنشأ الجداول في ClickHouse باستخدام محرك الجدول ReplicatedMergeTree. يمكنك تحديد محرك جدول بديل باستخدام table_engine_type مع المهايئ ClickHouse:

from dlt.destinations.adapters import clickhouse_adapter

@dlt.resource()
def my_resource():
  ...

clickhouse_adapter(my_resource, table_engine_type="merge_tree")

القيم المدعومة هي:

• merge_tree - يُنشئ جداول باستخدام المحرك MergeTree
• replicated_merge_tree (الافتراضي) - يُنشئ جداول باستخدام المحرك ReplicatedMergeTree

يدعم ClickHouse كلاً من Amazon S3 وGoogle Cloud Storage وAzure Blob Storage كوجهات للتخزين المرحلي للملفات.

سيقوم dlt برفع ملفات Parquet أو jsonl إلى موقع التخزين المرحلي، ثم استخدام وظائف الجدول في ClickHouse لتحميل البيانات مباشرةً من الملفات المخزنة مرحليًا.

يُرجى الرجوع إلى وثائق filesystem لمعرفة كيفية تهيئة بيانات الاعتماد لوجهات التخزين المرحلي:

• Amazon S3
• Google Cloud Storage
• Azure Blob Storage

لتشغيل مسار بيانات مع تمكين التخزين المرحلي:

pipeline = dlt.pipeline(
  pipeline_name='chess_pipeline',
  destination='clickhouse',
  staging='filesystem',  # add this to activate staging
  dataset_name='chess_data'
)

تدعم dlt استخدام Google Cloud Storage ‏(GCS) كتخزين مرحلي عند تحميل البيانات إلى ClickHouse. ويُدار ذلك تلقائيًا بواسطة دالة الجدول GCS في ClickHouse، والتي تستخدمها dlt في الخلفية.

لا تدعم دالة الجدول GCS في ClickHouse سوى المصادقة باستخدام مفاتيح Hash-based Message Authentication Code ‏(HMAC). ولتمكين ذلك، يوفّر GCS وضع توافق مع S3 يحاكي واجهة برمجة تطبيقات Amazon S3. ويستفيد ClickHouse من هذا لإتاحة الوصول إلى حاويات GCS عبر تكامله مع S3.

لإعداد التخزين المرحلي في GCS باستخدام مصادقة HMAC في dlt:

1. أنشئ مفاتيح HMAC لحساب الخدمة الخاص بك في GCS باتباع دليل Google Cloud.

2. اضبط مفاتيح HMAC، بالإضافة إلى client_email وproject_id وprivate_key الخاصة بحساب الخدمة، في إعدادات وجهة ClickHouse ضمن مشروع dlt في config.toml:

[destination.filesystem]
bucket_url = "gs://dlt-ci"

[destination.filesystem.credentials]
project_id = "a-cool-project"
client_email = "my-service-account@a-cool-project.iam.gserviceaccount.com"
private_key = "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkaslkdjflasjnkdcopauihj...wEiEx7y+mx\nNffxQBqVVej2n/D93xY99pM=\n-----END PRIVATE KEY-----\n"

[destination.clickhouse.credentials]
database = "dlt"
username = "dlt"
password = "Dlt*12345789234567"
host = "localhost"
port = 9440
secure = 1
gcp_access_key_id = "JFJ$$*f2058024835jFffsadf"
gcp_secret_access_key = "DFJdwslf2hf57)%$02jaflsedjfasoi"

ملاحظة: بالإضافة إلى مفاتيح HMAC bashgcp_access_key_id و gcp_secret_access_key)، تحتاج الآن أيضًا إلى تقديم client_email و project_id و private_key الخاصة بحساب الخدمة ضمن [destination.filesystem.credentials]. ويرجع ذلك إلى أن دعم التخزين المرحلي لـ GCS مُنفَّذ حاليًا كحل بديل مؤقت، ولا يزال غير مُحسَّن.

سيمرّر dlt بيانات الاعتماد هذه إلى ClickHouse، الذي سيتولى المصادقة والوصول إلى GCS.

يجري العمل حاليًا وبشكل نشط على تبسيط إعداد التخزين المرحلي لـ GCS وتحسينه لوجهة ClickHouse dlt مستقبلًا. ويجري تتبّع دعم التخزين المرحلي الكامل لـ GCS في مشكلات GitHub التالية:

• جعل وجهة filesystem تعمل مع gcs في وضع التوافق مع s3
• دعم التخزين المرحلي لـ Google Cloud Storage

يكون التكامل مع dbt مدعومًا عمومًا عبر dbt-clickhouse.

تدعم هذه الوجهة بالكامل مزامنة حالة dlt.