الماكرو (Macros)

نظرة عامة

الـ Macros هي أنماط SQL أو نصوص برمجية قابلة لإعادة الاستخدام وذات معاملات (parameterized)، تُعرَّف على قالب مصدر بيانات (data source template) وتكون متاحة لأي شخص ينشئ اختبارات على مصادر البيانات التي تستخدم ذلك القالب. بدلاً من كتابة نفس نمط SQL من الصفر في كل مرة تحتاج فيها إلى فحص عدد الصفوف (row count) أو استعلام نسبة القيم الفارغة (null percentage)، تُعرِّف النمط مرة واحدة كـ Macro مع عناصر نائبة (placeholders) للأجزاء المتغيرة — اسم الـ schema، اسم الجدول (table)، اسم العمود (column) — ويقوم المستخدمون بملء هذه القيم عبر قوائم منسدلة (dropdowns) بديهية ومرتبطة بالبيانات الوصفية (metadata) أثناء إنشاء الاختبار.

تخدم الـ Macros غرضين رئيسيين:

1. 1Test Data Set macros — توفر أنماط استعلام قابلة لإعادة الاستخدام يختارها المستخدمون كمصادر لمجموعة البيانات (data set) عند إنشاء الاختبارات.
2. 2Standard Test Action macros — توفر نصوصاً قابلة لإعادة الاستخدام تُنفَّذ كإجراءات لاحقة للاختبار (post-test actions)، مثل استعلامات المعالجة (remediation) أو تسجيل التدقيق (audit logging).

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

كيف تظهر الـ Macros عند إنشاء الاختبار

هذه هي القيمة الأساسية للـ Macros — التجربة التي توفرها للمستخدمين عند بناء الاختبارات.

عندما ينشئ المستخدم أو يعدّل اختباراً قياسياً (standard test) ويقوم بتهيئة مجموعة بيانات (data set)، يمكنه اختيار Macro كنوع مصدر لمجموعة البيانات بدلاً من كتابة SQL مخصص. يظهر عندها قائمة منسدلة بجميع الـ Macros المتاحة على القالب المرتبط بمصدر بيانات الاختبار.

بعد اختيار Macro، يرى المستخدم معاملات (parameters) الماكرو. يظهر كل معامل كحقل إدخال — وهنا يظهر تأثير الربط بالبيانات الوصفية:

• معامل من النوع Schema يظهر كقائمة منسدلة مملوءة بجميع الـ schemas المستخرجة من البيانات الوصفية المستوردة (ingested metadata) الخاصة بمصدر البيانات.
• معامل من النوع Table يظهر كقائمة منسدلة بالجداول، مُصفّاة تلقائياً حسب الـ schema المختار.
• معامل من النوع Column يظهر كقائمة منسدلة بالأعمدة، مُصفّاة تلقائياً حسب الجدول المختار.
• معامل من النوع Dropdown يعرض الخيارات المحددة مسبقاً المعرَّفة على الماكرو.
• معامل من النوع Free Text يوفر حقل إدخال نصي عادي.

هذه الواجهة المدفوعة بالبيانات الوصفية تعني أن المستخدمين لا يحتاجون إلى معرفة أسماء الـ schemas أو الجداول أو الأعمدة بدقة — بل يختارون مما هو موجود فعلياً في مصدر البيانات، دون أخطاء إملائية أو تخمين.

بمجرد ملء جميع المعاملات، يقوم Validatar بعرض نص الماكرو (script) بعد استبدال قيم المعاملات فيه، مما يمنح المستخدم معاينة للـ SQL أو النص البرمجي الفعلي الذي سيتم تنفيذه.

صياغة الماكرو (Macro Syntax)

تستخدم نصوص الـ Macros عناصر نائبة بأقواس مزدوجة (double-brace placeholders) تشير إلى مفاتيح المعاملات (parameter keys):

SELECT COUNT(*) AS row_count
FROM {{schema_name}}.{{table_name}}
WHERE {{column_name}} IS NULL;

عند التنفيذ، يستبدل Validatar كل {{parameterKey}} بالقيمة التي اختارها المستخدم:

SELECT COUNT(*) AS row_count
FROM sales.orders
WHERE customer_id IS NULL;

الاستبدال هو عملية استبدال نصي مباشر. أما فواصل المعرِّفات (identifier delimiters) المحددة على القالب فتُطبَّق بشكل منفصل عندما يقوم Validatar ببناء الاستعلام الكامل — لذا لا حاجة لإضافة علامات اقتباس في نص الماكرو نفسه.

