dbt OSS وv2 والمنصة (Beta)

حالة ClickHouse adapter في dbt OSS وdbt v2 ومنصة dbt

تجري إعادة بناء dbt على محرك جديد، وClickHouse جزء من ذلك منذ البداية. أصبح ClickHouse الآن يعمل مع محرك dbt الجديد المبني على Rust، في كل من dbt OSS وdbt v2، ولأول مرة يمكنك الاتصال بـ ClickHouse من منصة dbt. ولا يتغير مشروعك في شيء: فالنماذج والاختبارات وملفات التعريف نفسها التي تعمل اليوم على dbt Core 1.x تعمل على المحرك الجديد؛ الاختلاف الوحيد هو الملف التنفيذي.

ClickHouse هو أول adapter مجتمعي على dbt OSS وdbt v2 ومنصة dbt. وتُطلق dbt محولاتها الخاصة بالتوازي معنا، ونحن أول جهة من خارج dbt Labs. أما adapter بايثون الخاص بـ dbt Core 1.x، أي dbt-clickhouse، فلن يُوقَف: سنبقيه محدثًا مع إصدارات dbt 1.x ونصون كلا المحولين بالتوازي.

غير جاهز للإنتاج. إن adapter ClickHouse الخاص بـ dbt OSS وdbt v2، وكذلك الاتصال بمنصة dbt، ليست متاحة بعد بشكل عام (GA). استخدمها فقط في مشاريع التطوير أو staging.

توثيق dbt Core 1.x ينطبق أيضًا على dbt OSS وdbt v2. يعمل adapter بالطريقة نفسها على كلا المحركين: فملفات التعريف وإعدادات النماذج والتجسيدات والماكرو الموصوفة في صفحات dbt الأخرى تعمل دون تغيير على dbt OSS وdbt v2 ومنصة dbt. أما الاستثناءات فموثّقة في جدول تكافؤ v1 مقابل v2 أدناه.

dbt OSS هو البناء مفتوح المصدر (Apache 2.0) لمحرك v2. راجع المصطلحات والتوافر لمعرفة علاقته بـ dbt v2 ومنصة dbt.

تُتابع الحالة المباشرة في ClickHouse/dbt-clickhouse#660 (تكافؤ v2 مع v1، بمشكلة فرعية واحدة لكل مجال) وClickHouse/dbt-clickhouse#555 (dbt v2).

​

جرّب ClickHouse في منصة dbt

إذا كنت مهتمًا باختبار الإصدار التجريبي الخاص (Beta)، فسجّل عبر نموذج الإصدار التجريبي الخاص الخاص بـ dbt Labs. النموذج تابع لـ dbt Labs، لذا فإن المعلومات التي ترسلها تذهب إلى dbt Labs وليس إلى ClickHouse. وبعد تفعيل الوصول، اتبع Connect ClickHouse في وثائق dbt لإعداد الاتصال.

​

المصطلحات والتوافر

يتوفر dbt في عدة صور، ويمكن للـ adapter نفسه أن يعمل في أكثر من صورة منها. يوضح هذا الجدول كل تسمية والمستوى الحالي لدعم ClickHouse.

المصطلح	ما هو	حالة الدعم في ClickHouse وكيفية الحصول عليه
dbt Core 1.x	محرك dbt المبني على بايثون، open source (Apache 2.0). الـ adapter الخاص بنا هو dbt-clickhouse، ويجري صيانته ضمن منظمة ClickHouse على GitHub ويُثبَّت إلى جانب dbt-core.	GA، تجري صيانته. ولا يزال يتلقى إصدارات in parallel مع dbt v2.
dbt OSS	إعادة كتابة كاملة لمحرك dbt بلغة Rust، open source (Apache 2.0). يتضمن هذا الإصدار الجديد جميع مزايا الإصدار v1 إضافةً إلى عدة تحسينات في الأداء.	Beta. اتبع dbt v2 upgrade guide وصفحة إعداد ClickHouse للإصدار v2 في وثائق dbt. يأتي adapter الخاص بـ ClickHouse مدمجًا داخل binary الخاص بـ dbt، ولا حاجة لتثبيت package منفصل.
dbt v2	dbt OSS مع مزايا إضافية من dbt Labs: فهم SQL، والتحليل الساكن، وLSP، وextension لـ VS Code، والوعي بالـ column. مغلق المصدر، ومرخَّص بموجب dbt Product Licensing Agreement.	Beta. يعمل الـ adapter مع binary الخاص بالإصدار v2، لكن مزايا SQL الجديدة غير متوفرة لـ ClickHouse بعد.
dbt platform	dbt المُستضاف، وكان يُعرف سابقًا بـ dbt Cloud: Studio IDE، والـ jobs المجدولة، والبيئات، وCatalog، وSemantic Layer. تعمل المنصة بالإصدار v2 فقط، لذا فإن استخدام ClickHouse فيها يعني adapter الإصدار v2.	Private Beta. راجع كيفية طلب access. الإعداد: Connect ClickHouse في وثائق dbt.

