Elasticsearch / الأساسي: عقود المستندات والاستعلامات / الدرس 5

الإدخال الجماعي ومحاسبة العناصر

اقرأ NDJSON بوصفه تسلسلاً من إجراءات الإدخال، وعالج النجاح الجزئي من دون تكرار العمل المقبول.

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

في هذه الصفحة

أهداف الدرس

اشرح إجراءات Bulk من أنواع index وcreate وupdate وdelete.
صنّف أخطاء كل عنصر، وصمم إعادة إرسال محدودة.

الجمع تسلسل مؤطّر لا مصفوفة JSON

تقبل Bulk API صيغة JSON المفصولة بأسطر. يحدد كل سطر لبيانات تعريف الإجراء هل يلزمه سطر مصدر تالٍ. يحتاج index وcreate إلى سطر مستند، ويحتاج update إلى جسم تحديث، بينما لا يتبعه مصدر في delete. يجب أن ينتهي آخر سطر بمحرف سطر جديد، وألا يوزع تنسيق JSON المحسّن للقراءة السجل الواحد على عدة أسطر مادية. لا تتغير قواعد التأطير هذه إذا احتوت المستندات كائنات متداخلة. ينتج مسلسل مصفوفة JSON عام بروتوكولاً مختلفاً قد يفشل، رغم أن محلل JSON مستقلاً يعد مخرجاته صحيحة. اختبر تأطير الطلب منفصلاً عن تعيين الحقول.

اختر الاستبدال أو الإنشاء فقط

تحتوي الحمولة الاصطناعية إجراءَي create يستهدفان فهرساً تعليمياً ذا اسم إصدار. عند إعادة إرسالها بالمعرّفات نفسها، ينبغي أن تتعارض العناصر الموجودة بدلاً من استبدالها بصمت. أما index فيسمح بالاستبدال، وهو ما قد يناسب تمثيلاً للحالة الحالية، لكنه قد يضر أحداث اقتناء يفترض بقاؤها ثابتة. حدّد معنى التكرار قبل اختيار الإجراء. وتدعم تدفقات البيانات نمط create الإلحاقي، ولها قواعد خاصة لاستهداف التحديث؛ فلا تنقل أمثلة الفهارس العادية إليها من دون مراجعة هذا النموذج. لا ترسل هذه الدورة أي طلب إدخال جماعي.

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

{"create":{"_index":"museum-artifacts-v1","_id":"art-101"}}
{"artifact_id":"art-101","title":"Bronze compass"}
{"create":{"_index":"museum-artifacts-v1","_id":"art-102"}}
{"artifact_id":"art-102","title":"Paper navigation chart"}

هذا NDJSON توضيحي لـPOST /_bulk. محرف السطر الجديد الأخير جزء من التأطير، وكل سطر تعريف إجراء أو مصدر هو كائن JSON كامل.

قد يتضمن نجاح HTTP عناصر فاشلة

تتضمن استجابات Bulk علماً عاماً اسمه errors، ونتيجة عنصر مرتبة لكل إجراء. لا يثبت نجاح استجابة النقل أن كل مستند قد فُهرس. اربط كل عنصر استجابة بسجل المصدر الموافق له، واحتفظ بهوية المصدر وسبب الرفض. تعرض الاستجابة التخطيطية أدناه عنصراً أُنشئ وآخر رُفض بسبب التعيين. وقد تؤدي إعادة الدفعة كلها إلى تكرار العمل الناجح أو الكتابة فوقه، بحسب الإجراء وسياسة المعرّفات. احسب العناصر المقبولة والمرفوضة نهائياً والقابلة لإعادة المحاولة ومجهولة النتيجة، بحيث يساوي مجموعها عدد الإجراءات المرسلة.

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

{"errors":true,"items":[{"create":{"_id":"art-101","status":201}},{"create":{"_id":"art-102","status":400,"error":{"type":"mapper_parsing_exception","reason":"synthetic field-type conflict"}}}]}

هذه استجابة مبسطة لفهم النجاح الجزئي، وليست مخرجات خادم مقاسة. يقابل ترتيب عناصر الاستجابة ترتيب الإجراءات في الطلب.

أعد ما تسمح به النتيجة فقط

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

يجعل المصدر الدائم الإصلاح ممكناً

احتفظ بتدفق مصدر قابل للاستعادة أو بيان دفعة ثابت، يتضمن هوية الحدث ومراجعة المصدر وبصمة الحمولة حسب الحاجة. لا يكفي نجاح إرسال المنتج لحذف المصدر قبل اكتمال إقرار النظام التالي ومطابقة النتائج. اعزل السجلات المعيبة مع سبب وسياسة احتفاظ معتمدة. ولا تكون مجموعة السجلات المرفوضة مفيدة إلا إذا أمكن لشخص مسؤول فحصها وتصحيحها وإعادة إرسالها بأمان. احمِ بيانات العملاء وبيانات الاعتماد في المخرجات التشخيصية. تعامل مع إنتاجية Bulk بوصفها مسألة موثوقية تطبيق تشمل الضغط العكسي ومحاسبة العناصر، لا سباقاً لتعظيم الطلبات المتزامنة.

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

illegal_argument_exception

لماذا يحدث؟: لا يطابق تأطير Bulk أو اقتران الإجراء بسطر المصدر البروتوكول المطلوب.
كيف تصلحه؟: تحقق من كل سطر NDJSON ومن محرف السطر الجديد النهائي قبل الإرسال.
كيف تتجنب تكراره؟: استخدم مساعداً من عميل مدعوم أو مسلسلاً محلياً خضع للاختبار.

mapper_parsing_exception

لماذا يحدث؟: يتضمن أحد المستندات قيمة لا تتوافق مع التعيين.
كيف تصلحه؟: اعزل ذلك العنصر، وأصلح عقد المصدر الدقيق الذي خالفه.
كيف تتجنب تكراره؟: تتبع إخفاق كل عنصر، ولا تكتفِ بحالة HTTP.

es_rejected_execution_exception

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

اختبر فهمك

1. أعادت الاستجابة HTTP 200 مع errors:true. هل يجوز للمنتج حذف سجلات المصدر كلها؟

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

لا. افحص كل عنصر، واحفظ هويات العناصر المقبولة، واحتفظ بالسجلات المرفوضة أو مجهولة النتيجة لمسار الإصلاح الموثق. نجاح النقل يعني وصول الاستجابة فقط. طابق أعداد الإجراءات، ولا تُعِد عمليات create الناجحة أو التحديثات التراكمية من دون معرفة نتائجها.

2. لماذا ينبغي أن يشمل حد الدفعة البايتات إلى جانب عدد المستندات؟