> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > يمكنك تحويل بياناتك ونمذجتها في ClickHouse باستخدام dbt # تكامل dbt مع ClickHouse export const ClickHouseSupportedBadge = () => { return
متوافق مع ClickHouse
; };
## مُهايئ dbt-clickhouse
يُمكّن **dbt** (أداة بناء البيانات) مهندسي التحليلات من تحويل البيانات في مستودعاتهم بمجرد كتابة عبارات SELECT. ويتولى dbt تحويل عبارات SELECT هذه إلى كائنات داخل قاعدة البيانات، مثل الجداول والعروض، وبذلك ينفّذ مرحلة التحويل (T) من [Extract Load and Transform (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform). يمكنك إنشاء نموذج يحدّده تعبير SELECT. داخل dbt، يمكن لهذه النماذج أن تشير إلى بعضها بعضًا وأن تُرتَّب في طبقات، مما يتيح بناء مفاهيم ذات مستوى أعلى. ويُولِّد تلقائيًا شيفرة SQL النمطية المطلوبة لربط النماذج. إضافة إلى ذلك، يحدّد dbt التبعيات بين النماذج ويضمن إنشاءها بالترتيب المناسب باستخدام رسم بياني موجّه لا دوري (DAG). يتوافق dbt مع ClickHouse عبر [مُهايئ مدعوم من ClickHouse](https://github.com/ClickHouse/dbt-clickhouse). | الصفحة | الوصف | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [الميزات والإعدادات](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | وصف للميزات والإعدادات العامة المتاحة | | [التجسيدات](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materializations) | التجسيدات المتاحة وإعداداتها | | [العروض المُجسَّدة](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | توثيق خاص بتجسيد materialized\_view | | [الأدلة](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/guides) | أدلة لاستخدام dbt مع ClickHouse |
## الميزات المدعومة
قائمة الميزات المدعومة: * [x] التجسيد للجدول * [x] التجسيد للعرض * [x] التجسيد تزايدية * [x] التجسيد تزايدية من نوع Microbatch * [x] التجسيدات من نوع Materialized View (تستخدم صيغة `TO` الخاصة بـ MATERIALIZED VIEW، وهي تجريبية) * [x] Seeds * [x] Sources * [x] إنشاء الوثائق * [x] الاختبارات * [x] Snapshots * [x] معظم وحدات الماكرو في dbt-utils (وهي الآن مضمنة في dbt-core) * [x] التجسيد مؤقتة * [x] التجسيد للجدول الموزع (تجريبية) * [x] التجسيد تزايدية موزعة (تجريبية) * [x] العقود * [x] إعدادات الأعمدة الخاصة بـ ClickHouse (Codec، TTL...) * [x] إعدادات الجداول الخاصة بـ ClickHouse (indexes، projections...) جميع الميزات حتى dbt-core 1.10 مدعومة، بما في ذلك الخيار `--sample` مع إصلاح جميع تحذيرات الإهمال للإصدارات المستقبلية. **تكاملات Catalog** (مثل Iceberg) التي قُدمت في dbt 1.10 ليست مدعومة أصلًا بعد في المهايئ، ولكن تتوفر حلول بديلة. راجع [قسم دعم Catalog](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support) للتفاصيل. لا يزال هذا المهايئ غير متاح للاستخدام داخل [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview)، لكننا نتوقع إتاحته قريبًا. يُرجى التواصل مع الدعم للحصول على مزيد من المعلومات حول هذا الأمر.
## مفاهيم dbt وأنواع التجسيد المدعومة
يقدّم dbt مفهوم النموذج. ويُعرَّف النموذج على أنه عبارة SQL قد تجمع بين العديد من الجداول. ويمكن "تجسيد" النموذج بعدة طرق. ويمثل التجسيد استراتيجية بناء لاستعلام `select` الخاص بالنموذج. أما الشيفرة التي تقف وراء التجسيد فهي SQL قالبية تُغلّف استعلام SELECT الخاص بك داخل عبارة بهدف إنشاء relation جديدة أو تحديث relation موجودة. يوفر dbt خمسة أنواع من التجسيد، وكلها مدعومة بواسطة `dbt-clickhouse`: * **view** (الافتراضي): يُبنى النموذج كـ view في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ [view](/docs/ar/reference/statements/create/view). * **table**: يُبنى النموذج كـ table في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ [table](/docs/ar/reference/statements/create/table). * **ephemeral**: لا يُبنى النموذج مباشرةً في قاعدة البيانات، بل يُدرج داخل النماذج التابعة على شكل CTEs ‏(Common Table Expressions). * **incremental**: يُجسَّد النموذج في البداية كـ table، وفي عمليات التشغيل اللاحقة يُدرج dbt rows جديدة ويحدّث rows المتغيرة في table. * **materialized view**: يُبنى النموذج كـ materialized view في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ [materialized view](/docs/ar/reference/statements/create/view#materialized-view). وتحدد الصياغة الإضافية وclausees المختلفة كيفية تحديث هذه النماذج إذا تغيّرت بياناتها الأساسية. ويوصي dbt عمومًا بالبدء بتجسيد view إلى أن يصبح الأداء مصدر قلق. ويوفر تجسيد table تحسينًا في الأداء وقت الاستعلام عبر حفظ نتائج استعلام النموذج في table، مقابل زيادة في التخزين. ويطوّر نهج incremental هذه الفكرة أكثر، بحيث يمكن التقاط التحديثات اللاحقة على البيانات الأساسية في target table. كما يدعم [المهايئ الحالي](https://github.com/silentsokolov/dbt-clickhouse) لـ ClickHouse أيضًا أنواع التجسيد **dictionary** و**distributed table** و**distributed incremental**. ويدعم المهايئ كذلك [snapshots](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy) و[seeds](https://docs.getdbt.com/docs/building-a-dbt-project/seeds) في dbt. فيما يلي [الميزات التجريبية](/docs/ar/reference/settings/beta-and-experimental-features) في `dbt-clickhouse`: | النوع | هل هو مدعوم؟ | التفاصيل | | --------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Materialized View materialization | نعم. الإنشاء باستخدام explicit target ما يزال في Beta | ينشئ [materialized view](/docs/ar/reference/statements/create/view#materialized-view). | | Distributed table materialization | نعم، تجريبي | ينشئ [distributed table](/docs/ar/reference/engines/table-engines/special/distributed). | | Distributed incremental materialization | نعم، تجريبي | نموذج incremental يستند إلى الفكرة نفسها الخاصة بـ distributed table. لاحظ أن بعض الاستراتيجيات غير مدعومة؛ راجع [قسم الوثائق الخاص بها](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental) لمزيد من المعلومات. | | Dictionary materialization | نعم، تجريبي | ينشئ [dictionary](/docs/ar/reference/engines/table-engines/special/dictionary). |
## إعداد dbt ومهايئ ClickHouse
### تثبيت dbt-core وdbt-clickhouse
يوفّر dbt عدة خيارات لتثبيت واجهة سطر الأوامر (CLI)، وهي موضّحة بالتفصيل [هنا](https://docs.getdbt.com/dbt-cli/install/overview). نوصي باستخدام `pip` لتثبيت كلٍّ من dbt وdbt-clickhouse. ```sh theme={null} pip install dbt-core dbt-clickhouse ```
### زوّد dbt بتفاصيل الاتصال الخاصة بمثيل ClickHouse لدينا.
اضبط ملف التعريف `clickhouse-service` في الملف `~/.dbt/profiles.yml`، ووفّر خصائص `schema` و`host` و`port` و`user` و`password`. تتوفر القائمة الكاملة بخيارات إعدادات الاتصال في صفحة [الميزات والإعدادات](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations): ```yaml theme={null} 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: [ ] # Password for the user secure: True # Use TLS (native protocol) or HTTPS (http protocol) ```
### أنشئ مشروعًا لـ dbt
يمكنك الآن استخدام ملف التعريف هذا في أحد مشاريعك الحالية أو إنشاء مشروع جديد باستخدام: ```sh theme={null} dbt init project_name ``` داخل الدليل `project_name`، حدِّث ملف `dbt_project.yml` لتحديد اسم ملف التعريف للاتصال بخادم ClickHouse. ```yaml theme={null} profile: 'clickhouse-service' ```
### اختبار الاتصال
نفّذ `dbt debug` باستخدام أداة سطر الأوامر (CLI) للتأكد من أن dbt يستطيع الاتصال بـ ClickHouse. تأكد من أن المخرجات تتضمن `Connection test: [OK connection ok]`، مما يشير إلى نجاح الاتصال. انتقل إلى [صفحة الأدلة](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/guides) لمعرفة المزيد عن كيفية استخدام dbt مع ClickHouse.
### اختبار نماذجك ونشرها (CI/CD)
توجد العديد من الطرق لاختبار مشروع dbt الخاص بك ونشره. يقدّم dbt بعض الاقتراحات حول [سير العمل وفق أفضل الممارسات](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) و[مهام CI](https://docs.getdbt.com/docs/deploy/ci-jobs). سنستعرض عدة استراتيجيات، لكن ضع في اعتبارك أن هذه الاستراتيجيات قد تتطلّب تعديلات كبيرة لتلائم حالة الاستخدام الخاصة بك.
#### ‏CI/CD مع اختبارات بيانات بسيطة واختبارات الوحدة
من الطرق البسيطة لبدء مسار CI لديك تشغيل عنقود ClickHouse داخل مهمتك، ثم تشغيل نماذجك عليه. ويمكنك إدراج بيانات تجريبية في هذا العنقود قبل تشغيل النماذج. كما يمكنك ببساطة استخدام [seed](https://docs.getdbt.com/reference/commands/seed) لملء بيئة الاختبار قبل الإنتاج بمجموعة فرعية من بيانات الإنتاج لديك. وبعد إدراج البيانات، يمكنك بعد ذلك تشغيل [اختبارات البيانات](https://docs.getdbt.com/docs/build/data-tests) و[اختبارات الوحدة](https://docs.getdbt.com/docs/build/unit-tests). ويمكن أن تكون خطوة CD لديك بسيطة مثل تشغيل `dbt build` على عنقود ClickHouse الخاص ببيئة الإنتاج.
#### مرحلة CI/CD أكثر اكتمالًا: استخدم بيانات حديثة، واختبر فقط النماذج المتأثرة
تتمثل إحدى الاستراتيجيات الشائعة في استخدام مهام [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci)، بحيث لا يُعاد نشر سوى النماذج المعدّلة (وتبعياتها الصاعدة والهابطة). ويعتمد هذا النهج على المخرجات الناتجة عن عمليات التشغيل في بيئة الإنتاج لديك (أي [dbt manifest](https://docs.getdbt.com/reference/artifacts/manifest-json)) لتقليل زمن تشغيل مشروعك وضمان عدم حدوث انجراف في المخطط بين البيئات. وللحفاظ على تزامن بيئات التطوير لديك وتجنب تشغيل نماذجك على عمليات نشر متقادمة، يمكنك استخدام [clone](https://docs.getdbt.com/reference/commands/clone) أو حتى [defer](https://docs.getdbt.com/reference/node-selection/defer). نوصي باستخدام عنقود ClickHouse أو خدمة مخصصة لبيئة الاختبار (أي بيئة مرحلية) لتجنب التأثير في تشغيل بيئة الإنتاج لديك. ولضمان أن تكون بيئة الاختبار ممثلةً للواقع، من المهم استخدام مجموعة فرعية من بيانات الإنتاج لديك، إلى جانب تشغيل dbt بطريقة تمنع انجراف المخطط بين البيئات. * إذا لم تكن بحاجة إلى بيانات حديثة للاختبار، يمكنك استعادة نسخة احتياطية من بيانات الإنتاج لديك إلى البيئة المرحلية. * إذا كنت بحاجة إلى بيانات حديثة للاختبار، فيمكنك استخدام مزيج من [`remoteSecure()` table function](/docs/ar/reference/functions/table-functions/remote) والعروض المادية القابلة للتحديث لإدراج البيانات بالوتيرة المطلوبة. وهناك خيار آخر يتمثل في استخدام تخزين الكائنات كوسيط، وكتابة البيانات دوريًا من خدمة الإنتاج لديك، ثم استيرادها إلى البيئة المرحلية باستخدام دوال الجداول الخاصة بتخزين الكائنات أو ClickPipes (للاستيعاب المستمر). كما أن استخدام بيئة مخصصة لاختبارات CI يتيح لك إجراء اختبارات يدوية من دون التأثير في بيئة الإنتاج لديك. فعلى سبيل المثال، قد ترغب في توجيه أداة BI إلى هذه البيئة لاختبارها. أما بالنسبة إلى النشر (أي خطوة CD)، فنوصي باستخدام المخرجات الناتجة عن عمليات النشر في بيئة الإنتاج لديك لتحديث النماذج التي تغيّرت فقط. ويتطلب ذلك إعداد تخزين الكائنات (مثل S3) كتخزين وسيط لمخرجات dbt لديك. وبعد إتمام ذلك، يمكنك تشغيل أمر مثل `dbt build --select state:modified+ --state path/to/last/deploy/state.json` لإعادة بناء الحد الأدنى من النماذج المطلوبة بشكل انتقائي استنادًا إلى ما تغيّر منذ آخر تشغيل في بيئة الإنتاج.
## استكشاف المشكلات الشائعة وإصلاحها
### الاتصالات
إذا واجهت مشكلات عند الاتصال بـ ClickHouse من dbt، فتأكد من استيفاء المعايير التالية: * يجب أن يكون المحرّك أحد [المحرّكات المدعومة](/docs/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines). * يجب أن تتوفر لديك الأذونات الكافية للوصول إلى قاعدة البيانات. * إذا كنت لا تستخدم محرّك الجدول الافتراضي لقاعدة البيانات، فيجب عليك تحديد محرّك جدول في تهيئة النموذج.
### فهم العمليات طويلة الأمد
قد تستغرق بعض العمليات وقتًا أطول من المتوقع بسبب استعلامات معيّنة في ClickHouse. ولمعرفة أي الاستعلامات تستغرق وقتًا أطول بشكل أدق، ارفع [مستوى السجل](https://docs.getdbt.com/reference/global-configs/logs#log-level) إلى `debug` — سيؤدي ذلك إلى عرض الوقت المستغرَق لكل استعلام. على سبيل المثال، يمكن تحقيق ذلك بإضافة `--log-level debug` إلى أوامر dbt.
## القيود
يحتوي مهايئ ClickHouse الحالي لـ dbt على عدة قيود ينبغي أن تكون على دراية بها: * تستخدم الإضافة صياغة تتطلب ClickHouse بالإصدار 25.3 أو أحدث. نحن لا نختبر الإصدارات الأقدم من ClickHouse. كما أننا لا نختبر حاليًا الجداول Replicated. * قد تتعارض عمليات تشغيل مختلفة لـ `dbt-adapter` إذا جرى تشغيلها في الوقت نفسه، لأنها قد تستخدم داخليًا أسماء الجداول نفسها للعمليات نفسها. لمزيد من المعلومات، راجع issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420). * يقوم المهايئ حاليًا بتمثيل النماذج كجداول باستخدام [INSERT INTO SELECT](/docs/ar/reference/statements/insert-into#inserting-the-results-of-select). وهذا يعني فعليًا تكرار البيانات إذا أُعيد تنفيذ التشغيل. وقد تؤدي مجموعات البيانات الكبيرة جدًا (PB) إلى أوقات تشغيل طويلة للغاية، مما يجعل بعض النماذج غير عملية. لتحسين الأداء، استخدم ClickHouse Materialized Views من خلال تنفيذ العرض بالشكل `materialized: materialization_view`. بالإضافة إلى ذلك، احرص على تقليل عدد الصفوف التي يعيدها أي استعلام باستخدام `GROUP BY` حيثما أمكن. ويُفضَّل استخدام النماذج التي تلخّص البيانات على تلك التي تكتفي بتحويلها مع الحفاظ على عدد الصفوف نفسه الموجود في المصدر. * لاستخدام Distributed tables لتمثيل نموذج، يجب إنشاء الجداول replicated الأساسية على كل عقدة يدويًا. ويمكن بعد ذلك إنشاء Distributed table فوقها. لا يدير المهايئ إنشاء عنقود. * عندما ينشئ dbt relation ‏(table/view) في database، فإنه ينشئه عادةً بالشكل: `{{ database }}.{{ schema }}.{{ table/view id }}`. لا يوجد في ClickHouse مفهوم schemas. لذلك يستخدم المهايئ الصيغة `{{schema}}.{{ table/view id }}`، حيث يكون `schema` هو ClickHouse database. * لا تعمل النماذج ephemeral/CTEs إذا وُضعت قبل `INSERT INTO` في statement إدراج في ClickHouse، راجع [https://github.com/ClickHouse/ClickHouse/issues/30323](https://github.com/ClickHouse/ClickHouse/issues/30323). لا ينبغي أن يؤثر ذلك في معظم النماذج، لكن ينبغي توخي الحذر عند تحديد موضع النموذج ephemeral في تعريفات النماذج وعبارات SQL الأخرى. {/* TODO review this limitation, looks like the issue was already closed and the fix was introduced in 24.10 */}
## Fivetran
يتوفر موصل `dbt-clickhouse` أيضًا للاستخدام ضمن [تحويلات Fivetran](https://fivetran.com/docs/transformations/dbt)، ما يتيح إمكانات تكامل وتحويل سلسة مباشرةً داخل منصة Fivetran باستخدام `dbt`.