> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/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). | الصفحة | الوصف | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [الميزات والإعدادات](/ar/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | وصف للميزات والإعدادات العامة المتاحة | | [التجسيدات](/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materializations) | التجسيدات المتاحة وإعداداتها | | [العروض المُجسَّدة](/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | توثيق خاص بتجسيد materialized\_view | | [الأدلة](/ar/integrations/connectors/data-ingestion/etl-tools/dbt/guides) | أدلة لاستخدام dbt مع ClickHouse |
## الميزات المدعومة
قائمة الميزات المدعومة: * [x] التجسيد للجدول * [x] التجسيد للعرض * [x] التجسيد تزايدية * [x] التجسيد تزايدية من نوع Microbatch * [x] التجسيدات من نوع عرض مُجسَّد (تستخدم صيغة `TO` الخاصة بـ MATERIALIZED VIEW، وهي تجريبية) * [x] Seeds * [x] Sources * [x] إنشاء الوثائق * [x] الاختبارات * [x] Snapshots * [x] معظم وحدات الماكرو في dbt-utils (وهي الآن مضمنة في dbt-core) * [x] التجسيد مؤقتة * [x] التجسيد للجدول الموزع (تجريبية) * [x] التجسيد تزايدية موزعة (تجريبية) * [x] تجسيد Dictionary (تجريبية) * [x] العقود * [x] إعدادات الأعمدة الخاصة بـ ClickHouse (Codec، TTL...) * [x] إعدادات الجداول الخاصة بـ ClickHouse (indexes، projections...) جميع الميزات حتى dbt-core 1.10 مدعومة، بما في ذلك الخيار `--sample` مع إصلاح جميع تحذيرات الإهمال للإصدارات المستقبلية. **تكاملات Catalog** (مثل Iceberg) التي قُدمت في dbt 1.10 ليست مدعومة أصلًا بعد في المهايئ، ولكن تتوفر حلول بديلة. راجع [قسم دعم Catalog](/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`: * **عرض** (الافتراضي): يُبنى النموذج كـ عرض في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ [عرض](/ar/reference/statements/create/view). * **جدول**: يُبنى النموذج كـ جدول في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ [جدول](/ar/reference/statements/create/table). * **ephemeral**: لا يُبنى النموذج مباشرةً في قاعدة البيانات، بل يُدرج داخل النماذج التابعة على شكل CTEs ‏(Common Table Expressions). * **incremental**: يُجسَّد النموذج في البداية كـ جدول، وفي عمليات التشغيل اللاحقة يُدرج dbt rows جديدة ويحدّث rows المتغيرة في جدول. * **عرض مُجسَّد**: يُبنى النموذج كـ عرض مُجسَّد في قاعدة البيانات. وفي ClickHouse يُنشأ هذا كـ [عرض مُجسَّد](/ar/reference/statements/create/view#materialized-view). وتحدد الصياغة الإضافية وclausees المختلفة كيفية تحديث هذه النماذج إذا تغيّرت بياناتها الأساسية. ويوصي dbt عمومًا بالبدء بتجسيد عرض إلى أن يصبح الأداء مصدر قلق. ويوفر تجسيد جدول تحسينًا في الأداء وقت الاستعلام عبر حفظ نتائج استعلام النموذج في جدول، مقابل زيادة في التخزين. ويطوّر نهج incremental هذه الفكرة أكثر، بحيث يمكن التقاط التحديثات اللاحقة على البيانات الأساسية في target جدول. فيما يلي [الميزات التجريبية](/ar/reference/settings/beta-and-experimental-features) في `dbt-clickhouse`: | النوع | هل هو مدعوم؟ | التفاصيل | | ----------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | عرض مُجسَّد تجسيد | نعم. الإنشاء باستخدام explicit target ما يزال في Beta | ينشئ [عرض مُجسَّد](/ar/reference/statements/create/view#materialized-view). | | Distributed جدول تجسيد | نعم، تجريبي | ينشئ [distributed جدول](/ar/reference/engines/table-engines/special/distributed). | | Distributed incremental تجسيد | نعم، تجريبي | نموذج incremental يستند إلى الفكرة نفسها الخاصة بـ distributed جدول. لاحظ أن بعض الاستراتيجيات غير مدعومة؛ راجع [قسم الوثائق الخاص بها](/ar/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental) لمزيد من المعلومات. | | Dictionary تجسيد | نعم، تجريبي | ينشئ [dictionary](/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`. تتوفر القائمة الكاملة بخيارات إعدادات الاتصال في صفحة [الميزات والإعدادات](/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]`، مما يشير إلى نجاح الاتصال. انتقل إلى [صفحة الأدلة](/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 clone` جداول MergeTree باستخدام عبارة `CLONE` ذات النسخ الصفري — راجع [استنساخ النماذج باستخدام dbt clone](#dbt-clone) أدناه للاطلاع على التفاصيل. نوصي باستخدام عنقود ClickHouse أو خدمة مخصصة لبيئة الاختبار (أي بيئة الاختبار قبل الإنتاج) لتجنب التأثير في تشغيل بيئة الإنتاج لديك. ولضمان أن تكون بيئة الاختبار ممثلةً للواقع، من المهم استخدام مجموعة فرعية من بيانات الإنتاج لديك، إلى جانب تشغيل dbt بطريقة تمنع انجراف المخطط بين البيئات. * إذا لم تكن بحاجة إلى بيانات حديثة للاختبار، يمكنك استعادة نسخة احتياطية من بيانات الإنتاج لديك إلى البيئة المرحلية. * إذا كنت بحاجة إلى بيانات حديثة للاختبار، فيمكنك استخدام مزيج من [`remoteSecure()` دالة جدول](/ar/reference/functions/table-functions/remote) والعروض المُجسَّدة القابلة للتحديث لإدراج البيانات بالوتيرة المطلوبة. وهناك خيار آخر يتمثل في استخدام تخزين الكائنات كوسيط، وكتابة البيانات دوريًا من خدمة الإنتاج لديك، ثم استيرادها إلى البيئة المرحلية باستخدام دوال الجداول الخاصة بتخزين الكائنات أو 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`](https://docs.getdbt.com/reference/commands/clone) تعليمة النسخ الصفري في ClickHouse، `CREATE OR REPLACE TABLE ... CLONE AS ...`، لاستنساخ النماذج المُجسَّدة كجداول تستخدم محركًا من عائلة MergeTree. ينشئ ذلك نسخة من الجدول دون تكرار data parts الأساسية، مما يجعله طريقة سريعة ومنخفضة التكلفة لمزامنة البيئات، مثل إعداد بيئة تطوير أو [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci) استنادًا إلى حالة production. تعود النماذج التي لا يمكن استنساخها بهذه الطريقة إلى سلوك dbt الافتراضي، وهو إنشاء عرض يشير إلى relation المصدر: * الجداول التي تستخدم محركات غير MergeTree * Distributed materializations بالنسبة إلى نماذج عرض مُجسَّد، لا يُستنسخ سوى target جدول؛ أما عرض مُجسَّد نفسها فتُنشأ فوق الجدول المستنسخ.
## استكشاف المشكلات الشائعة وإصلاحها
### الاتصالات
إذا واجهت مشكلات عند الاتصال بـ ClickHouse من dbt، فتأكد من استيفاء المعايير التالية: * يجب أن يكون المحرّك أحد [المحرّكات المدعومة](/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.
### ربط عمليات تشغيل dbt باستعلامات ClickHouse
للاطلاع على التفاصيل من جانب الخادم، بدءًا من الإصدار 1.10.1 من dbt-clickhouse، يُخصَّص لكل عبارة ينفذها المُهايئ معرّف استعلام خاص بها (UUID4)، ويُمرَّر إلى ClickHouse. ويُعاد معرّف العبارة الرئيسية للنموذج ضمن `adapter_response` في نتيجة dbt الخاصة به، لذا يكون متاحًا في مخرجات dbt، مثل [`run_results.json`](https://docs.getdbt.com/reference/artifacts/run-results-json). يمكنك البحث عنه في جدول [`system.query_log`](/ar/reference/system-tables/query_log) لفحص توقيت تلك العبارة واستخدامها للموارد: ```sql theme={null} SELECT query_id, query, query_duration_ms, read_rows, memory_usage FROM system.query_log WHERE query_id = '' AND type = 'QueryFinish' ``` لاحظ أن عملية تجسيد تُنفِّذ عادةً عدة عبارات لكل model ‏(مثل DDL وعمليات inserts)، ولكل منها query ID خاص بها؛ أما المعرّف الموجود في `run_results.json` فلا يحدد إلا العبارة الرئيسية الخاصة بـ model. للعثور على جميع العبارات المرتبطة بعملية تشغيل، استخدم filter على `system.query_log` استنادًا إلى [تعليق query الخاص بـ dbt](https://docs.getdbt.com/reference/project-configs/query-comment) المضمَّن في نص كل query بدلًا من ذلك. يتيح query ID أيضًا لأدوات observability التي تستهلك مخرجات dbt (مثل Elementary) ربط عمليات تشغيل models في dbt بـ entries في `system.query_log` تلقائيًا.
## القيود
يحتوي مهايئ ClickHouse الحالي لـ dbt على عدة قيود ينبغي أن تكون على دراية بها: * تستخدم الإضافة صياغة تتطلب ClickHouse بالإصدار 25.3 أو أحدث. نحن لا نختبر الإصدارات الأقدم من ClickHouse. كما أننا لا نختبر حاليًا الجداول Replicated. * قد تتعارض عمليات تشغيل مختلفة لـ `dbt-adapter` إذا جرى تشغيلها في الوقت نفسه، لأنها قد تستخدم داخليًا أسماء الجداول نفسها للعمليات نفسها. لمزيد من المعلومات، راجع issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420). * يقوم المهايئ حاليًا بتمثيل النماذج كجداول باستخدام [INSERT INTO SELECT](/ar/reference/statements/insert-into#inserting-the-results-of-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. * لا تعمل النماذج ephemeral/CTEs إذا وُضعت قبل `INSERT INTO` في statement إدراج في ClickHouse، راجع [https://github.com/ClickHouse/ClickHouse/issues/30323](https://github.com/ClickHouse/ClickHouse/issues/30323). لا ينبغي أن يؤثر ذلك في معظم النماذج، لكن ينبغي توخي الحذر عند تحديد موضع النموذج ephemeral في تعريفات النماذج وعبارات SQL الأخرى.
## Fivetran
يتوفر موصل `dbt-clickhouse` أيضًا للاستخدام ضمن [تحويلات Fivetran](https://fivetran.com/docs/transformations/dbt)، ما يتيح إمكانات تكامل وتحويل سلسة مباشرةً داخل منصة Fivetran باستخدام `dbt`.