findOneAndUpdate()

تحديث وإرجاع المستند بعملية واحدة findOneAndUpdate()

findOneAndUpdate() تحدّث مستندًا وترجع نسخته (قبل أو بعد التعديل) بعملية ذرّية واحدة.

الفرق عن updateOne() أنها ترجع المستند نفسه بدل تقرير عن عدد المستندات المعدَّلة — مفيدة عندما تحتاج القيمة الجديدة فورًا (مثل عدّاد يزيد ويُستخدم مباشرة)، بلا استعلام findOne() إضافي بعد التحديث.

الصياغة

db.collection.findOneAndUpdate(<filter>, <update>, { returnDocument, upsert })

📄 مثال

// إرجاع النسخة بعد التحديث (وليس قبله)
const updated = db.counters.findOneAndUpdate(
  { _id: "orderNumber" },
  { $inc: { seq: 1 } },
  { returnDocument: "after" }
)

console.log(updated.seq)

أهم المعاملات

المعامل	الوظيفة
returnDocument	"before" (افتراضي) أو "after" — أي نسخة تُرجَع
upsert	إنشاء مستند جديد إن لم يوجد تطابق (اختياري)
sort	ترتيب لاختيار المستند إن تطابق أكثر من واحد (اختياري)

💡 نصائح عملية

مثالية لتنفيذ عدّادات ذرّية (atomic counters) مثل ترقيم الطلبات بلا تعارض بين طلبات متزامنة

⚠️ أخطاء شائعة

توقّع أن القيمة الافتراضية لـ returnDocument هي "after" — الافتراضي فعليًّا "before" (النسخة قبل التعديل)

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار MONGODB الكامل بالعربي.

📚 للتعمق التقني الكامل بالإنجليزية: MDN Web Docs