> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>ميزة Beta</span>
        </a>;
};

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            متوافق مع ClickHouse
        </div>;
};

<ClickHouseSupportedBadge />

<BetaBadge link="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.
</Warning>

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

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

تُتابع الحالة المباشرة في [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).

<h4 id="request-access">
  جرّب ClickHouse في منصة dbt
</h4>

إذا كنت مهتمًا باختبار الإصدار التجريبي الخاص (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 لإعداد الاتصال.

<h2 id="terminology">
  المصطلحات والتوافر
</h2>

يتوفر 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. |

<h2 id="beta-status">
  حالة Beta
</h2>

نقيس أداء 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 مدرج في خطة الطريق وسيصدر قريبًا، وسنحدّث الوثائق بمجرد أن يكون جاهزًا.

<h3 id="out-of-scope">
  خارج نطاق Beta
</h3>

بالإضافة إلى فجوات التكافؤ مع الإصدار 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.

<h2 id="parity">
  التكافؤ بين v1 وv2
</h2>

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

<Badge color="green">مدعوم</Badge> يعمل حاليًا · <Badge color="yellow">جزئي</Badge> يعمل ضمن قيود · <Badge color="red">ليس بعد</Badge> قيد التنفيذ.

### التجسيدات

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

### تهيئة الـ model

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

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

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

### العنقود وClickHouse Cloud

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

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

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

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

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