dbt / الأساسي: أسس المشروع والنماذج / الدرس 4

Jinja والماكرو وسياق التنفيذ

ولّد SQL قابلاً للمراجعة مع توضيح النصوص والاعتماديات والآثار في المستودع.

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

في هذه الصفحة

أهداف الدرس

ميّز قيم القالب من معرّفات SQL وقيمه الحرفية.
استخدم منطقاً واعياً بـexecute دون اعتبار الترجمة بلا اتصال دائماً.

تولد Jinja SQL ولا تقيّم كل صف

تعمل Jinja عندما يولد dbt نص المشروع. قد تولد الماكرو CASE تقيّمها القاعدة لاحقاً لكل إعارة، لكنها لا تصبح تلقائياً دالة قاعدة مثبتة. تستخدم التعابير {{...}} للإخراج والعبارات {%...%} للتحكم. احفظ SQL المولد مقروءاً. قد تصعب مراجعة النسب والصحة إذا أخفت ماكرو قصيرة ربطاً وتحويلات خاصة بالهدف. فضّل تجريداً محدداً موثق المعلمات وشكل المخرج وافتراضات المحوّل.

نص القالب المقتبس ليس قيمة SQL حرفية مقتبسة

تتلقى الماكرو تعبير SQL موثوقاً كنص Jinja وتولد علم وجود قيمة. يمرر known_flag('returned_at') النص returned_at ليصبح تعبير معرّف في SQL. أما حذف اقتباس Jinja فيبحث عن متغير قالب. ولا يمثل أيهما ربط معلمات لمدخل غير موثوق. يحتاج إدراج نص اعتباطي قائمة مسموحة واقتباساً أوقيمة حرفية صحيحة للغة الهدف. يقبل المثال تعبيرات المطور فقط، ولا يدعي حماية مولد استعلام عام من الحقن.

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

{% macro known_flag(column_expression) %}
case when {{ column_expression }} is null then 0 else 1 end
{% endmacro %}

select {{ known_flag('returned_at') }} as has_return
from {{ ref('stg_loans') }}

يولّد من حيث المعنى CASE WHEN returned_at IS NULL THEN 0 ELSE 1 END. تُحفظ الماكرو والنموذج في ملفي المشروع المناسبين، ولا يُشغّل هنا محرك Jinja أو SQL.

يختلف المتاح وقت التحليل عن وقت التنفيذ

أثناء تحليل مشروع v1، يكتشف dbt الموارد والرسم دون كائنات نتائج استعلام من التنفيذ. يساعد execute في حراسة منطق يحتاج نتيجة قاعدة. وعندما يكون true، قد تتصل run_query بالمستودع حتى ضمن مسار يركز على الترجمة. لذلك ليست «ترجمت فقط» ضماناً عاماً بلا اتصال. أظهر الحراسة والقيمة البديلة، ولا تجعل الأعمال تعتمد بديل التحليل. يعيد المقطع0 للتحكم وقت التحليل فقط، لا عدّاً مقاساً لعلاقة.

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

{% macro observed_row_count(relation) %}
  {% if not execute %}
    {{ return(0) }}
  {% endif %}
  {% set result = run_query('select count(*) as n from ' ~ relation) %}
  {{ return(result.columns[0].values()[0]) }}
{% endmacro %}

ماكرو استبطان توضيحية فقط. يجب أن تكون relation علاقة محلولة موثوقة؛ قد تصدر SQL وقت التنفيذ ولم تُستخدم هنا.

أظهر المراجع اللازمة أثناء التحليل

قد تصبح ref المخفية في فرع لا يمر به التحليل اعتماداً غير متوقع وقت التنفيذ. استخدم أنماط الإعلان الموثقة إذا لم يظهر المطلوب للرسم. قد تحتوي تعليقات SQL Jinja مولدة، بينما تحذف تعليقات Jinja فلا تخدم الغرض نفسه. وتختلف سياقات الملفات: لا تدعم خصائص YAML في v1 كل ماكرو يدعمها نموذج SQL، ولا تعد CSV قالباً. راجع جدول دعم الملفات للجيل المسمى ولا تنقل سياقاً خاصاً بـv2 إلى v1.

راجع المصدر والعبارة المولدة معاً

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

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

يصبح اسم العمود متغير قالب غير معرّف

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

تستخدم الماكرو نتيجة استعلام أثناء التحليل

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

لا يظهر اعتماد لازم إلا وقت التنفيذ

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

اختبر فهمك

1. هل تربط known_flag("returned_at") قيمة SQL بأمان؟

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

لا. تمرر نص قالب يستخدم كتعبير SQL. المثال مقيد بتعبيرات مطور موثوقة. ميّز نص Jinja ومعرّف القاعدة وقيمة SQL، واستخدم معالجة هدف مراجعة إذا لزم مولد أوسع.

2. لماذا لا تثبت return0 وقت التحليل أن العلاقة خالية؟