تكامل dbt مع ClickHouse

يمكنك تحويل بياناتك ونمذجتها في ClickHouse باستخدام dbt

​

مُهايئ dbt-clickhouse

يُمكّن dbt (أداة بناء البيانات) مهندسي التحليلات من تحويل البيانات في مستودعاتهم بمجرد كتابة عبارات SELECT. ويتولى dbt تحويل عبارات SELECT هذه إلى كائنات داخل قاعدة البيانات، مثل الجداول والعروض، وبذلك ينفّذ مرحلة التحويل (T) من Extract Load and Transform (ELT). يمكنك إنشاء نموذج يحدّده عبارة SELECT.

داخل dbt، يمكن لهذه النماذج أن تشير إلى بعضها بعضًا وأن تُرتَّب في طبقات، مما يتيح بناء مفاهيم ذات مستوى أعلى. ويُولِّد تلقائيًا شيفرة SQL النمطية المطلوبة لربط النماذج. إضافة إلى ذلك، يحدّد dbt التبعيات بين النماذج ويضمن إنشاءها بالترتيب المناسب باستخدام رسم بياني موجّه لا دوري (DAG).

يتوافق dbt مع ClickHouse عبر مُهايئ مدعوم من ClickHouse.

dbt OSS وdbt v2 ومنصة dbt. يعمل ClickHouse الآن مع dbt OSS (Beta) وdbt v2 (Beta) ومنصة dbt (Private Beta؛ راجع كيفية طلب الوصول). وهذا التكامل ليس جاهزًا للاستخدام في الإنتاج بعد. راجع صفحة dbt OSS وdbt v2 ومنصة dbt للاطلاع على الحالة الراهنة والقيود المعروفة. كما ينطبق ما تبقّى من هذه الوثائق عليها جميعًا، وفقًا للقيود المذكورة في جدول التكافؤ في تلك الصفحة.

​

صفحات ذات صلة

الصفحة	الوصف
الميزات والإعدادات	وصف للميزات والإعدادات العامة المتاحة
التجسيدات	التجسيدات المتاحة وإعداداتها
العروض المُجسَّدة	توثيق خاص بتجسيد materialized_view
الأدلة	أدلة لاستخدام dbt مع ClickHouse

​

الميزات المدعومة

قائمة الميزات المدعومة:

• التجسيد للجدول
• التجسيد للعرض
• التجسيد تزايدية
• التجسيد تزايدية من نوع Microbatch
• التجسيدات من نوع عرض مُجسَّد (تستخدم صيغة TO الخاصة بـ MATERIALIZED VIEW، وهي تجريبية)
• Seeds
• Sources
• إنشاء الوثائق
• الاختبارات
• Snapshots
• معظم وحدات الماكرو في dbt-utils (وهي الآن مضمنة في dbt-core)
• التجسيد مؤقتة
• التجسيد للجدول الموزع (تجريبية)
• التجسيد تزايدية موزعة (تجريبية)
• تجسيد Dictionary (تجريبية)
• العقود
• إعدادات الأعمدة الخاصة بـ ClickHouse (Codec، TTL…)
• إعدادات الجداول الخاصة بـ ClickHouse (indexes، projections…)

الميزات حتى dbt-core 1.12 مدعومة، بما في ذلك الخيار --sample، مع إصلاح جميع تحذيرات الإهمال للإصدارات المستقبلية. تكاملات Catalog (مثل Iceberg) التي قُدمت في dbt 1.10 ليست مدعومة أصلًا بعد في المهايئ، ولكن تتوفر حلول بديلة. راجع قسم دعم Catalog للتفاصيل.

​

مفاهيم dbt وأنواع التجسيد المدعومة

