عقدة استعلام قاعدة البيانات: قراءة بيانات أنظمتك المباشرة أثناء العملية

ما هي؟

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

تدعم العقدة مصدرين للبيانات: قاعدة بيانات التطبيقات (App Database) التي تستخدمها التطبيقات الداخلية منخفضة البرمجة المنشأة في التطبيقات، وقاعدة بيانات سير العمل (Workflow DB) التشغيلية الخاصة بمحرك سير العمل. بعد تنفيذ الاستعلام، تُحفظ نتائجه في متغير مسمى تختاره، مثل {{db_rows}}، وتستطيع كل عقدة لاحقة قراءة البيانات.

في السيناريوهات المتقدمة، تثبّت ميزة المُشغّلات التفاعلية (Reactive Triggers) الاختيارية مستمعًا للتغييرات في جدول المصدر. وعند إدراج صف في ذلك الجدول أو تحديثه أو حذفه، يُخطر المستمع محرك سير العمل فورًا لتستجيب العُقد اللاحقة من دون انتظار دورة استقصاء.

أهميتها وفوائدها الرئيسية

• قرارات مبنية على بيانات حقيقية، لا على مدخلات النموذج وحدها. قبل توجيه اعتماد، يستطيع سير العمل التحقق من الميزانية المتبقية لمقدم الطلب، أو إدراج المورد ضمن القائمة المعتمدة، أو استمرار صلاحية العقد، باستخدام سجلات مباشرة لا لقطات قديمة.
• إلغاء عمليات البحث اليدوية. تصبح العمليات التي كانت تتطلب من المعتمد فتح نظام آخر والبحث عن سجل ثم العودة للاعتماد مؤتمتة بالكامل؛ إذ يحدث البحث داخل سير العمل.
• توجيه ديناميكي مدعوم بالبيانات المباشرة. اجمع بين عقدة استعلام قاعدة البيانات وعقدة شرط للتفرع تلقائيًا: إذا أظهر السجل status = approved يُسلك مسار، وإذا أظهر status = pending review يُسلك آخر، من دون تدخل بشري.
• تغذية تحليل الذكاء الاصطناعي اللاحق. يمكن تمرير مجموعة نتائج عقدة استعلام قاعدة البيانات مباشرة إلى عقدة وكيل ذكاء اصطناعي، ليحلل السجلات ويعيد قرارًا منظمًا.
• استجابة فورية لتغير البيانات باستخدام المُشغّلات التفاعلية. يعني هذا الخيار أن سير العمل يستطيع بدء الاستجابة لحظة تغير صف في نظام المصدر؛ مثل اعتماد يبدأ عند INSERT في قاعدة البيانات، أو مهام تُلغى عند DELETE، من دون تأخير الاستقصاء المجدول.
• إخراج مسمى لتسهيل المراجع اللاحقة. تختار اسم المتغير، مثل db_rows أو active_contracts، فتستخدم العُقد اللاحقة وسمًا مقروءًا وذا معنى مثل {{active_contracts}} بدلًا من معرّف غامض.

قبل أن تبدأ

• تتاح عقدة استعلام قاعدة البيانات لمصممي سير العمل. ويتطلب إعداد ميزة المُشغّلات التفاعلية في علامة المُشغّلات صلاحية المشرف، لأنها تثبّت مستمعًا على مستوى قاعدة البيانات في جدول المصدر.
• يجب أن تعرف قاعدة البيانات المراد الاستعلام منها، سواء قاعدة بيانات التطبيقات أو قاعدة بيانات سير العمل، وأن تكون لديك معرفة أساسية باستعلامات SQL من نوع SELECT.
• الحد الافتراضي في الحد الأقصى للصفوف (Max Rows) هو 1000، ويمكن رفعه إلى 10,000. قد تؤثر النتائج الكبيرة جدًا في الأداء؛ لذلك صمّم الاستعلامات بشروط WHERE وقيم LIMIT مناسبة.
• الصلاحية المطلوبة: إدارة مسارات سير العمل (Manage Workflows).

مكان العثور عليها: في لوحة العناصر (Elements) داخل المصمم المرئي، انتقل إلى علامة المنطق (LOGIC)، واسحب عقدة استعلام قاعدة البيانات إلى اللوحة.

