> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/alblwkat-alwzyfyh/blocks-reference/input-output/communication/sql-db-operations.md).

# SQL-DB Operations

هذا الـ function block يتيح لك أداء مهام SQL الشائعة (INSERT, QUERY, UPDATE, DELETE, EXECUTE) على قاعدة بيانات متصلة. يوفر واجهة بسيطة لاختيار العملية المطلوبة، إدخال اسم الجدول عند الحاجة، وتمرير المدخلات المطلوبة عبر المقابس (sockets). تُنفذ العمليات في الخلفية حتى تبقى الواجهة سريعة الاستجابة.

## 📥 Inputs (sockets)

اعتمادًا على العملية المحددة، يعرض البلوك مقابس إدخال مختلفة. كل اسم مذكور أدناه هو مقبس يمكنك توصيله ببلوكات أخرى.

مقابس شائعة تستخدم في كل الطرق

* `Enable`\
  يجب أن تكون محددة على true لتشغيل العملية المختارة.
* `DB Client`\
  مرجع عميل قاعدة البيانات المقدم بواسطة بلوك اتصال منفصل (راجع "Tips and Tricks").

مقابس خاصة بكل طريقة

* INSERT
  * `JSON Data`\
    البيانات المراد إدراجها في الجدول المختار (JSON/dictionary).
* QUERY
  * `Query String`\
    سلسلة SQL SELECT أو أي استعلام آخر لتشغيله.
* UPDATE
  * `JSON Data`\
    قيم التحديث (JSON/dictionary).
  * `JSON Data(Where Conditions)`\
    شروط WHERE لتحديد الصفوف التي سيتم تحديثها.
* DELETE
  * `JSON Data(Where Conditions)`\
    شروط WHERE لتحديد الصفوف التي سيتم حذفها.
* EXECUTE
  * `Statement String`\
    جملة SQL خام للتنفيذ (استخدمها بحذر).

ملاحظة: سيُظهر البلوك أو يخفي حقل إدخال `Table Name` اعتمادًا على العملية المختارة.

## 📤 Outputs (sockets)

* `Output Data`\
  يُرجع نتيجة العملية (على سبيل المثال صفوف الاستعلام، معلومات الصفوف المتأثرة، أو بيانات خاصة بالعملية).
* `Success?`\
  قيمة منطقية تشير إلى ما إذا كانت العملية قد اكتملت بنجاح.

## 🕹️ Controls (widgets)

* `Select SQL Operation`\
  قائمة منسدلة لاختيار واحدة من: INSERT / QUERY / UPDATE / DELETE / EXECUTE. تغيير الخيار يحدّث مقابس الإدخال المتاحة لتطابق العملية المختارة.
* `Table Name`\
  حقل نصي لاسم الجدول المستهدف. يُخفي تلقائيًا عندما لا يكون مطلوبًا (مثلاً عند استخدام `EXECUTE`).

## ⚙️ آلية التشغيل (Running mechanism)

* يعمل البلوك فقط عندما يستقبل مقبس `Enable` قيمة true.
* يتطلب وجود مقبس `DB Client` صالحًا موصولًا (عادةً يتم توفيره بواسطة بلوك اتصال بقاعدة البيانات).
* عند التشغيل، ينفذ البلوك العملية المختارة في الخلفية ويُرجع `Output Data` و`Success?` عند الانتهاء.
* أي مشاكل (مثل مدخلات غير صالحة، عميل مفقود، JSON غير صالح، أو أخطاء SQL) يتم الإبلاغ عنها في منطقة الرسائل/السجل داخل البلوك.

## ✨ الميزات الرئيسية

* مقابس ديناميكية تتكيف مع العملية المختارة لواجهة أنظف.
* تنفيذ في الخلفية للحفاظ على استجابة الواجهة أثناء نداءات قاعدة البيانات طويلة الأمد.
* مدخلات JSON بسيطة لـ INSERT و UPDATE لتسهيل تغذية البيانات الجدولية.
* مؤشر نجاح واضح وبيانات نتيجة مرجعة للمعالجة اللاحقة.

## 📝 تعليمات الاستخدام

1. وفّر عميل قاعدة البيانات إلى مقبس `DB Client` (راجع Tips and Tricks).
2. اختر العملية المطلوبة عبر `Select SQL Operation`.
3. إذا لزم الأمر، أدخل اسم الجدول في `Table Name`.
4. وصل مقابس البيانات المطلوبة للعملية المختارة (مثلاً `JSON Data` للـ INSERT).
5. أرسل إشارة true إلى `Enable` لتشغيل العملية.
6. افحص `Output Data` و`Success?` لمتابعة المعالجة في السيناريو الخاص بك.

## 💡 Tips and Tricks

* لإنشاء الاتصالات، استخدم `SQL-DB Client Connect` لإنشاء وتزويد مقبس `DB Client`.
* حضّر بيانات الإدراج/التحديث باستخدام `Data to JSON` حتى تتطابق صيغة البيانات مع المدخلات المتوقعة (JSON/dictionary).
* إذا كنت تبني جمل SQL ديناميكيًا، استخدم `String Input` أو `String Merge` لتكوين الاستعلام أو الجملة قبل تمريرها إلى `Query String` أو `Statement String`.
* احفظ أو شارك عملاء DB أو النتائج الشائعة الاستخدام باستخدام `Data Write Local` / `Data Read Local` أو النسخ العالمية للوصول عبر السيناريوهات.
* استخدم `Parse Data Dictionary` لاستخراج الحقول من صفوف الاستعلام المرجعة وتمريرها إلى بلوكات أخرى.
* استخدم `Debug Input` لتسجيل وفحص البيانات الوسيطة الداخلة إلى البلوك عند استكشاف الأخطاء وإصلاحها.
* لحفظ نتائج الاستعلام لاستخدام لاحق، اجمع مع `CSV Export` لكتابة `Output Data` إلى ملف.

## 🛠️ استكشاف الأخطاء وإصلاحها (Troubleshooting)

* `DB Client` غير صالح\
  تأكد من توصيل عميل قاعدة بيانات صحيح (استخدم `SQL-DB Client Connect`). سيعرض البلوك خطأ إذا كان العميل مفقودًا أو غير صالح.
* العملية تعيد خطأ\
  راجع حمولة JSON أو سلسلة SQL المقدمة للتأكد من صحتها. استخدم `Debug Input` أو `Parse Data Dictionary` لفحص المدخلات والنتائج.
* لا يوجد استجابة أو انتظار طويل\
  البلوك ينفذ العمليات في الخلفية، لكن الاستعلامات الطويلة قد تستغرق وقتًا. اجعل الاستعلامات أصغر أو تحقق من أن قاعدة البيانات متاحة وتستجيب.
* JSON غير صالح\
  عند استخدام مدخلات JSON، تحقق من صحة JSON باستخدام `Data to JSON` أو افحص المحتوى باستخدام بلوكات التسجيل قبل التوصيل.

إذا استمرت المشاكل، فراجع مخرجات الرسائل/السجل داخل البلوك للعثور على تلميحات وضبط المدخلات أو إعدادات قاعدة البيانات وفقًا لذلك.