يقدّم dbt مفهوم النموذج. ويُعرَّف النموذج على أنه عبارة SQL قد تجمع بين العديد من الجداول. ويمكن “تجسيد” النموذج بعدة طرق. ويمثل التجسيد استراتيجية بناء لاستعلام select الخاص بالنموذج. أما الشيفرة التي تقف وراء التجسيد فهي SQL قالبية تُغلّف استعلام SELECT الخاص بك داخل عبارة بهدف إنشاء relation جديدة أو تحديث relation موجودة.

يوفر dbt خمسة أنواع من التجسيد، وكلها مدعومة بواسطة dbt-clickhouse:

• عرض (الافتراضي): يُبنى النموذج كـ عرض في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ عرض.
• جدول: يُبنى النموذج كـ جدول في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ جدول.
• ephemeral: لا يُبنى النموذج مباشرةً في قاعدة البيانات، بل يُدرج داخل النماذج التابعة على شكل CTEs ‏(Common Table Expressions).
• incremental: يُجسَّد النموذج في البداية كـ جدول، وفي عمليات التشغيل اللاحقة يُدرج dbt rows جديدة ويحدّث rows المتغيرة في جدول.
• عرض مُجسَّد: يُبنى النموذج كـ عرض مُجسَّد في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ عرض مُجسَّد.

وتحدد الصياغة الإضافية وclausees المختلفة كيفية تحديث هذه النماذج إذا تغيّرت بياناتها الأساسية. ويوصي dbt عمومًا بالبدء بتجسيد عرض إلى أن يصبح الأداء مصدر قلق. ويوفر تجسيد جدول تحسينًا في الأداء وقت الاستعلام عبر حفظ نتائج استعلام النموذج في جدول، مقابل زيادة في التخزين. ويطوّر نهج incremental هذه الفكرة أكثر، بحيث يمكن التقاط التحديثات اللاحقة على البيانات الأساسية في target جدول.

فيما يلي الميزات التجريبية في dbt-clickhouse:

النوع	هل هو مدعوم؟	التفاصيل
عرض مُجسَّد تجسيد	نعم. الإنشاء باستخدام explicit target ما يزال في Beta	ينشئ عرض مُجسَّد.
Distributed جدول تجسيد	نعم، تجريبي	ينشئ distributed جدول.
Distributed incremental تجسيد	نعم، تجريبي	نموذج incremental يستند إلى الفكرة نفسها الخاصة بـ distributed جدول. لاحظ أن بعض الاستراتيجيات غير مدعومة؛ راجع قسم الوثائق الخاص بها لمزيد من المعلومات.
Dictionary تجسيد	نعم، تجريبي	ينشئ dictionary.

​

إعداد dbt ومُهايئ ClickHouse

إذا كنت تفضّل البدء من مشروع جاهز للعمل، فإن Jaffle Shop for ClickHouse، وهو fork لمشروع dbt النموذجي، يأتي مزوّدًا بملفات تعريف لـ ClickHouse محلي ولـ ClickHouse Cloud، وبيانات نموذجية، وملف README يغطي dbt Core 1.x وdbt OSS وdbt v2 ومنصة dbt. وتنبني عليه صفحة الأدلة.

​

تثبيت dbt-core وdbt-clickhouse

يوفّر dbt عدة خيارات لتثبيت واجهة سطر الأوامر (CLI)، وهي موضّحة بالتفصيل هنا. نوصي باستخدام pip لتثبيت كلٍّ من dbt وdbt-clickhouse.

pip install dbt-core dbt-clickhouse

​

زوّد dbt بتفاصيل الاتصال الخاصة بمثيل ClickHouse لدينا.

اضبط ملف التعريف clickhouse-service في الملف ~/.dbt/profiles.yml، ووفّر خصائص schema وhost وport وuser وpassword. تتوفر القائمة الكاملة بخيارات إعدادات الاتصال في صفحة الميزات والإعدادات:

clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ] # ClickHouse database for dbt models

      # Optional
      host: [ localhost ]
      port: [ 8123 ]  # Defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings
      user: [ default ] # User for all database operations
      password: [ <empty string> ] # Password for the user
      secure: True  # Use TLS (native protocol) or HTTPS (http protocol)

