> ## 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 adapter في dbt OSS وdbt v2 ومنصة dbt

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

متوافق مع ClickHouse

[Beta](https://github.com/ClickHouse/dbt-clickhouse/issues/660)

تجري إعادة بناء 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 ونصون كلا المحولين بالتوازي.

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

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

> [!NOTE]
>
> **dbt OSS** هو البناء مفتوح المصدر (Apache 2.0) لمحرك v2. راجع [المصطلحات والتوافر](#terminology) لمعرفة علاقته بـ dbt v2 ومنصة dbt.

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

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

إذا كنت مهتمًا باختبار الإصدار التجريبي الخاص (Beta)، فسجّل عبر [نموذج الإصدار التجريبي الخاص الخاص بـ dbt Labs](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). النموذج تابع لـ dbt Labs، لذا فإن المعلومات التي ترسلها تذهب إلى dbt Labs وليس إلى ClickHouse. وبعد تفعيل الوصول، اتبع [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) في وثائق dbt لإعداد الاتصال.

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

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

| المصطلح | ما هو | حالة الدعم في ClickHouse وكيفية الحصول عليه |
| - | - | - |
| **dbt Core 1.x** | محرك dbt المبني على بايثون، open source (Apache 2.0). الـ adapter الخاص بنا هو `dbt-clickhouse`، ويجري صيانته ضمن [منظمة ClickHouse على GitHub](https://github.com/ClickHouse/dbt-clickhouse) ويُثبَّت إلى جانب `dbt-core`. | **GA، تجري صيانته.** ولا يزال يتلقى إصدارات in parallel مع dbt v2. |
| **dbt OSS** | إعادة كتابة كاملة لمحرك dbt بلغة Rust، open source (Apache 2.0). يتضمن هذا الإصدار الجديد جميع مزايا الإصدار v1 إضافةً إلى عدة تحسينات في الأداء. | **Beta.** اتبع [dbt v2 upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2) و[صفحة إعداد ClickHouse للإصدار v2](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2) في وثائق dbt. يأتي adapter الخاص بـ ClickHouse مدمجًا داخل binary الخاص بـ dbt، ولا حاجة لتثبيت package منفصل. |
| **dbt v2** | dbt OSS مع مزايا إضافية من dbt Labs: فهم SQL، والتحليل الساكن، وLSP، وextension لـ VS Code، والوعي بالـ column. مغلق المصدر، ومرخَّص بموجب [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-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](#request-access). الإعداد: [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/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](#parity) للحصول على صورة تفصيلية ميزة بميزة.

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

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

### خارج نطاق Beta

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

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

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

تقارن الجداول أدناه الميزات المتاحة في `dbt-clickhouse` (v1) بحالتها في محوّل dbt v2. جميع الميزات المدرجة مدعومة في v1 ما لم تُشر الملاحظات إلى خلاف ذلك، أما عمود الحالة فيخص dbt v2 وينطبق كذلك على dbt OSS. ويمكن متابعة تطوّر كل عنصر قيد الانتظار في [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/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` غير متاح. |