طريقة الاستخدام خطوة بخطوة

الخطوة 1 — وضع العقدة

1. افتح سير عمل في المصمم المرئي.
2. انقر علامة المنطق في لوحة العناصر إلى اليسار.
3. اسحب عقدة استعلام قاعدة البيانات إلى موضع تنفيذ البحث في اللوحة. ضعها قبل أي عقدة ستستخدم البيانات المستردة.
4. صِلها بالعقدة السابقة وبالعقدة التي ينبغي أن تستلم نتائج الاستعلام.
5. انقر عقدة استعلام قاعدة البيانات نقرًا مزدوجًا لفتح مربع إعداد عقدة استعلام قاعدة البيانات.

الخطوة 2 — إعداد الاستعلام في علامة الاستعلام

تظهر علامة الاستعلام (Query) أولًا.

6. الاسم (Name)، اختياري: أدخل اسم عرض قصيرًا للعقدة، مثل «تحميل العقود النشطة» أو «التحقق من رصيد الميزانية». يظهر الاسم في تسمية العقدة على اللوحة وفي سجل الإصدارات.

7. الوصف (Description)، اختياري: صِف بإيجاز ما يسترده الاستعلام، مثل «يعيد كل أوامر الشراء المفتوحة لقسم مقدم الطلب». يساعد ذلك الزملاء في صيانة سير العمل.

8. مصدر البيانات (Datasource): اختر قاعدة البيانات المطلوب الاستعلام منها.

   • قاعدة بيانات التطبيقات (Applications Database) — قاعدة التطبيقات التي تستخدمها التطبيقات الداخلية المنشأة في التطبيقات؛ وهذه هي التسمية في القائمة الظاهرة. استخدمها للبحث في بيانات التطبيقات.
   • قاعدة بيانات سير العمل (Workflow DB) — البيانات التشغيلية الخاصة بمحرك سير العمل، مثل المثيلات والمهام والإجراءات. استخدمها في سيناريوهات فحص سير العمل نفسه.

   لا تتاح المُشغّلات التفاعلية، الموضحة في الخطوة 3، إلا لمصدر قاعدة بيانات التطبيقات.

9. استعلام SQL: اكتب عبارة SELECT في منطقة الشفرة. يقبل الحقل SQL القياسية. أمثلة:

   • SELECT * FROM public.purchase_orders WHERE status = 'pending' LIMIT 100
   • SELECT budget_remaining FROM public.budgets WHERE department = '{{form_department}}'
   • SELECT id, vendor_name, status FROM public.vendors WHERE approved = true ORDER BY vendor_name

   استخدام متغيرات سير العمل في الاستعلامات: يمكنك تضمين علامات دمج من العُقد السابقة مباشرة في SQL، مثل WHERE employee_id = '{{form_employee_id}}'. تستبدل المنصة القيمة عند التشغيل قبل تنفيذ الاستعلام. هذه قدرة قوية، لكن استخدمها بحذر مع مدخلات موثوقة جرى التحقق منها فقط.

10. اسم متغير الإخراج (Output Variable Name): أدخل الاسم الذي ستستخدمه للإشارة إلى النتائج في العُقد اللاحقة. القيمة الافتراضية db_rows. اختر اسمًا يوضح البيانات، مثل active_contracts أو budget_info أو pending_orders.

    • يعرض نص المساعدة أسفل الحقل علامة الدمج الدقيقة التي ستُنشأ، مثل {{db_rows}} أو {{active_contracts}}.

11. الحد الأقصى للصفوف (Max Rows): حدد أكبر عدد من الصفوف المعادة. القيمة الافتراضية 1000 والحد الأقصى 10000. اضبط قيمة أقل إذا كنت تعرف أن مجموعة النتائج صغيرة لتحسين الأداء. واستخدم LIMIT في SQL أيضًا لتوفير تحكم مزدوج.

الخطوة 3 — إعداد المُشغّلات التفاعلية اختياريًا للمشرف

هذه الخطوة اختيارية وتتطلب صلاحية المشرف.