​

أنشئ مشروعًا لـ dbt

يمكنك الآن استخدام ملف التعريف هذا في أحد مشاريعك الحالية أو إنشاء مشروع جديد باستخدام:

dbt init project_name

داخل الدليل project_name، حدِّث ملف dbt_project.yml لتحديد اسم ملف التعريف للاتصال بخادم ClickHouse.

profile: 'clickhouse-service'

​

اختبار الاتصال

نفّذ dbt debug باستخدام أداة سطر الأوامر (CLI) للتأكد من أن dbt يستطيع الاتصال بـ ClickHouse. تأكد من أن المخرجات تتضمن Connection test: [OK connection ok]، مما يشير إلى نجاح الاتصال.

انتقل إلى صفحة الأدلة لمعرفة المزيد عن كيفية استخدام dbt مع ClickHouse.

​

اختبار نماذجك ونشرها (CI/CD)

توجد العديد من الطرق لاختبار مشروع dbt الخاص بك ونشره. يقدّم dbt بعض الاقتراحات حول سير العمل وفق أفضل الممارسات ومهام CI. سنستعرض عدة استراتيجيات، لكن ضع في اعتبارك أن هذه الاستراتيجيات قد تتطلّب تعديلات كبيرة لتلائم حالة الاستخدام الخاصة بك.

​

‏CI/CD مع اختبارات بيانات بسيطة واختبارات الوحدة

من الطرق البسيطة لبدء مسار CI لديك تشغيل عنقود ClickHouse داخل مهمتك، ثم تشغيل نماذجك عليه. ويمكنك إدراج بيانات تجريبية في هذا العنقود قبل تشغيل النماذج. كما يمكنك ببساطة استخدام seed لملء بيئة الاختبار قبل الإنتاج بمجموعة فرعية من بيانات الإنتاج لديك.

وبعد إدراج البيانات، يمكنك بعد ذلك تشغيل اختبارات البيانات واختبارات الوحدة.

ويمكن أن تكون خطوة CD لديك بسيطة مثل تشغيل dbt build على عنقود ClickHouse الخاص ببيئة الإنتاج.

​

مرحلة CI/CD أكثر اكتمالًا: استخدم بيانات حديثة، واختبر فقط النماذج المتأثرة

تتمثل إحدى الاستراتيجيات الشائعة في استخدام مهام Slim CI، بحيث لا يُعاد نشر سوى النماذج المعدّلة (وتبعياتها الصاعدة والهابطة). ويعتمد هذا النهج على المخرجات الناتجة عن عمليات التشغيل في بيئة الإنتاج لديك (أي dbt manifest) لتقليل زمن تشغيل مشروعك وضمان عدم حدوث انجراف في المخطط بين البيئات.

وللحفاظ على تزامن بيئات التطوير لديك وتجنب تشغيل نماذجك على عمليات نشر متقادمة، يمكنك استخدام clone أو حتى defer. في ClickHouse، ينسخ dbt clone جداول MergeTree باستخدام عبارة CLONE ذات النسخ الصفري — راجع استنساخ النماذج باستخدام dbt clone أدناه للاطلاع على التفاصيل.

نوصي باستخدام عنقود ClickHouse أو خدمة مخصصة لبيئة الاختبار (أي بيئة الاختبار قبل الإنتاج) لتجنب التأثير في تشغيل بيئة الإنتاج لديك. ولضمان أن تكون بيئة الاختبار ممثلةً للواقع، من المهم استخدام مجموعة فرعية من بيانات الإنتاج لديك، إلى جانب تشغيل dbt بطريقة تمنع انجراف المخطط بين البيئات.

