$dateAdd (إضافة إلى تاريخ)
آخر تحديث: 2026-10-09
$dateAdd (إضافة إلى تاريخ)
يضيف $dateAdd مقدارًا محددًا من وحدة زمنية إلى تاريخ ويعيد التاريخ الجديد — وهو العامل المفضّل للتواريخ النسبية في خطوط الأنابيب (مواعيد الاستحقاق، تواريخ التجديد، المواعيد النهائية). تدعم وحدة (unit) السنة والشهر والأسبوع واليوم والساعة والدقيقة والثانية والميلي ثانية؛ وقد تكون الكمية سالبة، بما يعادل الطرح. مع timezone يمكنك الحساب وفق تقويم منطقة زمنية محددة للحصول على حدود دقيقة للأشهر والسنوات. يعمل في $project و $addFields و $set والتعبيرات المتداخلة.
| الفئة | التاريخ |
|---|---|
| إصدار MongoDB | 5.0+ |
| لغة المثال | mongosh (الطرفية) |
📝 الصيغة
{ $dateAdd: { startDate: <date-expression>, unit: <unit>, amount: <number>, timezone: <timezone> } }⚙️ المعلمات
| startDate | التاريخ المراد تعديله؛ قيمة Date أو timestamp أو تعبير يُحلّ إلى تاريخ. |
|---|---|
| unit | الوحدة: year أو month أو week أو day أو hour أو minute أو second أو millisecond. |
| amount | المقدار المراد إضافته؛ الموجب يضيف والسالب يطرح؛ وخارج نطاق عدد صحيح 64 بت يرمي خطأً. |
| timezone | المنطقة الزمنية اختيارية للحساب؛ اسم IANA (مثل Asia/Shanghai) أو إزاحة UTC. |
القيمة المرجعة：التاريخ الجديد (BSON Date)؛ null إذا كان startDate يساوي null أو مفقودًا.
▶ مثال
نفّذ الأوامر التالية في mongosh المحلي لديك (يتطلب تشغيل mongod):
// $dateAdd: تاريخ الاستحقاق بعد 30 يومًا من الإنشاء (توقيت بكين)
db.orders.aggregate([
{ $project: {
dueDate: { $dateAdd: { startDate: '$createdAt', unit: 'day', amount: 30, timezone: 'Asia/Shanghai' } }
} }
])المخرجات：
{ "_id": 1, "dueDate": ISODate("2026-10-25T00:00:00Z") }
{ "_id": 2, "dueDate": ISODate("2026-11-15T00:00:00Z") }📌 ملاحظات
- الوحدات الثمانية المذكورة فقط هي المدعومة؛ والكمية خارج نطاق int64 تُسبب خطأً
- startDate الفارغ أو المفقود يُرجع null — احمِه بـ $ifNull
- حساب الأشهر يقصّ إلى أيام شهر النتيجة (31 يناير زائد شهر واحد = آخر يوم في فبراير)
🏷️ وسوم ذات صلة
💡 حالات ذات صلة
مزيد من الحالات العملية قريبًا.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
Qهل يمكن لـ $dateAdd إضافة عدة وحدات دفعة واحدة؟
Aوحدة واحدة لكل استدعاء؛ ندِّد الاستدعاءات أو اربط عدة $dateAdd للوحدات المتعددة.
Qهل تدعم الكمية القيم السالبة؟
Aنعم — الكميات السالبة تطرح، أو استخدم $dateSubtract بدلًا من ذلك.
Qكيف أحدد المنطقة الزمنية؟
Aاستخدم اسم IANA مثل Asia/Shanghai أو إزاحة مثل +08:00؛ الافتراضي هو UTC.
