The $dateDiff operator calculates how many time units lie between two dates in MongoDB aggregation pipelines. Use it to measure delivery times, ticket resolution duration, account age, or any elapsed-time metric.
Two dates → number.
startDate, endDate, unit.
day, hour, year, etc.
Optional Olson zone.
SLA, age, shipping.
Measure vs shift.
In MongoDB’s aggregation framework, the $dateDiff operator returns an integer count of complete time units between startDate and endDate. For example, if an order was placed on June 1 and delivered on June 8, $dateDiff with unit: "day" returns 7.
$dateDiff returns a number, not a date. If endDate is before startDate, the result is negative. Requires MongoDB 5.0+.
The $dateDiff operator takes an object with at least three fields:
{
$dateDiff: {
startDate: <dateExpression>,
endDate: <dateExpression>,
unit: <string>,
timezone: <string>,
startOfWeek: <string>
}
}startDate — the earlier (or reference) date in the comparison.endDate — the later (or target) date; can be $$NOW.unit — one of: year, quarter, week, day, hour, minute, second, millisecond.timezone — optional Olson timezone ID for calendar-aware calculations.startOfWeek — optional when unit is week (sun, mon, etc.).| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | startDate, endDate, unit |
| Return type | Integer (number of units) |
| Supported units | year, quarter, week, day, hour, minute, second, millisecond |
| MongoDB version | 5.0+ |
{
$dateDiff: {
startDate: "$orderedAt",
endDate: "$deliveredAt",
unit: "day"
}
}Shipping duration
{
$dateDiff: {
startDate: "$birthDate",
endDate: "$$NOW",
unit: "year"
}
}Years since birth
{
$dateDiff: {
startDate: "$openedAt",
endDate: "$closedAt",
unit: "hour"
}
}Ticket resolution time
{
$dateDiff: {
startDate: "$start",
endDate: "$end",
unit: "day",
timezone: "UTC"
}
}Timezone-aware diff
Measure shipping days, ticket resolution hours, account age, and timezone-aware elapsed time with $dateDiff.
Use an orders collection and compute shipping duration from order to delivery.
Suppose you have an orders collection with order and delivery timestamps:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"item": "Laptop",
"orderedAt": ISODate("2024-06-01T10:00:00Z"),
"deliveredAt": ISODate("2024-06-08T14:30:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"item": "Mouse",
"orderedAt": ISODate("2024-06-10T09:00:00Z"),
"deliveredAt": ISODate("2024-06-12T11:00:00Z")
}
]Calculate how many full days passed between order and delivery:
db.orders.aggregate([
{
$project: {
item: 1,
orderedAt: 1,
deliveredAt: 1,
shippingDays: {
$dateDiff: {
startDate: "$orderedAt",
endDate: "$deliveredAt",
unit: "day"
}
}
}
}
])$dateDiff counts complete calendar days between the two timestamps.Resolution time in hours, account age, and filtering by duration.
Measure how many hours a support ticket stayed open:
db.tickets.aggregate([
{
$project: {
title: 1,
openedAt: 1,
closedAt: 1,
hoursOpen: {
$dateDiff: {
startDate: "$openedAt",
endDate: "$closedAt",
unit: "hour"
}
}
}
}
])
// openedAt: 2024-06-01 09:00, closedAt: 2024-06-01 17:00 → hoursOpen: 8Use finer units like hour, minute, or millisecond when day-level precision is too coarse for SLAs or performance metrics.
Calculate how many years a user has been registered using $$NOW:
db.users.aggregate([
{
$project: {
name: 1,
registeredAt: 1,
accountAgeYears: {
$dateDiff: {
startDate: "$registeredAt",
endDate: "$$NOW",
unit: "year"
}
}
}
}
])$$NOW is the current server time when the pipeline runs. The year unit returns whole years elapsed, useful for loyalty tiers or retention analysis.
Combine $dateDiff with $match to find fast deliveries:
db.orders.aggregate([
{
$addFields: {
shippingDays: {
$dateDiff: {
startDate: "$orderedAt",
endDate: "$deliveredAt",
unit: "day"
}
}
}
},
{
$match: {
shippingDays: { $lte: 3 }
}
},
{
$project: {
item: 1,
shippingDays: 1
}
}
])Compute the difference in $addFields, then filter in a later $match stage. This pattern supports SLA reporting and quality dashboards.
$dateDiff WorksstartDate and endDate are evaluated per document — fields, $$NOW, or literals.
MongoDB calculates complete units between the dates, optionally using timezone.
The count is stored in the field you define — ready for sorting, filtering, or grouping.
Use in $match, $group, charts, or alongside $dateAdd for scheduling.
The $dateDiff operator is the clearest way to measure elapsed time between two dates in MongoDB aggregation pipelines. It replaces manual millisecond subtraction and division with readable, unit-based date math.
Use $dateAdd when you need a future or past date, and $dateDiff when you need how long something took. Always ensure both operands are BSON dates and that your MongoDB deployment is version 5.0 or later.
Date type, not stringsunit for your business questiontimezone when calendar days depend on locale$$NOW for “time since” calculations$match for SLA and threshold filters$dateDiff on MongoDB versions before 5.0$dateDiff with $dateAddmonth unit exists)startDate and endDate without expecting negative values$dateDiffUse these points when measuring time between dates in MongoDB.
Two dates → number.
Purposestart, end, unit.
SyntaxTruncated units.
OutputOptional Olson ID.
OptionMeasure vs shift.
ImportantMove on to $dateFromParts to build dates from components, or review $dateAdd for forward date math.
5 people found this page helpful