أنواع المعاملات (Parameter Types)

لكل معامل في الماكرو نوع يحدد كيفية عرضه للمستخدم والقيم المتاحة له:

المعاملات الهرمية (Hierarchical Parameters)

يمكن أن تكون بين المعاملات علاقات أب-ابن (parent-child) تُنشئ عوامل تصفية متسلسلة (cascading filters). وهذا من أكثر جوانب تصميم معاملات الماكرو فائدة:

• تعريف معامل من النوع Schema.
• تعريف معامل من النوع Table وجعل معامل Schema أباً له.
• تعريف معامل من النوع Column وجعل معامل Table أباً له.

عندما يختار المستخدم schema، تُصفَّى قائمة الجداول تلقائياً لعرض جداول ذلك الـ schema فقط. وعندما يختار جدولاً، تُصفَّى قائمة الأعمدة لعرض أعمدة ذلك الجدول فقط. هذا السلوك المتسلسل تلقائي — يتولى Validatar تطبيقه استناداً إلى علاقة الأب-الابن التي تُعرِّفها.

مثال على تسلسل هرمي:

Schema Parameter: "schema_name" (type: Schema)
  └─ Table Parameter: "table_name" (type: Table, parent: schema_name)
       └─ Column Parameter: "column_name" (type: Column, parent: table_name)

إنشاء ماكرو (Creating a Macro)

انتقل إلى تبويب Macros في القالب لرؤية جميع الـ Macros المعرَّفة عليه. اختر New لإنشاء ماكرو جديد، أو افتح ماكرو موجوداً لتعديله.

حقول الماكرو (Macro Fields)

تعريف المعاملات (Defining Parameters)

على صفحة تفاصيل الماكرو، أضف المعاملات في قسم Parameters:

1. 1اضغط على Add Parameter.
2. 2حدد الـ Name (التسمية المعروضة)، والـ Reference Key (المستخدم في العناصر النائبة {{key}})، والـ Type.
3. 3بالنسبة للمعاملات الهرمية، حدد Parent وهو المعامل الذي يعتمد عليه هذا المعامل.
4. 4بالنسبة لمعاملات النوع Dropdown، عرِّف الخيارات المتاحة (Options).
5. 5أضف Help Text لإرشاد المستخدمين عند ملء القيمة.
6. 6حدد Sequence للتحكم في ترتيب ظهور المعاملات في الواجهة.

التحقق من النص البرمجي (Script Validation)

عند حفظ الماكرو، يتحقق Validatar من النص البرمجي مقابل المعاملات المعرَّفة:

• يجب أن يقابل كل {{parameterKey}} في النص البرمجي معاملاً معرَّفاً.
• يجب الإشارة إلى كل معامل معرَّف داخل النص البرمجي (المعاملات غير المستخدمة تُولّد تحذيراً).
• يجب أن تكون مفاتيح مراجع المعاملات (reference keys) فريدة ضمن الماكرو الواحد.

أنواع الـ Macros بالتفصيل

Test Data Set Macros

عندما يختار المستخدم ماكرو من نوع Test Data Set كمصدر لمجموعة بيانات الاختبار، يُنتج الماكرو استعلاماً يُعيد بيانات الاختبار أو بيانات التحكم (control data). يحدد نوع مجموعة البيانات (data set type) كيفية تفسير النتائج:

الاختيار بين SingleValue وKeyValueList يحدد ما إذا كان الماكرو يُنتج نتيجة عددية مفردة (scalar)، كعدد الصفوف مثلاً، أو مجموعة نتائج (result set)، كقائمة أسماء أعمدة مع عدد القيم الفارغة لكل منها.

Standard Test Action Macros

تُستخدم ماكرو الإجراءات (action macros) كخطوات ضمن إعدادات إجراءات الاختبار. بعد تنفيذ الاختبار وتحقق شرط معين (مثل فشل الاختبار)، يمكن لمُشغِّل إجراء (action trigger) أن يُطلق خطوة "Run Macro" تُنفِّذ نص الماكرو.

من حالات الاستخدام الشائعة لماكرو الإجراءات:

• استعلامات المعالجة (Remediation queries) — لإصلاح مشكلات بيانات معروفة تلقائياً عند اكتشافها.
• تسجيل التدقيق (Audit logging) — لكتابة نتائج الاختبار في جدول تدقيق.
• الإشعارات (Notifications) — لإدراج سجلات في قائمة انتظار الإشعارات.
• التنفيذ المتسلسل (Cascading execution) — لتشغيل عمليات لاحقة استناداً إلى نتائج الاختبار.

