$dateAdd is a MongoDB aggregation expression that adds a number of time units (day, month, hour, and more) to a start date and returns the new date. Prefer it over raw millisecond math when you need calendar units.
Set unit (for example "day") and amount (for example 7).
Optionally set timezone when calendar boundaries matter for a zone.
Piece
Required?
Role
startDate
Yes
Date to start from
unit
Yes
What to add (day, month, hour, …)
amount
Yes
How many units (can be negative)
timezone
No
Olson timezone string when needed
Pseudocode
Pseudocode
for each document:
start = evaluate(startDate)
unit = evaluate(unit)
n = evaluate(amount)
if start is null or missing:
result = null
else:
result = start + n units // calendar-aware
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while writing date-add expressions.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $dateAdd: { startDate, unit, amount } }
Common units
day, month, week, hour
Negative amount
Moves backward (like subtract)
vs $add
$add uses milliseconds only
Sibling
$dateSubtract for going back
Sample check
2026-01-10 + 7 days → 2026-01-17
Try it
Live Preview
Watch $dateAdd move a borrow date forward by days or months.
Simulates $dateAdd from start date 2026-01-10 (UTC midnight).
We use one library loan. First add 7 days for the due date, then add 1 month for a renewal date. Run these in mongosh after inserting the sample data once.
Example 1 — Sample Data
Imagine one library loan with a borrow date of 2026-01-10. We save it in a collection named loans.
Same stored document. Still using borrowedOn: 2026-01-10 from Example 1.
Use the month unit.unit: "month" adds one calendar month, not a fixed 30 days.
Easy check. January 10 plus one month lands on February 10.
Edge Cases & Pitfalls
Check these before using $dateAdd in production pipelines.
month
Month lengths vary
Adding one month from Jan 31 may land on Feb 28/29. Prefer day when you need an exact day count.
vs add
Do not confuse with $add
$add treats numbers as milliseconds. Use $dateAdd for day/month/hour units.
tz
Timezone can change boundaries
Day and month math can depend on the zone near DST. Set timezone when your app is zone-aware.
null
Null start dates stay null
Missing startDate yields null, not an error. Validate or default dates before adding.
Analysis
Performance Notes
Approach
Cost
Best for
$dateAdd per document
Cheap date math
Due dates, renewals, SLA windows
Many nested date ops
Still O(docs)
Multi-step schedules
Filter after computing
Scan + compute
Prefer $match on stored dates when possible
Date arithmetic is cheap compared with large sorts or joins. Filter early with $match when only some documents need a computed date.
Remember
Key Takeaways
Role: add calendar/clock units to a date.
Required:startDate, unit, amount.
Units: day, month, hour, and more—not just milliseconds.
Sibling: use $dateSubtract to go backward.
One line:$dateAdd answers “what date is N units after this?”—with real day/month units, not only milliseconds.
Frequently Asked Questions
$dateAdd adds a number of calendar or clock units to a start date and returns the new date. Use it inside aggregation stages such as $project and $addFields.
Use { $dateAdd: { startDate: <date>, unit: <string>, amount: <number>, timezone: <tz> } }. startDate, unit, and amount are required; timezone is optional.
Supported units include year, quarter, month, week, day, hour, minute, second, and millisecond. Pass the unit as a string such as "day" or "month".
$add can add milliseconds to a Date. $dateAdd understands calendar units like month and day, so month lengths and DST are handled more naturally.
$dateAdd moves a date forward. $dateSubtract moves it backward by the same unit/amount style.
If startDate is null or missing, $dateAdd returns null.