12. انقر علامة المُشغّلات (Triggers).
13. إذا اخترت قاعدة بيانات سير العمل مصدرًا، يظهر تنبيه بأن المُشغّلات متاحة لقاعدة بيانات التطبيقات فقط. ارجع إلى علامة الاستعلام واختر قاعدة بيانات التطبيقات إذا كنت تحتاج إليها.
14. حدّد مربع تمكين المُشغّلات التفاعلية (Enable Reactive Triggers) لتفعيل الاستماع إلى تغييرات جدول المصدر. عند التمكين، يثبّت محرك سير العمل مستمعًا يطلق المعالجة اللاحقة تلقائيًا عند وقوع الأحداث المحددة.
15. تحت التشغيل عند (Trigger on)، حدد أنواع الأحداث المطلوبة:
    • INSERT — «تشغيل الخطوات اللاحقة عند إضافة صف جديد». استخدمه لبدء سير عمل أو تقديمه عند إنشاء سجل جديد في نظام المصدر.
    • UPDATE — «إعادة تشغيل الخطوات اللاحقة عند تغير صف». استخدمه لإعادة تقييم التوجيه عند تعديل سجل قائم.
    • DELETE — «إلغاء المهام اللاحقة للصفوف المحذوفة». استخدمه لتنظيف مهام سير العمل عند حذف سجل المصدر.
16. عمود المفتاح (Key Column): أدخل اسم العمود الذي يعرّف كل صف تعريفًا فريدًا، ويكون عادة id. يستخدمه المستمع لمطابقة الأحداث الواردة مع مثيل سير العمل الصحيح.
    • يُكتشف حقل الجدول (Table) أدناه تلقائيًا من عبارة FROM في استعلام SQL ويظهر للتأكيد.

الخطوة 4 — الحفظ والاختبار

17. انقر حفظ (Save) في تذييل مربع الحوار. يُغلق المربع وتعرض العقدة على اللوحة الاسم الذي اخترته ورمز قاعدة بيانات.
18. احفظ سير العمل كاملًا باستخدام Ctrl+S أو زر حفظ في شريط الأدوات.
19. للتحقق من عمل العقدة، شغّل مثيلًا تجريبيًا؛ راجع تشغيل سير عمل، وافحص عرض تفاصيل سير العمل للتأكد من أن متغير {{db_rows}} يحتوي الصفوف المتوقعة.

شرح الخيارات والإعدادات

علامة الاستعلام

علامة المُشغّلات لقاعدة بيانات التطبيقات فقط

بنية متغير الإخراج

متغير الإخراج مصفوفة من كائنات الصفوف. يحتوي كل كائن على مفتاح لكل عمود يعيده استعلام SQL. مثلًا، إذا اختار الاستعلام id وvendor_name وstatus، يحتوي المتغير {{active_vendors}} على:

[
  { "id": 1, "vendor_name": "Acme Corp", "status": "approved" },
  { "id": 2, "vendor_name": "Beta Ltd",  "status": "pending" }
]

يمكن للعُقد اللاحقة، مثل الشرط ووكيل الذكاء الاصطناعي ونص البريد، استخدام المصفوفة كاملة، أو استخدام الحقول الفردية بترميز النقطة عندما تدعم المنصة ذلك.

نصائح وأفضل الممارسات

