insertOne() (إدراج مستند واحد)
آخر تحديث: 2026-10-09
insertOne() (إدراج مستند واحد)
تدرج طريقة insertOne() مستندًا واحدًا داخل مجموعة. إذا لم يكن المستند يحوي حقل _id، تولّد MongoDB تلقائيًا معرّف كائن (ObjectId). تتضمن النتيجة الحقلين insertedId و acknowledged. وهي أبسط طريقة كتابة لمستند واحد، بكلفة جولة طلب واحدة (على عكس insertMany()).
| الفئة | الكتابة |
|---|---|
| إصدار MongoDB | 1.0+ |
| لغة المثال | mongosh (الطرفية) |
📝 الصيغة
db.<collection>.insertOne(<document>, { writeConcern: <options> })⚙️ المعلمات
| مستند | مستند BSON المراد إدراجه؛ قد يحتوي على حقول ومصفوفات متداخلة. |
|---|
القيمة المرجعة：WriteResult: { acknowledged, insertedId }
▶ مثال
نفّذ الأوامر التالية في mongosh المحلي لديك (يتطلب تشغيل mongod):
// insertOne: إدراج مستخدم واحد
db.users.insertOne({
name: "Alice",
age: 21,
address: { city: "Beijing" }
})المخرجات：
{
acknowledged: true,
insertedId: ObjectId("64c8a1b2f3d4e5a6b7c8d9e0")
}📌 ملاحظات
- يُولَّد ObjectId تلقائيًا عند غياب _id
- الحد الأقصى لحجم المستند: 16 ميجابايت (BSON)
- تكرار _id يرفع خطأ DuplicateKeyError (فهرس فريد)
- إعدادات الكتابة الافتراضية هي acknowledged: true
🏷️ وسوم ذات صلة
💡 حالات ذات صلة
قواعد البيانات والمجموعات: إدارة مساحات الأسماء في MongoDB
إدراج المستندات: شرح مفصل لوظيفتي `insertOne` و`insertMany`
📚 دروس ذات صلة
❓ الأسئلة الشائعة
Qهل يمكن أن تدرج insertOne مصفوفة؟
Aلا — يجب أن يكون المستوى الأعلى مستندًا (كائنًا). أما المصفوفات فتُستخدم كقيم حقول داخل المستند.
Qماذا يحدث إذا حذفت _id في insertOne؟
Aتولّد MongoDB تلقائيًا معرّف كائن لحقل _id. يمكنك توفير _id خاص بك، لكن يجب أن يكون فريدًا داخل المجموعة وإلا يُرفع خطأ تكرار المفتاح.
Qهل يمكنني تحديد writeConcern مع insertOne؟
Aنعم، مرّر خيارات مثل { writeConcern: { w: 'majority' } } كوسيط ثانٍ للتحكم في مستوى التأكيد؛ وإلا فتُطبَّق إعدادات المجموعة أو الجلسة.
