المعاملات الافتراضية ونصوص التنفيذ (Default Parameters and Execution Scripts)
Default Parameters and Execution Scripts
شرح تبويب Defaults على قالب مصدر البيانات بقدرتيه: المعاملات (Parameters) الخاصة بالقوالب المعتمدة على Python، ونصوص التنفيذ (Execution Scripts) التي تعمل قبل وبعد كل استعلام على الاتصال.
نظرة عامة
يوفر تبويب Defaults على قالب مصدر البيانات (data source template) قدرتين: المعاملات (parameters) ونصوص التنفيذ (execution scripts). في حين أن نصوص التنفيذ متاحة على جميع أنواع القوالب، فإن المعاملات مُصمَّمة بشكل أساسي للقوالب المعتمدة على Python (فئة Script)، حيث تُعد الآلية الرئيسية لتمرير قيم التهيئة — مثل مفاتيح API، ومسارات الملفات، وتفاصيل الاتصال — إلى نصوص الاستيراد (ingestion) والتوصيف (profiling) وقت التنفيذ.
بالنسبة للقوالب المعتمدة على SQL، تُدار تفاصيل الاتصال عبر سلسلة الاتصال (connection string) وحقول الخادم/قاعدة البيانات في الاتصال نفسه. أما قوالب Python فلا تملك سلسلة اتصال تقليدية، لذا تقوم المعاملات بهذا الدور بدلاً منها.
المعاملات (Parameters)
ما هي المعاملات
معاملات القالب (template parameters) هي قيم تهيئة مسمّاة ومحددة النوع تُعرِّفها مرة واحدة على القالب ثم تضبطها لكل اتصال (per-connection). تعمل كمتغيرات متاحة لنصوص الاستيراد، ونصوص التوصيف، والـ Macros وقت التنفيذ.
على سبيل المثال، قد يُعرِّف قالب Python الخاص بواجهة REST API المعاملات التالية:
| Parameter | Type | Description |
|---|---|---|
| api_base_url | String | The base URL of the API |
| api_key | Secret | Authentication key |
| page_size | Integer | Number of records per request |
| include_archived | Boolean | Whether to include archived records |
| environment | Dropdown | Which environment to connect to (prod, staging, dev) |
عندما ينشئ شخص ما مصدر بيانات باستخدام هذا القالب، يقوم بملء قيم هذه المعاملات في تهيئة الاتصال الخاصة به. تُصبح هذه القيم بعد ذلك متاحة لأي نص Python يُشغِّله القالب.
أنواع المعاملات (Parameter Types)
| النوع | الإدخال | الاستخدام |
|---|---|---|
| String | حقل نصي حر (Free text input) | الروابط (URLs)، مسارات الملفات، أسماء الـ schemas، وأي قيمة نصية. |
| Integer | إدخال رقمي (Numeric input) | أحجام الصفحات (page sizes)، مهلات الانتظار (timeouts)، حدود الصفوف، أرقام المنافذ (port numbers). |
| Boolean | مربع اختيار (Checkbox) | أعلام الميزات (feature flags)، مفاتيح تشغيل/إيقاف. |
| Dropdown | اختيار من خيارات محددة مسبقاً | البيئات (environments)، الأنماط (modes)، والتهيئات ذات الخيارات الثابتة. |
| Secret | حقل نصي مُخفى (Masked text input) | مفاتيح API، كلمات المرور، الرموز (tokens) — تُخزَّن مشفَّرة. |
تُخزَّن معاملات النوع Secret بشكل مشفَّر ولا تُعرض أبداً بنص صريح بعد حفظها. استخدم هذا النوع لأي بيانات اعتماد حساسة.
تعريف المعاملات (Defining Parameters)
لإضافة معامل إلى قالب:
- 1افتح القالب وانتقل إلى Defaults > Parameters.
- 2اضغط على Add لإنشاء معامل جديد.
- 3قم بتهيئة المعامل: Name (الاسم المعروض للمستخدمين، مثل "API Base URL")، وReference Key (المفتاح المستخدم للوصول إلى هذا المعامل في النصوص البرمجية، مثل api_base_url)، وType (أحد الأنواع الخمسة أعلاه)، وHelp Text (وصف يُعرض للمستخدمين عند تهيئة المعامل)، وOptions (لنوع Dropdown فقط، قائمة الخيارات المتاحة).
- 4احفظ (Save).
كيف تُستهلك المعاملات
في نصوص الاستيراد والتوصيف المكتوبة بـ Python، تكون المعاملات متاحة عبر سياق تنفيذ النص البرمجي (script's execution context). عندما يُشغِّل Validatar نصاً برمجياً، يقوم بحقن جميع قيم المعاملات الخاصة بالاتصال الحالي، مما يجعلها متاحة كمتغيرات يمكن للنص البرمجي الرجوع إليها.
المعاملات متاحة أيضاً في نصوص الـ Macros عبر صياغة الاستبدال {{parameterKey}}، بغض النظر عمّا إذا كان القالب معتمداً على SQL أو على Python.
أفضل الممارسات للمعاملات
- استخدم مفاتيح مرجعية وصفية — api_base_url أفضل من param1. تظهر هذه المفاتيح في النصوص البرمجية، لذا فإن وضوحها مهم.
- استخدم دائماً نوع Secret لبيانات الاعتماد — لا تُخزّن مفاتيح API أو كلمات المرور أو الرموز كمعاملات نصية عادية من نوع String.
- قدِّم نصوص مساعدة (help text) — سيرى المستخدمون الذين يهيئون الاتصالات هذه الأوصاف. النص المساعد الواضح يقلل أخطاء الإعداد.
- حدِّد قيماً افتراضية منطقية — بالنسبة للمعاملات الاختيارية، وثِّق السلوك الافتراضي في النص المساعد ليعرف المستخدمون ما الذي سيحدث إن تركوه فارغاً.
- استخدم Dropdown للخيارات المقيَّدة — عندما يكون للمعامل مجموعة ثابتة من القيم الصحيحة، استخدم Dropdown بدلاً من String لمنع الأخطاء الإملائية والتهيئات غير الصحيحة.
نصوص التنفيذ (Execution Scripts)
ما هي نصوص التنفيذ
نصوص التنفيذ (execution scripts) هي نصوص SQL أو Python تعمل تلقائياً قبل و/أو بعد كل استعلام يُنفِّذه Validatar على اتصال يستخدم هذا القالب. توفر طريقة لتهيئة بيئة الجلسة (session environment) قبل بدء أي عمل وتنظيفها بعد الانتهاء.
نصوص ما قبل التنفيذ (Pre-Execution Scripts)
يعمل نص ما قبل التنفيذ (pre-execution script) قبل كل استعلام. من حالات الاستخدام الشائعة:
- ضبط متغيرات الجلسة — تهيئة إعدادات على مستوى الجلسة مثل المنطقة الزمنية (timezone)، أو مهلة الاستعلام (query timeout)، أو تنسيق النتائج.
- تبديل السياقات — ضبط الدور (role) النشط أو المستودع (warehouse) أو الـ schema في المنصات التي تدعم تبديل السياق على مستوى الجلسة.
- تفعيل الميزات — تشغيل ميزات خاصة بالمنصة مطلوبة لاستعلامات Validatar.
مثال — تهيئة جلسة Snowflake:
ALTER SESSION SET TIMEZONE = 'UTC';
ALTER SESSION SET QUERY_TAG = 'validatar';
USE WAREHOUSE VALIDATAR_WH;مثال — مسار البحث (search path) في PostgreSQL:
SET search_path TO public, information_schema;
SET statement_timeout = '300s';نصوص ما بعد التنفيذ (Post-Execution Scripts)
يعمل نص ما بعد التنفيذ (post-execution script) بعد اكتمال الاستعلامات. وهو أقل احتياجاً بشكل عام، لكنه مفيد في:
- إعادة ضبط حالة الجلسة — إعادة متغيرات الجلسة إلى قيمها الافتراضية.
- التسجيل (Logging) — تسجيل أن Validatar قد نفَّذ استعلامات (لأغراض التدقيق).
- التنظيف (Cleanup) — إزالة أي كائنات مؤقتة تم إنشاؤها إن وُجدت.
التجاوز على مستوى الاتصال (Override at Connection Level)
نصوص التنفيذ المعرَّفة على القالب هي إعدادات افتراضية. يمكن للاتصالات الفردية تجاوزها بنصوص خاصة بها. هذا مفيد عندما تحتاج معظم الاتصالات على منصة معينة إلى نفس الإعداد، بينما يحتاج القليل منها إلى متطلبات خاصة (مثل مستودع (warehouse) أو دور (role) مختلف).
يتم تهيئة هذا التجاوز على مستوى إصدار الاتصال (connection version)، وليس على مصدر البيانات أو القالب.
كيف يندمج هذا في الصورة الأكبر
تتعامل المعاملات ونصوص التنفيذ مع مرحلة "الإعداد" (setup) عند العمل مع مصدر بيانات. توفر المعاملات لقوالب Python التهيئة اللازمة للاتصال والاستعلام من الأنظمة الخارجية. أما نصوص التنفيذ فتضمن أن جلسة قاعدة البيانات في الحالة الصحيحة قبل أن يُنفِّذ Validatar عمليات الاستيراد أو التوصيف أو استعلامات الاختبار.
تتدفق هذه الإعدادات الافتراضية إلى كل عملية يقوم بها القالب — وتُستهلك من قِبل نصوص استيراد البيانات الوصفية (metadata ingestion)، وإعدادات التوصيف (profiling)، والـ Macros التي تتناولها المقالات التالية.
للاطلاع على الصورة الشاملة، راجع مقالة Data Source Templates: The Complete Picture.