dbt / المتوسط: التاريخ والمسارات المضبوطة / الدرس 7

العقود والتوثيق وواجهات النماذج

انشر نموذج فروع مستقراً مع فصل عقد شكل الأعمدة وتأكيدات الأعمال وحوكمة الاعتماد.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

حدد شكل نموذج صريحاً ونطاق فرضه المدعوم.
ميّز إصدارات النموذج وإتاحة الاعتماد عن صلاحيات مستخدم القاعدة.

يعمل النموذج المشترك كواجهة بيانات

لنموذج فروع تستهلكه تقارير عدة واجهة: أسماء وأنواع وتفصيل ومعنى وحداثة. يستطيع عقد النموذج فحص ضمانات شكل أعمدة مدعومة أثناء البناء، ولا يثبت صحة الاسم أووجود كل الفروع. احتفظ باختبارات الأعمال ومطابقة المصدر معه. قد يكسر حذف عمود أوتغيير نوع مستهلكاً رغم عمل الاستعلام. وثق التغيير واختر نافذة ترحيل، بدلاً من اكتشاف الفرق بفشل تقرير صباحي.

يجب أن يسمي عقد الشكل المفروض الأعمدة الفعلية

يعلن المثال عمودَي varchar لنموذج ثنائي الأعمدة، بافتراض دعم المحوّل والهدف لهذا الاسم. يجب أن يغطي العقد كل أعمدة المخرج بأنواع متوافقة، لا قائمة جزئية مما تذكره المؤلف. يختلف الدعم حسب التجسيد والمنصة؛ فلا يغطي السلوك نفسه ephemeral أونماذج Python العادية. والقيود طبقة أخرى تختلف قابليتها للتعريف والفرض؛ فقد يكون primary_key بيانات وصفية مقبولة دون فرض تفرّد.

yaml مثال تقني توضيحي؛ النتائج المنطقية مستنتجة ولم تُختبر على المحرك.

version: 2
models:
  - name: dim_branches
    config:
      contract:
        enforced: true
    columns:
      - name: branch_id
        data_type: varchar
      - name: branch_name
        data_type: varchar

مثال شكل كامل لعمودين فقط. يحتاج توافق النوع ودعم العقد تحققاً مستقلاً معتمداً.

ليحفظ الوصف المعنى بدلاً من تكرار الاسم

صف branch_id كهوية مصدر ثابتة، لا «معرّف الفرع» فقط. وضح بقاء الهوية بعد تغيير الاسم والاسم المعتمد ومعالجة الغائب. يمكن لكتلة docs تجميع وصف أطول واستدعائها بـdoc() في الخصائص المدعومة. لتوليد التوثيق واستضافته حدود أوامر ومنصة؛ ولا يُشغّل منها شيء هنا. قد تكشف الأوصاف والآثار بيانات أعمال خاصة؛ فانشر المعتمد فقط. لا تعوض صفحة جميلة تفصيلاً ملتبساً.

ثبّت واجهة نموذج عند حاجة التغيير للتعايش

تختلف نسخة النموذج من المحرك والمشروع وصيغة YAML. يستطيع مستهلك طلب1 بينما ينتقل آخر إلى2، إذا عرّف المشروع النسختين وعلاقاتهما. يطلب المقطع نسخة معروفة بدلاً من متابعة latest_version تلقائياً. قد يحسن الثبات ويضيف صيانة وتقاعداً. وقد يكسر تغيير المعنى العقد رغم بقاء الأسماء والأنواع. لا يلغي الإصدار ضرورة إعلان تغير التفصيل والقياس ومطابقة الواجهتين أثناء الترحيل.

jinja مثال تقني توضيحي؛ النتائج المنطقية مستنتجة ولم تُختبر على المحرك.

select branch_id, branch_name
from {{ ref('dim_branches', v=1) }}

يتطلب نسخة1 معرفة صراحة. لا ينشئها ولا يمنح قراءة القاعدة.

تحكم إتاحة النموذج المراجع لا كل استعلام مستخدم

تحكم private وprotected وpublic مراجع dbt المدعومة ضمن المجموعة والمشروع. لا تعوض منح المستودع أوسياسات الصف أومدارة الأسرار. في أساس v1.12، لماكرو run-operation سلوك إتاحة موثق يختلف من ref العادية، مما يؤكد أنها ليست حداً أمنياً عاماً. راجع صلاحيات التشغيل مستقلة. لا تنشئ الدورة عقداً أودوراً أونسخة أوموقع توثيق. تفحص الشكل والواجهة المؤلفين فقط، ولا تدعي فرض قاعدة أوبناء ناجحاً.

الأخطاء الشائعة وإصلاحها

يُعامل عقد الأعمدة كضمان لحقيقة الأعمال

لماذا يحدث؟: اختلط تحقق الشكل بالمحتوى والاكتمال.
كيف تصلحه؟: أضف اختبارات البيانات ومطابقة المصدر المناسبة.
كيف تتجنب تكراره؟: وثق نطاق كل ضمان بدقة.

تُسمى إتاحة private تحكماً في مستخدم القاعدة

لماذا يحدث؟: اختلطت حوكمة الاعتماد بصلاحيات القاعدة.
كيف تصلحه؟: راجع هوية التشغيل والفرض الفعلي.
كيف تتجنب تكراره؟: افصل الحوكمة والاختبارات الأمنية.

يكسر تغير حساب بنفس النوع المستهلكين بصمت

لماذا يحدث؟: اختُزل التوافق الدلالي في الأسماء والأنواع.
كيف تصلحه؟: أصدر المعنى أو نسقه وطابق القياسات اللاحقة.
كيف تتجنب تكراره؟: راجع التفصيل والوحدات والتعريفات عند التغيير.

اختبر فهمك

1. هل يثبت عقد عمودين مفروض تفرّد هويات الفروع؟

اعرض الحل المشروح

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

2. لماذا يثبت مستهلك ref("dim_branches",v=1)؟