ماكرو الإجراءات لها نفس بنية المعاملات والنصوص البرمجية الخاصة بماكرو مجموعات البيانات. تُملأ المعاملات عند تهيئة خطوة الإجراء على الاختبار.

مثال: بناء ماكرو "Null Percentage"

لنستعرض خطوات إنشاء ماكرو شائع خطوة بخطوة.

1. تعريف الماكرو

• Name: Null Percentage Check
• Reference Key: null_percentage_check
• Macro Type: Test Data Set
• Priority: 1

2. تعريف المعاملات

3. كتابة النص البرمجي

SELECT
    CAST(
        COUNT(CASE WHEN {{column_name}} IS NULL THEN 1 END) * 100.0
        / NULLIF(COUNT(*), 0)
    AS DECIMAL(10, 2)) AS null_percentage
FROM {{schema_name}}.{{table_name}};

4. اختباره

أنشئ اختباراً قياسياً، اختر "Macro" كنوع مصدر مجموعة البيانات، اختر "Null Percentage Check"، ثم اختر schema ثم table ثم column من القوائم المنسدلة، وتحقق من أن نص SQL المُعاين صحيح.

الأولوية وترتيب التنفيذ (Priority and Execution Order)

عند تعريف عدة Macros على قالب واحد، يحدد حقل Priority ترتيب ظهورها في قائمة الاختيار المنسدلة وترتيب تنفيذها عند استخدامها معاً ضمن إعدادات الإجراءات. الأرقام الأقل في الأولوية تظهر وتُنفَّذ أولاً.

استخدم الأولوية لتجميع الـ Macros المرتبطة منطقياً — على سبيل المثال، جميع ماكرو عدّ الصفوف بأولوية 1، وجميع ماكرو فحص القيم الفارغة بأولوية 2، وجميع ماكرو التوزيع بأولوية 3.

أفضل الممارسات

• أطلق أسماء وصفية على الـ Macros — يرى المستخدمون الاسم في قائمة منسدلة أثناء إنشاء الاختبار. "Row Count by Table" أفضل من "Macro 1".
• استخدم المعاملات الهرمية — سلوك القوائم المنسدلة المتسلسلة يحسّن تجربة المستخدم بشكل كبير ويقلل الأخطاء.
• اجعل النصوص البرمجية مركّزة — يجب أن يقوم كل ماكرو بمهمة واحدة بشكل جيد. إذا كان نمط الاستعلام معقداً، فكّر في تقسيمه إلى عدة Macros بدلاً من ماكرو واحد يحتوي معاملات كثيرة.
• أضف نصوص مساعدة مفيدة — يرشد Help Text المستخدمين غير المطّلعين على غرض الماكرو أو معنى كل معامل.
• اختبر ببيانات حقيقية — أنشئ اختباراً باستخدام الماكرو على مصدر بيانات فعلي للتحقق من أن SQL المُولَّد يعمل بشكل صحيح على المنصة المستهدفة.
• خذ اختلافات المنصات بعين الاعتبار — إذا كنت تدعم عدة منصات، فقد تحتاج إلى Macros خاصة بكل منصة. ماكرو دالة تاريخ خاصة بـ SQL Server لن تعمل على Snowflake؛ ولكل قالب مجموعة Macros خاصة به، لذا تُحل هذه المسألة تلقائياً من خلال استخدام قوالب منفصلة.

كيف يندمج هذا في الصورة الأكبر

الـ Macros هي الجسر بين معرفة القالب على مستوى المنصة (platform-level knowledge) واستخدامها اليومي في إنشاء الاختبارات. فهي تُرمّز أنماط الاستعلام الشائعة بحيث لا يحتاج المستخدمون إلى أن يكونوا خبراء في SQL لإنشاء اختبارات جودة بيانات فعّالة. القوائم المنسدلة للمعاملات المرتبطة بالبيانات الوصفية تربط الـ Macros بكتالوج البيانات الذي تُنشئه عملية استيراد البيانات الوصفية (metadata ingestion)، مما يخلق سير عمل سلساً من تهيئة مصدر البيانات وحتى تنفيذ الاختبار.

بالنسبة لماكرو الإجراءات (action macros) على وجه الخصوص، فهي توسّع قيمة الـ Macros إلى ما هو أبعد من تعريف الاختبار لتصل إلى الاستجابة الآلية — لتحويل نتائج الاختبار إلى إجراءات.