​

حالة Beta

نقيس أداء adapter الخاص بـ dbt v2 مقابل مجموعة اختبارات التكامل الخاصة بـ dbt Core 1.x في dbt-clickhouse. تعني Beta أن سير عمل dbt الأساسي ومجموعة ميزات ClickHouse Cloud تعمل ضمن حدود موثّقة؛ أما التكافؤ الكامل مع v1 ودعم العناقيد المُدارة ذاتيًا فسيأتيان لاحقًا.

حتى اليوم، يجتاز الـ adapter أكثر من 81% من مجموعة اختبارات v1 الكاملة و92% من الاختبارات التي تنطبق على ClickHouse Cloud. وجميع أنواع materialization في حالة تكافؤ (view، table، incremental، materialized_view، dictionary، snapshot، seed، ephemeral)، مع المجموعة الكاملة من إعدادات الجداول، وعقود الـ model، واختبارات البيانات واختبارات الوحدة، والتخزين الدائم للوثائق، وclickhouse_s3source() وإعدادات الاتصال في dbt Core 1.x. وتتعلق حالات الفشل المتبقية بأعمال العناقيد المُدارة ذاتيًا المذكورة أدناه وبعدد قليل من الاختلافات على جانب الـ engine. راجع التكافؤ بين v1 وv2 للحصول على صورة تفصيلية ميزة بميزة.

الخطوات التالية: دعم DDL بصيغة ON CLUSTER وDistributed materializations للعناقيد المُدارة ذاتيًا، وgrants، وdbt clone، وdbt source freshness انطلاقًا من metadata الجداول، وإصلاح الأخطاء المتبقية، واجتياز مجموعة اختبارات v1 الكاملة لضمان التكافؤ التام. ويُتابع تقدم هذه الأعمال كلها في ClickHouse/dbt-clickhouse#660، مع مسألة فرعية لكل مجال.

وإصدار GA مدرج في خطة الطريق وسيصدر قريبًا، وسنحدّث الوثائق بمجرد أن يكون جاهزًا.

​

خارج نطاق Beta

بالإضافة إلى فجوات التكافؤ مع الإصدار v1 المذكورة أدناه، توجد بعض الميزات الحصرية للإصدار v2 تقع خارج النطاق الحالي، لكنها ستتوفر قريبًا:

• Semantic Layer / MetricFlow. لم يُضَف دعم ClickHouse بعد. يمكن متابعة ذلك في dbt-labs/metricflow#2124.
• ذكاء ClickHouse SQL في dbt v2 (validation مُدرك للـ dialect، والتحليل الثابت، وLSP، وإدراك الـ column في امتداد VS Code). يعمل الـ adapter حاليًا مع الـ binary الخاص بـ dbt v2، لكنه لا يتضمّن هذه الميزات بعد. وحتى ذلك الحين، يُفرَض ضبط التحليل الثابت على off لمشاريع ClickHouse، ولا يكتب الـ engine أي تتبّع للأصول (lineage) على مستوى الـ column. يمكن متابعة ذلك في #736.
• طرق مصادقة إضافية بخلاف username وpassword في منصة dbt.

​

التكافؤ بين v1 وv2

تقارن الجداول أدناه الميزات المتاحة في dbt-clickhouse (v1) بحالتها في محوّل dbt v2. جميع الميزات المدرجة مدعومة في v1 ما لم تُشر الملاحظات إلى خلاف ذلك، أما عمود الحالة فيخص dbt v2 وينطبق كذلك على dbt OSS. ويمكن متابعة تطوّر كل عنصر قيد الانتظار في ClickHouse/dbt-clickhouse#660.

مدعوم يعمل حاليًا · جزئي يعمل ضمن قيود · ليس بعد قيد التنفيذ.

​

التجسيدات

الميزة	وظيفتها	dbt v2	ملاحظات
view	عرض dbt قياسي.	مدعوم
table	إعادة بناء كاملة مع خيارات المحرك و DDL.	مدعوم
incremental	إلحاق صفوف جديدة أو دمجها.	مدعوم
materialized_view	عرض مجسّد في ClickHouse يُحوّل البيانات وقت الإدراج.	مدعوم
dictionary	قاموس ClickHouse لعمليات البحث بالمفاتيح وعمليات الربط.	مدعوم
snapshot	أبعاد بطيئة التغيّر من النوع 2.	مدعوم
seed	تحميل ملفات CSV كجداول.	مدعوم	تُستنتج أنواع الأعمدة الرقمية على أنها Int64/Float64 بدلاً من Int32/Float32؛ استخدم column_types لتحديدها صراحةً.
ephemeral	تعبير جدول شائع مضمّن، دون إنشاء أي كائن.	مدعوم
distributed_table، distributed_incremental	جداول مُقسّمة إلى أجزاء خلف محرك Distributed.	ليس بعد

​

تهيئة الـ model

