findOne() (الاستعلام عن مستند واحد)
آخر تحديث: 2026-10-09
findOne() (الاستعلام عن مستند واحد)
تُعيد findOne() أول مستند يطابق مرشحًا مباشرةً كمستند وليس كمؤشر، مثل `db.users.findOne({ name: 'Alice' })`. عندما يطابق عدة مستندات، تُعيد الأول بالترتيب الطبيعي؛ وعند عدم التطابق تُعيد null. وهي تتجاوز تكرار المؤشر، مما يجعلها مثالية للبحث بحقل فريد مثل _id أو اسم المستخدم.
| الفئة | القراءة |
|---|---|
| إصدار MongoDB | 1.0+ |
| لغة المثال | mongosh (الطرفية) |
📝 الصيغة
db.<collection>.findOne(<filter>, <projection>)⚙️ المعلمات
| شرط التصفية | كائن شرط؛ يدعم معاملات الاستعلام. |
|---|---|
| الإسقاط | اختياري. يتحكم في الحقول المُرجَعة: 1 تضمين / 0 استبعاد. |
القيمة المرجعة：أول مستند مطابق؛ null عندما لا يتطابق شيء.
▶ مثال
نفّذ الأوامر التالية في mongosh المحلي لديك (يتطلب تشغيل mongod):
// findOne: البحث عن مستخدم بواسطة _id
const user = db.users.findOne(
{ _id: ObjectId('64c8a1b20000000000000001') },
{ name: 1, age: 1, _id: 0 }
)
userالمخرجات：
{ name: 'Alice', age: 21 }📌 ملاحظات
- يُعاد أول تطابق فقط؛ الترتيب الطبيعي غير مضمون الاستقرار
- تُعيد null عند عدم التطابق — احمِ نفسك بـ if (doc)
- أنظف من find().limit(1) لقراءات المستند الواحد
🏷️ وسوم ذات صلة
💡 حالات ذات صلة
حذف المستندات والبدء في استخدام Node.js
الوثائق وBSON: حجر الأساس لبيانات MongoDB
نماذج مونغوس وتصميم المخطط
📚 دروس ذات صلة
❓ الأسئلة الشائعة
Qهل findOne مثل find().limit(1)؟
Aمتشابهتان، لكن findOne() تُعيد المستند مباشرةً بينما تُعيد find() مؤشرًا للتكرار؛ فضّل findOne() للبحث بالحقول الفريدة.
Qماذا تُعيد findOne عند عدم العثور على شيء؟
Aتُعيد null دون رفع خطأ؛ تُستهلك عادةً بصيغة if (doc) { ... }.
Qهل يمكن أن تُعيد findOne بعض الحقول فقط؟
Aنعم — مرّر إسقاطًا كوسيط ثانٍ، مثل {name: 1}.