• إذا لم تكن بحاجة إلى بيانات حديثة للاختبار، يمكنك استعادة نسخة احتياطية من بيانات الإنتاج لديك إلى البيئة المرحلية.
• إذا كنت بحاجة إلى بيانات حديثة للاختبار، فيمكنك استخدام مزيج من remoteSecure() دالة جدول والعروض المُجسَّدة القابلة للتحديث لإدراج البيانات بالوتيرة المطلوبة. وهناك خيار آخر يتمثل في استخدام تخزين الكائنات كوسيط، وكتابة البيانات دوريًا من خدمة الإنتاج لديك، ثم استيرادها إلى البيئة المرحلية باستخدام دوال الجداول الخاصة بتخزين الكائنات أو ClickPipes (للاستيعاب المستمر).

كما أن استخدام بيئة مخصصة لاختبارات CI يتيح لك إجراء اختبارات يدوية من دون التأثير في بيئة الإنتاج لديك. فعلى سبيل المثال، قد ترغب في توجيه أداة BI إلى هذه البيئة لاختبارها.

أما بالنسبة إلى النشر (أي خطوة CD)، فنوصي باستخدام المخرجات الناتجة عن عمليات النشر في بيئة الإنتاج لديك لتحديث النماذج التي تغيّرت فقط. ويتطلب ذلك إعداد تخزين الكائنات (مثل S3) كتخزين وسيط لمخرجات dbt لديك. وبعد إتمام ذلك، يمكنك تشغيل أمر مثل dbt build --select state:modified+ --state path/to/last/deploy/state.json لإعادة بناء الحد الأدنى من النماذج المطلوبة بشكل انتقائي استنادًا إلى ما تغيّر منذ آخر تشغيل في بيئة الإنتاج.

​

استنساخ النماذج باستخدام dbt clone

بدءًا من الإصدار 1.10.1 من dbt-clickhouse، يستخدم الأمر dbt clone تعليمة النسخ الصفري في ClickHouse، CREATE OR REPLACE TABLE ... CLONE AS ...، لاستنساخ النماذج المُجسَّدة كجداول تستخدم محركًا من عائلة MergeTree. ينشئ ذلك نسخة من الجدول دون تكرار data parts الأساسية، مما يجعله طريقة سريعة ومنخفضة التكلفة لمزامنة البيئات، مثل إعداد بيئة تطوير أو Slim CI استنادًا إلى حالة production.

تعود النماذج التي لا يمكن استنساخها بهذه الطريقة إلى سلوك dbt الافتراضي، وهو إنشاء عرض يشير إلى relation المصدر:

• الجداول التي تستخدم محركات غير MergeTree
• Distributed materializations

بالنسبة إلى نماذج عرض مُجسَّد، لا يُستنسخ سوى target جدول؛ أما عرض مُجسَّد نفسها فتُنشأ فوق الجدول المستنسخ.

​

استكشاف المشكلات الشائعة وإصلاحها

​

الاتصالات

إذا واجهت مشكلات عند الاتصال بـ ClickHouse من dbt، فتأكد من استيفاء المعايير التالية:

• يجب أن يكون المحرّك أحد المحرّكات المدعومة.
• يجب أن تتوفر لديك الأذونات الكافية للوصول إلى قاعدة البيانات.
• إذا كنت لا تستخدم محرّك الجدول الافتراضي لقاعدة البيانات، فيجب عليك تحديد محرّك جدول في تهيئة النموذج.

​

فهم العمليات طويلة الأمد

قد تستغرق بعض العمليات وقتًا أطول من المتوقع بسبب استعلامات معيّنة في ClickHouse. ولمعرفة أي الاستعلامات تستغرق وقتًا أطول بشكل أدق، ارفع مستوى السجل إلى debug — سيؤدي ذلك إلى عرض الوقت المستغرَق لكل استعلام. على سبيل المثال، يمكن تحقيق ذلك بإضافة --log-level debug إلى أوامر dbt.

​

ربط عمليات تشغيل dbt باستعلامات ClickHouse

