findOneAndUpdate() (تحديث مستند وإعادته)
آخر تحديث: 2026-10-09
findOneAndUpdate() (تحديث مستند وإعادته)
تحدّث findOneAndUpdate() أول مستند يطابق مرشحًا وتُعيد المستند نفسه — قبل أو بعد التحديث، بتحكم من `returnDocument`: 'before' (الافتراضي) أو 'after'، مثل `db.users.findOneAndUpdate({ name: 'Alice' }, { $set: { age: 22 } }, { returnDocument: 'after' })`. على عكس updateOne() التي تُعيد عدّادات فقط، فإنها تقرأ المستند مرة أخرى، وهي مناسبة للتدفقات التي تحتاج القيمة الجديدة فورًا، مثل العدّادات أو انتقالات آلة الحالة.
| الفئة | الكتابة |
|---|---|
| إصدار MongoDB | 1.0+ |
| لغة المثال | mongosh (الطرفية) |
📝 الصيغة
db.<collection>.findOneAndUpdate(<filter>, <update>, { returnDocument: 'after', upsert: <bool> })⚙️ المعلمات
| شرط التصفية | شرط يطابق المستند المراد تحديثه. |
|---|---|
| عملية التحديث | كائن معاملات التحديث، مثل {$inc: {count: 1}}. |
| returnDocument | اختياري. 'before' يُرجع المستند قبل التحديث، و'after' بعده؛ الافتراضي 'before'. |
| upsert | اختياري. يُدرج عندما لا يتطابق شيء؛ الافتراضي false. |
القيمة المرجعة：المستند قبل (أو بعد) التحديث؛ null إذا لم يتطابق شيء وكان upsert معطَّلًا.
▶ مثال
نفّذ الأوامر التالية في mongosh المحلي لديك (يتطلب تشغيل mongod):
// findOneAndUpdate: تحديث Alice وإعادة المستند الجديد
const doc = db.users.findOneAndUpdate(
{ name: 'Alice' }, { $set: { age: 22 } },
{ returnDocument: 'after' }
)
docالمخرجات：
{
_id: ObjectId('64c8a1b20000000000000001'),
name: 'Alice',
age: 22
}📌 ملاحظات
- تُعيد المستند قبل التحديث افتراضيًا؛ اضبط returnDocument: 'after' للقيمة الجديدة
- المشغلات القديمة تسمّي هذه العملية findAndModify مع خيار new بدلًا من returnDocument
- تُعيد updateOne() عدّادات؛ استخدم هذه الطريقة عند الحاجة إلى المستند نفسه
🏷️ وسوم ذات صلة
💡 حالات ذات صلة
مزيد من الحالات العملية قريبًا.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
Qهل تُعيد findOneAndUpdate المستند قبل التحديث أم بعده؟
Aافتراضيًا تُعيد المستند قبل التحديث؛ مرّر {returnDocument: 'after'} للحصول على المستند بعده.
Qما الفرق بين findOneAndUpdate و updateOne؟
Aتُعيد updateOne() عدّادات فقط؛ بينما تُعيد findOneAndUpdate() المستند، وهو مفيد عند الحاجة إلى القيمة القديمة أو الجديدة.
Qماذا تُعيد findOneAndUpdate عندما لا يطابق شيء؟
Aتُعيد null (مع تعطيل upsert). ومع تفعيل upsert يُدرج مستند جديد ويُعاد.
