$dateDiff (فرق التواريخ)
آخر تحديث: 2026-10-09
$dateDiff (فرق التواريخ)
يحسب $dateDiff الفرق بين تاريخين بوحدة معينة كعدد صحيح — مثالي للأعمار، مدة الاشتراكات، أو زمن الإقامة. تدعم وحدة (unit) السنة والشهر والأسبوع واليوم والساعة والدقيقة والثانية والميلي ثانية؛ وتُقتطع النتائج إلى حدود الوحدات الكاملة (السنة تحسب السنوات الكاملة فقط). تحدد startOfWeek بداية الأسبوع وتُطبّق فقط عندما تكون الوحدة أسبوعًا. تحدد timezone التقويم المستخدم؛ اضبطها دائمًا عبر المناطق.
| الفئة | التاريخ |
|---|---|
| إصدار MongoDB | 5.0+ |
| لغة المثال | mongosh (الطرفية) |
📝 الصيغة
{ $dateDiff: { startDate: <date-expression>, endDate: <date-expression>, unit: <unit>, timezone: <timezone>, startOfWeek: <week-start> } }⚙️ المعلمات
| startDate / endDate | مطلوب؛ تاريخا البداية والنهاية. |
|---|---|
| unit | مطلوب؛ وحدة الفرق (الوحدات الثماني أعلاه). |
| timezone | المنطقة الزمنية اختيارية للحساب. |
| startOfWeek | اختياري؛ يُطبَّق فقط عندما تكون unit هي week؛ قيم مثل Monday وSunday. |
القيمة المرجعة：الفرق الصحيح (endDate ناقص startDate)؛ null إذا كان أي من التاريخين null.
▶ مثال
نفّذ الأوامر التالية في mongosh المحلي لديك (يتطلب تشغيل mongod):
// $dateDiff: حساب العمر بالسنوات
db.users.aggregate([
{ $project: {
ageYears: { $dateDiff: { startDate: '$birthDate', endDate: '$$NOW', unit: 'year' } }
} }
])المخرجات：
{ "_id": 1, "ageYears": 28 }
{ "_id": 2, "ageYears": 31 }📌 ملاحظات
- النتيجة هي endDate ناقص startDate وقد تكون سالبة
- الوحدات الأكبر تقتطع إلى حدود كاملة: السنة تحسب السنوات الكاملة فقط
- startOfWeek تُطبّق على وحدة الأسبوع فقط؛ قيمها من الاثنين إلى الأحد
🏷️ وسوم ذات صلة
💡 حالات ذات صلة
مزيد من الحالات العملية قريبًا.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
Qهل تحتوي النتيجة على كسور عشرية؟
Aلا — يُرجع $dateDiff أعدادًا صحيحة مقتطعة عند حدود الوحدات.
Qهل يمكن أن يكون الفرق سالبًا؟
Aنعم — سالب عندما يكون endDate أسبق من startDate.
Qكيف أعدّ الأيام بين تاريخين؟
Aاضبط unit على day؛ ولاحظ أن timezone تحرّك حدود الأيام التقويمية.
