dbt / المتقدم: الأدلة والعزل والنشر القابل للتعافي / الدرس 16

الحزم والتوجيه وتوافق المحوّلات

عامل الماكرو المعاد استخدامها كتبعيات تنفيذية بإصدارات، وراجع التنفيذ الذي يختاره المشروع فعلياً.

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

في هذه الصفحة

أهداف الدرس

ميّز مواصفة الحزمة وقفل الحل والكود المثبت.
اشرح توجيه المحوّل ومتطلبات التوافق المستقلة.

تستورد الحزمة سلوكاً لا أسماء مريحة فقط

قد تضيف الحزمة ماكرو واختبارات ونماذج وموارد مدعومة. قد تخفي مراجعة موضع الاستدعاء وحده استعلامات أوخطافات أوسلوك هدف داخلها. اختر أصلاً معتمداً وافحص الكود والترخيص. ليست قائمة Hub اعتماداً عاماً للأمن أوالتنفيذ. احفظ جيل المحرك والمحوّل والحزمة في الدليل. تصدر محوّلات v1 مستقلة؛ فلا يعوض تطابق الأرقام الفرعية متطلبات الواجهة الموثقة.

النسخة المراجعة مدخل لإعادة الإنتاج

يثبت المثال dbt_utils 1.4.1 التي عرضها Hub الرسمي يوم المراجعة بنطاق إطار معلن واسع. هو مثال مسمى، لا ادعاء بأنها ستبقى الأحدث أوتوصية لتثبيتها في مشروع مهيأ. لا يثبت النطاق كل فرع ماكرو على المحوّل. المواصفة وpackage-lock.yml والكود المثبت آثار مختلفة مترابطة. يحفظ القفل الحل وفق السلوك المدعوم، ولا يحدث تغيير المواصفة الملفات المثبتة وحده. لا يُشغّل أمر تبعيات هنا.

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

packages:
  - package: dbt-labs/dbt_utils
    version: 1.4.1

مواصفة حزمة نموذجية مراجعة فقط؛ لا تنزّل شيئاً ولا تعتمد المحوّل أوالأمن.

يختار dispatch التنفيذ بقواعد بحث مضبوطة

يسمح التوجيه باستدعاء اسم منطقي واختيار تنفيذ خاص أوافتراضي مدعوم. يفوض المثال إلى lower(trim(...)) ما لم يُختر تجاوز صحيح. المدخل تعبير مطور موثوق، لا بيانات مستخدم مرتبطة. قد يغير تجاوز المشروع أوترتيب الحزم SQL دون تغير الاستدعاء الظاهر. راجع ترتيب البحث والنطاق عند التشخيص. ولا تعني default SQL محمولة دائماً أوسلوك يونيكود وترتيب نص موحداً.

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

{% macro normalize_code(expression) %}
  {{ return(adapter.dispatch('normalize_code', 'library_analytics')(expression)) }}
{% endmacro %}

{% macro default__normalize_code(expression) %}
  lower(trim({{ expression }}))
{% endmacro %}

غلاف وتطبيق افتراضي توضيحيان. تحتاج التجاوزات ودلالات النص مراجعة مستقلة؛ ولم تُولد الماكرو.

قد تؤثر تغيرات الجيل وسياق الملف في الحزم

قد تحتاج حزمة v1 ترحيلاً لتحقق v2 الأشد، وقد تغيب ميزة v2 عن أساس1.12. ويختلف دعم Jinja حسب الملف؛ فلا تولد dependencies.yml والخصائص كل ماكرو اعتباطية. راجع دليل الجيل والتصريح، ثم المسارات المستخدمة. وشارة توافق التحليل أضعف من تشغيل الهدف. احتفظ بنطاق ما اختُبر ولا تعتمد الحزمة كلها لنجاح ماكرو واحدة.

تحتاج ترقية التبعية فحص المعنى والتعافي

قارن SQL والاختبارات والمخرجات الممثلة عند تغيير حزمة أومحوّل. قد يغير مفتاح بديل أوتطبيع هوية ربط تاريخية دون تغير المخطط. خطط للملء وتوافق incremental والمستهلك قبل الاعتماد. لا تضع أسراراً بعناوين الحزم أوسجلاتها، واستخدم آلية معتمدة للخاصة. لا تثبت الدورة حزمة، ولا تستورد dbt ولا تختبر محوّلاً؛ تفحص شكل YAML ونص النسخة ومحددات الماكرو فقط، لا حل التبعية أوالتوجيه أوالنتيجة.

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

يُفترض أن القفل يثبت توافق التنفيذ

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

يغير تجاوز dispatch تطبيع المفتاح بصمت

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

يُعامل تطابق أرقام المحوّل والمحرك كتوافق لازم

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

اختبر فهمك

1. ماذا يثبت تثبيت dbt_utils 1.4.1 في المثال؟

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

يسمي نسخة التبعية المطلوبة المراجعة. لا ينزلها أويتحقق من الكود أويثبت المحوّل أودعم كل الميزات. احفظ القفل والمسارات المختبرة مستقلة في مشروع مصرح.

2. لماذا قد يتغير مخرج normalize_code دون تحرير استدعائها؟