replaceOne() (استبدال مستند)
آخر تحديث: 2026-10-09
replaceOne() (استبدال مستند)
تستبدل replaceOne() أول مستند يطابق مرشحًا بمستند جديد كليًا. على عكس updateOne() التي تستخدم عوامل تحديث في وسيطها الثاني، فإن الوسيط الثاني هنا هو مستند الاستبدال نفسه — يُستبدل كل حقل ما عدا _id. تتضمن النتيجة matchedCount و modifiedCount. وهي الأداة الصحيحة عندما يجب إعادة كتابة بنية المستند بالكامل.
| الفئة | الكتابة |
|---|---|
| إصدار MongoDB | 1.0+ |
| لغة المثال | mongosh (الطرفية) |
📝 الصيغة
db.<collection>.replaceOne(<filter>, <replacement>, { upsert: <bool> })⚙️ المعلمات
| شرط التصفية | شرط يطابق المستند المراد استبداله. |
|---|---|
| مستند جديد | مستند الاستبدال الكامل؛ يستبدل كل الحقول عدا _id. |
| upsert | اختياري. يُدرج عندما لا يتطابق شيء؛ الافتراضي false. |
القيمة المرجعة：UpdateResult: { acknowledged, matchedCount, modifiedCount, upsertedId }.
▶ مثال
نفّذ الأوامر التالية في mongosh المحلي لديك (يتطلب تشغيل mongod):
// replaceOne: استبدال مستند Bob بالكامل
db.users.replaceOne(
{ name: 'Bob' },
{ name: 'Bob', age: 26, city: 'Shanghai', vip: true }
)المخرجات：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 ملاحظات
- يجب أن يحتفظ مستند الاستبدال بـ _id (أو يتجاهله ليبقى الأصلي) وإلا يُرفع خطأ
- عوامل التحديث مثل {$set: ...} لا تُفسَّر هنا — بل تُخزَّن كحقول حرفية
- يُستبدل أول تطابق فقط؛ كرِّر العملية أو استخدم updateMany() للعمليات الجماعية
🏷️ وسوم ذات صلة
💡 حالات ذات صلة
مزيد من الحالات العملية قريبًا.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
Qما الفرق بين replaceOne و updateOne؟
Aتغيّر updateOne() الحقول تدريجيًا بعوامل التحديث؛ بينما تستبدل replaceOne() المستند بمستند جديد كامل، مع الكتابة فوق كل حقل ما عدا _id.
Qهل يمكن أن تغيّر replaceOne حقل _id؟
Aلا. _id غير قابل للتغيير؛ يجب أن يحتفظ مستند الاستبدال بـ _id الأصلي وإلا يُرفع خطأ.
Qهل يمكن وضع عوامل تحديث في الوسيط الثاني لـ replaceOne؟
Aلا. الوسيط الثاني هو مستند الاستبدال؛ فـ {$set: ...} سيُخزَّن حرفيًا كحقل.