للاطلاع على التفاصيل من جانب الخادم، بدءًا من الإصدار 1.10.1 من dbt-clickhouse، يُخصَّص لكل عبارة ينفذها المُهايئ معرّف استعلام خاص بها (UUID4)، ويُمرَّر إلى ClickHouse. ويُعاد معرّف العبارة الرئيسية للنموذج ضمن adapter_response في نتيجة dbt الخاصة به، لذا يكون متاحًا في مخرجات dbt، مثل run_results.json. يمكنك البحث عنه في جدول system.query_log لفحص توقيت تلك العبارة واستخدامها للموارد:

SELECT query_id, query, query_duration_ms, read_rows, memory_usage
FROM system.query_log
WHERE query_id = '<query_id from run_results.json>'
  AND type = 'QueryFinish'

لاحظ أن عملية تجسيد تُنفِّذ عادةً عدة عبارات لكل model ‏(مثل DDL وعمليات inserts)، ولكل منها query ID خاص بها؛ أما المعرّف الموجود في run_results.json فلا يحدد إلا العبارة الرئيسية الخاصة بـ model. للعثور على جميع العبارات المرتبطة بعملية تشغيل، استخدم filter على system.query_log استنادًا إلى تعليق query الخاص بـ dbt المضمَّن في نص كل query بدلًا من ذلك.

يتيح query ID أيضًا لأدوات observability التي تستهلك مخرجات dbt (مثل Elementary) ربط عمليات تشغيل models في dbt بـ entries في system.query_log تلقائيًا.

​

القيود

يحتوي مهايئ ClickHouse الحالي لـ dbt على عدة قيود ينبغي أن تكون على دراية بها:

• تستخدم الإضافة صياغة تتطلب ClickHouse بالإصدار 25.3 أو أحدث. نحن لا نختبر الإصدارات الأقدم من ClickHouse. كما أننا لا نختبر حاليًا الجداول Replicated.
• قد تتعارض عمليات تشغيل مختلفة لـ dbt-adapter إذا جرى تشغيلها في الوقت نفسه، لأنها قد تستخدم داخليًا أسماء الجداول نفسها للعمليات نفسها. لمزيد من المعلومات، راجع issue #420.
• يقوم المهايئ حاليًا بتمثيل النماذج كجداول باستخدام INSERT INTO SELECT. وهذا يعني فعليًا تكرار البيانات إذا أُعيد تنفيذ التشغيل. وقد تؤدي مجموعات البيانات الكبيرة جدًا (PB) إلى أوقات تشغيل طويلة للغاية، مما يجعل بعض النماذج غير عملية. لتحسين الأداء، استخدم ClickHouse عروض مُجسَّدة من خلال تنفيذ العرض بالشكل materialized: materialization_view. بالإضافة إلى ذلك، احرص على تقليل عدد الصفوف التي يعيدها أي استعلام باستخدام GROUP BY حيثما أمكن. ويُفضَّل استخدام النماذج التي تلخّص البيانات على تلك التي تكتفي بتحويلها مع الحفاظ على عدد الصفوف نفسه الموجود في المصدر.
• لاستخدام جداول موزعة لتمثيل نموذج، يجب إنشاء الجداول replicated الأساسية على كل عقدة يدويًا. ويمكن بعد ذلك إنشاء جدول موزع فوقها. لا يدير المهايئ إنشاء عنقود.
• عندما ينشئ dbt relation ‏(table/view) في database، فإنه ينشئه عادةً بالشكل: {{ database }}.{{ schema }}.{{ table/view id }}. لا يوجد في ClickHouse مفهوم schemas. لذلك يستخدم المهايئ الصيغة {{schema}}.{{ table/view id }}، حيث يكون schema هو ClickHouse database.

​

Fivetran

يتوفر موصل dbt-clickhouse أيضًا للاستخدام ضمن تحويلات Fivetran، ما يتيح إمكانات تكامل وتحويل سلسة مباشرةً داخل منصة Fivetran باستخدام dbt.