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