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