الميزة	وظيفتها	dbt v2	ملاحظات
المحرك، ORDER BY، PARTITION BY، PRIMARY KEY	عناصر التحكم الأساسية في DDL الخاص بـ MergeTree.	مدعوم
TTL	انتهاء صلاحية الصفوف والأعمدة.	مدعوم
إعدادات الجدول والاستعلام	SETTINGS خاصة بكل model في DDL وفي عملية الإدخال.	مدعوم
الإسقاطات والفهارس وsql_header	البنى الثانوية وشيفرة SQL التمهيدية.	مدعوم
عقود الـ models والقيود	أنواع الأعمدة والقيود المطبَّقة وقت البناء.	مدعوم
تطور المخطط في الـ models التزايدية	on_schema_change يضيف الأعمدة أو يزامنها.	مدعوم
codec وttl على مستوى الـ column	الضغط وانتهاء الصلاحية لكل column على حدة.	مدعوم

​

الاختبار والتوثيق

الميزة	وظيفتها	dbt v2	ملاحظات
اختبارات البيانات	اختبارات عامة ومفردة.	مدعومة
unit tests	اختبار منطق الـ model مقابل مدخلات ثابتة.	مدعومة
التخزين الدائم للتوثيق	الأوصاف تُكتب على هيئة comments في ClickHouse.	جزئي	تفشل الأوصاف التي تحتوي على ;.
توليد الـ catalog والتوثيق	metadata الأعمدة الخاصة بموقع التوثيق.	مدعوم
التتبع على مستوى الأعمدة (column-level)	تتبّع الأعمدة عبر الـ DAG.	جزئي	ميزة جديدة في v2 عبر مصرّف SQL وغير متاحة في v1. لا يُعرض التتبع في منصة dbt إلا عند تعطيل quoting المعرّفات في dbt_project.yml؛ أما التتبع على جانب الـ engine فيتطلب ClickHouse SQL dialect.

​

العنقود وClickHouse Cloud

الميزة	وظيفتها	dbt v2	ملاحظات
ClickHouse Cloud	الإعداد Beta المُوصى به.	مدعوم
الاتساق بين النسخ المتعددة	select_sequential_consistency وإعدادات القراءة بعد الكتابة ذات الصلة.	مدعوم
ON CLUSTER ومحركات Replicated	توزيع عبارات DDL على العناقيد المُدارة ذاتيًا.	ليس بعد	العناقيد متعددة العُقد في ClickHouse Cloud مدعومة، أما الإعدادات الأخرى التي تتطلب ON CLUSTER لنشر عبارات DDL فهي غير مدعومة بعد. وفي حالات النشر المُدار ذاتيًا، اقتصر في الاختبار على العناقيد أحادية العقدة.
EXCHANGE TABLES	تبديل atomic عند إعادة البناء.	مدعوم
إعدادات الاتصال المخصصة	custom_settings على مستوى ملف التعريف.	مدعوم
إصدار خادم ClickHouse	الحد الأدنى لإصدار الخادم.	مدعوم	25.3+ على كلا المحركين. تتطلب قراءة أعمدة UUID على v2 الإصدار 26.7+ (الخوادم الأقدم لا تستطيع تحويل UUID إلى Arrow).

​

وحدات الماكرو والعمليات

الميزة	وظيفتها	dbt v2	ملاحظات
ماكرو S3 table function	clickhouse_s3source() يقرأ من S3 مباشرةً داخل model.	مدعوم
وحدات ماكرو عابرة لقواعد البيانات	أدوات مساعدة مثل تلك الموجودة في dbt-utils.	مدعوم
الأذونات	عبارات GRANT من إعداد model.	ليس بعد
dbt clone	CLONE AS بدون نسخ (zero-copy) بين البيئات.	ليس بعد
معرّف الاستعلام في نتائج التشغيل	query_id ضمن adapter_response للربط مع system.query_log.	ليس بعد
query-comment	تهيئة تعليق الاستعلام.	ليس بعد	لا يُؤخذ query-comment: null بعين الاعتبار بعد.
تكامل الكتالوج (Iceberg)	التجسيد في external catalogs.	ليس بعد	غير متوفر في v1 أيضًا؛ وهناك حلول بديلة موثّقة.

​

الاتصال والمصادقة

الميزة	وظيفتها	dbt v2	ملاحظات
Protocol	كيفية اتصال dbt بـ ClickHouse.	مدعوم	ADBC (‏Arrow عبر HTTP) في الإصدار v2؛ وHTTP وnative في الإصدار v1.
اسم المستخدم وكلمة المرور، TLS	المصادقة القياسية.	مدعوم
شهادات العميل mTLS	client_cert، client_cert_key، verify.	ليس بعد	يتطلب عملاً على مستوى الـ driver؛ تُقبل المفاتيح لكن يتم تجاهلها.
خيارات HTTP client	connect_timeout، send_receive_timeout، sync_request_timeout، compress_block_size، server_host_name.	ليس بعد	تُقبل لكن يتم تجاهلها؛ وserver_host_name غير متاح.