$dateAdd (Add to a Date)
Last updated: 2026-10-09
$dateAdd (Add to a Date)
$dateAdd adds a specified amount of a time unit to a date and returns the new date — the go-to operator for relative dates in pipelines (due dates, renewal dates, deadlines). unit supports year, month, week, day, hour, minute, second, and millisecond; amount may be negative, equivalent to subtracting. With timezone you can compute against a specific time zone's calendar for accurate month/year boundaries. Works in $project, $addFields, $set and nested expressions.
| Category | Date |
|---|---|
| MongoDB Version | 5.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $dateAdd: { startDate: <date-expression>, unit: <unit>, amount: <number>, timezone: <timezone> } }⚙️ Parameters
| startDate | The date to modify; a Date, timestamp, or date-resolving expression. |
|---|---|
| unit | The unit: year, month, week, day, hour, minute, second, or millisecond. |
| amount | The amount to add; positive adds, negative subtracts; out of 64-bit integer range throws. |
| timezone | Optional timezone for the calculation; IANA name (e.g. Asia/Shanghai) or UTC offset. |
Returns：The new date (BSON Date); null if startDate is null or missing.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $dateAdd: due date is 30 days after creation (Beijing time)
db.orders.aggregate([
{ $project: {
dueDate: { $dateAdd: { startDate: '$createdAt', unit: 'day', amount: 30, timezone: 'Asia/Shanghai' } }
} }
])Output：
{ "_id": 1, "dueDate": ISODate("2026-10-25T00:00:00Z") }
{ "_id": 2, "dueDate": ISODate("2026-11-15T00:00:00Z") }📌 Notes
- Only the 8 units above are supported; amount beyond int64 range throws
- null/missing startDate yields null — guard with $ifNull
- Month arithmetic truncates to the result month's days (Jan 31 plus 1 month = last day of February)
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QCan $dateAdd add several units at once?
AOne unit per call; nest calls or chain multiple $dateAdd for several units.
QDoes amount support negative values?
AYes — negative amounts subtract, or use $dateSubtract instead.
QHow do I specify the timezone?
AUse an IANA name like Asia/Shanghai or an offset like +08:00; defaults to UTC.
