The $dateSubtract operator subtracts time units from a date inside MongoDB aggregation pipelines. Use it to compute rolling cutoffs, grace-period starts, retention windows, or any past timestamp relative to a stored date or $$NOW.
Subtract units from dates.
startDate, unit, amount.
day, hour, year, etc.
Optional IANA zone.
Cutoffs, grace periods.
Subtract vs add.
In MongoDB’s aggregation framework, the $dateSubtract operator decrements a startDate by a given amount of unit values and returns the resulting BSON date. For example, subtracting 30 days from $$NOW gives you the cutoff for “active in the last 30 days” queries.
$dateSubtract returns a Date, not a number. It mirrors $dateAdd but moves backward in time. Requires MongoDB 5.0+ and a valid BSON date for startDate.
The $dateSubtract operator takes an object with at least three fields:
{
$dateSubtract: {
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 subtract (positive integer or expression).timezone — optional Olson timezone ID (e.g. "America/New_York").$project, $addFields, $set, or update aggregation pipelines.$dateSubtract over $dateAdd with a negative amount for readable backward date math.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | startDate, unit, amount |
| Return type | BSON Date |
| Supported units | year, quarter, week, day, hour, minute, second, millisecond |
| MongoDB version | 5.0+ |
{
$dateSubtract: {
startDate: "$dueDate",
unit: "day",
amount: 7
}
}One week earlier
{
$dateSubtract: {
startDate: "$$NOW",
unit: "day",
amount: 30
}
}Rolling window start
{
$dateSubtract: {
startDate: "$reportDate",
unit: "year",
amount: 1
}
}Same date last year
{
$dateSubtract: {
startDate: "$start",
unit: "day",
amount: 1,
timezone: "UTC"
}
}Timezone-aware subtract
Compute grace-period reminders, rolling activity cutoffs, and timezone-aware past dates with $dateSubtract.
Use an invoices collection and compute a reminder date seven days before payment is due.
Suppose you have an invoices collection with a dueDate field:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"customer": "Acme Corp",
"dueDate": ISODate("2024-06-15T00:00:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"customer": "Globex",
"dueDate": ISODate("2024-07-01T00:00:00Z")
}
]Subtract 7 days from dueDate to get when to send a payment reminder:
db.invoices.aggregate([
{
$project: {
customer: 1,
dueDate: 1,
reminderDate: {
$dateSubtract: {
startDate: "$dueDate",
unit: "day",
amount: 7
}
}
}
}
])$dateSubtract moves the date backward by exactly 7 calendar days.Date suitable for scheduled jobs or $match filters.Rolling windows, year-over-year comparisons, and filtering recent activity.
Subtract 30 days from the current time to define the start of a “last 30 days” window:
db.users.aggregate([
{
$addFields: {
activeSinceCutoff: {
$dateSubtract: {
startDate: "$$NOW",
unit: "day",
amount: 30
}
}
}
},
{
$project: {
name: 1,
lastLogin: 1,
activeSinceCutoff: 1
}
}
])
// activeSinceCutoff = date 30 days before pipeline runs$$NOW is evaluated when the pipeline runs. Subtracting days gives a fixed cutoff you can compare against lastLogin or other activity timestamps.
Subtract one year for year-over-year reporting:
db.sales.aggregate([
{
$project: {
region: 1,
reportDate: 1,
priorYearDate: {
$dateSubtract: {
startDate: "$reportDate",
unit: "year",
amount: 1
}
}
}
}
])
// reportDate: 2024-03-15 → priorYearDate: 2023-03-15The year unit handles calendar-year arithmetic, including leap-year edge cases (Feb 29 maps appropriately). Use the result to join or compare against historical data.
Combine $dateSubtract with $match to find recently active users:
db.users.aggregate([
{
$match: {
lastLogin: {
$gte: {
$dateSubtract: {
startDate: "$$NOW",
unit: "day",
amount: 7
}
}
}
}
},
{
$project: {
name: 1,
lastLogin: 1
}
}
])MongoDB 5.0+ allows aggregation expressions inside $match when using the aggregation pipeline form of find or in $match after $addFields. Compute the cutoff once, then keep documents where lastLogin is on or after that date.
$$NOW.$dateSubtract WorksThe base date is evaluated per document — a field, $$NOW, or literal ISODate.
MongoDB subtracts amount of unit, optionally respecting timezone.
The earlier timestamp is stored in the field you define — ready for filtering or display.
Use in $match range queries, reminders, YoY joins, or alongside $dateAdd for bidirectional date math.
The $dateSubtract operator is the clearest way to perform backward date arithmetic in MongoDB aggregation pipelines. With explicit unit and amount fields, it replaces negative $dateAdd calls and manual millisecond subtraction for most business rules.
Pair it with $dateAdd for forward shifts and $dateDiff when you need the distance between two dates as a number. Always confirm your MongoDB version is 5.0+ and that startDate fields are proper BSON dates.
$dateSubtract instead of negative $dateAdd for clarityDate type, not stringstimezone when local calendar rules matterunit (day vs hour vs year)$dateSubtract on MongoDB versions before 5.0month unit exists)$dateSubtract with $dateDiff$dateFromString first$dateSubtractUse these points when subtracting time from dates in MongoDB.
Backward date math.
PurposestartDate, unit, amount.
SyntaxNot a number.
OutputOptional Olson ID.
OptionSubtract vs add.
ImportantMove on to $dateToParts to split dates into components, or review $dateAdd for forward date math.
5 people found this page helpful