The $dateAdd operator adds time units to a date inside MongoDB aggregation pipelines. Use it to calculate due dates, subscription renewals, trial expirations, or any future timestamp from a stored date.
Add units to dates.
startDate, unit, amount.
day, hour, year, etc.
Optional IANA zone.
Due dates, renewals.
Add vs subtract.
In MongoDB’s aggregation framework, the $dateAdd operator increments a startDate by a given amount of unit values and returns the resulting BSON date. For example, adding 7 days to a subscription start date gives you the end of a one-week trial.
$dateAdd requires MongoDB 5.0+. The startDate must be a valid date (or date expression). Use $convert first if your field is stored as a string.
The $dateAdd operator takes an object with at least three fields:
{
$dateAdd: {
startDate: <dateExpression>,
unit: <string>,
amount: <numberExpression>,
timezone: <string>
}
}startDate — the base date (field reference, $$NOW, or literal).unit — one of: year, quarter, week, day, hour, minute, second, millisecond.amount — how many units to add (integer or expression).timezone — optional Olson timezone ID (e.g. "America/New_York").$project, $addFields, $set, or update aggregation pipelines.amount moves the date backward (prefer $dateSubtract for clarity).| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | startDate, unit, amount |
| Supported units | year, quarter, week, day, hour, minute, second, millisecond |
| MongoDB version | 5.0+ |
| Common stages | $project, $addFields, $set |
{
$dateAdd: {
startDate: "$createdAt",
unit: "day",
amount: 7
}
}One week later
{
$dateAdd: {
startDate: "$renewalDate",
unit: "year",
amount: 1
}
}Annual renewal
{
$dateAdd: {
startDate: "$start",
unit: "hour",
amount: 24,
timezone: "UTC"
}
}Timezone-aware add
{
$dateAdd: {
startDate: "$$NOW",
unit: "day",
amount: 30
}
}30 days from pipeline run
Calculate trial end dates, subscription renewals, and timezone-aware deadlines with $dateAdd.
Use a subscriptions collection and compute a trial end date from startDate.
Suppose you have a subscriptions collection with a startDate field:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"plan": "Trial",
"startDate": ISODate("2024-06-01T00:00:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"plan": "Pro",
"startDate": ISODate("2024-03-15T10:30:00Z")
}
]Compute trialEndDate by adding 14 days to startDate:
db.subscriptions.aggregate([
{
$project: {
plan: 1,
startDate: 1,
trialEndDate: {
$dateAdd: {
startDate: "$startDate",
unit: "day",
amount: 14
}
}
}
}
])$project keeps existing fields and adds trialEndDate.unit: "day" and amount: 14 add exactly 14 calendar days.Annual renewals, hours for SLAs, and timezone-aware scheduling.
Calculate the next renewal date for annual subscriptions:
db.subscriptions.aggregate([
{
$project: {
plan: 1,
startDate: 1,
nextRenewal: {
$dateAdd: {
startDate: "$startDate",
unit: "year",
amount: 1
}
}
}
}
])
// startDate: 2024-03-15 → nextRenewal: 2025-03-15The year unit handles calendar-year arithmetic, including leap years. Use quarter for three-month billing cycles.
Add 48 hours to an incident timestamp for a response deadline:
db.tickets.aggregate([
{
$project: {
title: 1,
openedAt: 1,
slaDeadline: {
$dateAdd: {
startDate: "$openedAt",
unit: "hour",
amount: 48
}
}
}
}
])Fine-grained units like hour, minute, and millisecond suit SLAs, session timeouts, and precise scheduling.
Add one day using a specific timezone so daylight saving is handled correctly:
db.events.aggregate([
{
$project: {
title: 1,
eventStart: 1,
nextDayLocal: {
$dateAdd: {
startDate: "$eventStart",
unit: "day",
amount: 1,
timezone: "America/New_York"
}
}
}
}
])The optional timezone field uses an Olson timezone identifier. Without it, MongoDB uses UTC. Set timezone when business rules depend on local calendar days.
$dateAdd WorksThe base date is evaluated per document — a field, $$NOW, or literal ISODate.
MongoDB adds amount of unit, optionally respecting timezone.
The result is written to the field you define in $project or $addFields.
Ready for $match filters, sorting, or display in reports.
The $dateAdd operator is the standard way to perform forward date arithmetic in MongoDB aggregation pipelines. With clear unit and amount fields, it replaces manual millisecond math for most business date calculations.
Pair it with $dateSubtract for backward shifts and $dateDiff when you need the distance between two dates. Always confirm your MongoDB version is 5.0+ and that startDate fields are proper BSON dates.
Date type, not stringstimezone when local calendar rules matterunit (day vs hour vs year)$dateSubtract for backward moves (clearer intent)$dateAdd on MongoDB versions before 5.0month unit exists)$convert first$dateAdd with $dateDiffamount is as readable as $dateSubtract$dateAddUse these points when adding time to dates in MongoDB.
Forward date math.
PurposestartDate, unit, amount.
Syntaxday, hour, year, etc.
UnitsOptional Olson ID.
OptionVersion requirement.
ImportantMove on to $dateDiff to measure time between dates, or review $convert for type conversion.
5 people found this page helpful