• اجعل استعلامات SQL محددة. اختر الأعمدة التي تحتاج إليها فقط، وتجنب SELECT * في مسارات الإنتاج. الاستعلامات المحددة أسرع والمتغير الناتج أسهل استخدامًا لاحقًا.
• أضف عبارة LIMIT في SQL نفسها إلى جانب ضبط الحد الأقصى للصفوف. يمنع الحدان المستقلان مجموعات النتائج الكبيرة بطريق الخطأ.
• استخدم شروط WHERE مع متغيرات سير العمل لتصفية السجل الصحيح. بدلًا من إعادة 10,000 صف ثم تصفيتها في عقدة شرط، اكتب WHERE employee_id = '{{form_employee_id}}' وأعد السجل ذي الصلة وحده.
• سمِّ متغير الإخراج حسب محتواه. تكون {{active_contracts}} أسهل قراءة في نصوص البريد والشروط اللاحقة من {{db_rows}} الافتراضية.
• ضع عقدة استعلام قاعدة البيانات قبل أي عقدة تحتاج إلى بياناتها. لا تتاح في مرحلة سابقة المتغيرات الناتجة من عُقد تعمل لاحقًا في الرسم البياني.
• لا تمكّن المُشغّلات التفاعلية إلا عند الحاجة الحقيقية إلى استجابة فورية. يثبّت كل مُشغّل مستمعًا في جدول المصدر. أبقِها متوقفة لمسارات سير العمل التي تحتمل الجدولة أو البدء اليدوي.
• اختبر أولًا باستعلام LIMIT 1. تحقق من صياغة الاستعلام وبنية متغير الإخراج قبل توسيع مجموعة النتائج.
• ادمجها مع عقدة وكيل ذكاء اصطناعي. مرر نتيجة استعلام قاعدة البيانات إلى وكيل للحصول على تحليل ذكي، مثل «لخّص أوامر الشراء هذه وحدد أيها يتجاوز السياسة».

الأسئلة الشائعة

س: هل يمكنني تحديث السجلات أو حذفها بعقدة استعلام قاعدة البيانات؟

لا. تنفذ العقدة استعلامات SELECT للقراءة فقط. لتعديل البيانات، استخدم تكاملًا مخصصًا أو عقدة Webhook لاستدعاء API خارجية تنفذ الكتابة.

س: ماذا يحدث إذا لم يُعد الاستعلام أي صفوف؟

يُضبط متغير الإخراج على مصفوفة فارغة []. يجب أن تتعامل عُقد الشرط اللاحقة مع هذه الحالة، كالتفرع إلى مسار «لم يُعثر على بيانات» عندما تكون المصفوفة فارغة باستخدام عامل «فارغ» على المتغير.

س: هل يمكنني استخدام علامة دمج داخل عبارة SQL WHERE؟

نعم. مثلًا: SELECT * FROM budgets WHERE department = '{{form_department}}'. تستبدل المنصة قيمة المتغير قبل تنفيذ الاستعلام. تحقق دائمًا من مدخلات النموذج ونقّحها في مرحلة سابقة لمنع سلوك استعلام غير متوقع.

س: كم صفًا يمكنني استرداده؟

الحد الأقصى 10,000 صف. اضبط الحد الأقصى للصفوف في علامة الاستعلام، وأضف عبارة LIMIT في SQL للحماية المزدوجة. يُفضل التعامل مع النتائج الكبيرة بشروط WHERE أدق بدلًا من زيادة الحد.

س: ما الذي تفعله المُشغّلات التفاعلية بالضبط؟

عند تمكينها، تثبّت المنصة آلية إشعار خفيفة في جدول قاعدة بيانات المصدر. كلما وقع INSERT أو UPDATE أو DELETE مطابق، تُخطر المنصة فورًا، ويمكنها إعادة تشغيل خطوات سير العمل المعنية أو تقديمها من دون استقصاء مجدول. وبذلك يستجيب سير العمل خلال ثوان بدلًا من دقائق لتغير بيانات المصدر.

س: هل يمكنني إضافة أكثر من عقدة استعلام قاعدة بيانات إلى سير العمل نفسه؟

نعم. تنفذ كل عقدة استعلامًا مستقلًا على مصدرها وتحفظ النتائج في متغير إخراج مستقل. استخدم أسماء مميزة لتتمكن العُقد اللاحقة من الإشارة إلى مجموعة البيانات الصحيحة.

س: يعمل الاستعلام لكن متغير الإخراج فارغ. ما الذي أراجعه؟

تحقق من: 1) كتابة أسماء الجدول والأعمدة بصورة صحيحة ومطابقتها مخطط قاعدة البيانات بدقة؛ إذ تراعي PostgreSQL حالة الأحرف. 2) عدم استبعاد شرط WHERE كل الصفوف بطريق الخطأ؛ جرّب إزالته مؤقتًا لترى إن كانت الصفوف تعود. 3) صحة مصدر البيانات، قاعدة التطبيقات أو قاعدة سير العمل. 4) عدم ضبط الحد الأقصى للصفوف على صفر.