The $dateTrunc operator rounds a BSON Date down to the start of a time period — such as midnight for a day, the first of the month, or the top of the hour. Use it for time-series charts, daily rollups, and grouping events into calendar buckets.
Date → period start.
date, unit.
day, month, hour…
Wider time bins.
Charts, rollups.
Boundary vs parts.
In MongoDB’s aggregation framework, the $dateTrunc operator takes a timestamp and returns the BSON Date at the beginning of the chosen unit period. For example, truncating ISODate("2024-06-15T14:30:45Z") to unit: "day" yields ISODate("2024-06-15T00:00:00Z") — the start of that calendar day in UTC.
$dateTrunc returns a Date, not a string or number. It always rounds down to the period boundary. Requires MongoDB 5.0+.
The $dateTrunc operator takes an object with a required date and unit:
{
$dateTrunc: {
date: <dateExpression>,
unit: <string>,
binSize: <numberExpression>,
timezone: <stringExpression>,
startOfWeek: <stringExpression>
}
}date — required; the BSON date to truncate (field, $$NOW, or literal).unit — required; one of: year, quarter, month, week, day, hour, minute, second, millisecond.binSize — optional; size of each bin in units (default 1). Use 2 with hour for two-hour buckets.timezone — optional Olson timezone ID for calendar-aware truncation.startOfWeek — optional when unit is week (sun, mon, etc.).Date at the start of the matching period.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | date, unit |
| Return type | BSON Date (period boundary) |
| Default binSize | 1 |
| MongoDB version | 5.0+ |
{
$dateTrunc: {
date: "$createdAt",
unit: "day"
}
}Midnight UTC
{
$dateTrunc: {
date: "$orderDate",
unit: "month"
}
}First day of month
{
$dateTrunc: {
date: "$loggedAt",
unit: "hour"
}
}Top of the hour
{
$dateTrunc: {
date: "$eventAt",
unit: "day",
timezone: "America/Chicago"
}
}Local calendar day
Truncate timestamps to day and month boundaries, build hourly time-series buckets, and group revenue by truncated periods with $dateTrunc.
Use a pageviews collection and normalize timestamps to daily boundaries.
Suppose you have a pageviews collection with precise visit timestamps:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"path": "/home",
"visitedAt": ISODate("2024-06-15T09:12:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"path": "/pricing",
"visitedAt": ISODate("2024-06-15T18:45:30Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6c"),
"path": "/blog",
"visitedAt": ISODate("2024-06-16T07:00:00Z")
}
]Truncate visitedAt to the start of each UTC day:
db.pageviews.aggregate([
{
$project: {
path: 1,
visitedAt: 1,
dayBucket: {
$dateTrunc: {
date: "$visitedAt",
unit: "day"
}
}
}
}
])dayBucket despite different times.Date, ideal for $group keys.Monthly revenue rollups, wider bins, and timezone-aware daily buckets.
Truncate order dates to month boundaries, then sum revenue per month:
db.orders.aggregate([
{
$addFields: {
monthBucket: {
$dateTrunc: {
date: "$orderDate",
unit: "month"
}
}
}
},
{
$group: {
_id: "$monthBucket",
totalRevenue: { $sum: "$amount" },
orderCount: { $sum: 1 }
}
},
{ $sort: { _id: 1 } }
])Using a truncated date as the $group key is cleaner than string formatting. All orders in June 2024 share one bucket starting at the first instant of that month.
Use binSize: 2 with unit: "hour" for wider time-series buckets:
db.metrics.aggregate([
{
$project: {
metric: 1,
recordedAt: 1,
twoHourBin: {
$dateTrunc: {
date: "$recordedAt",
unit: "hour",
binSize: 2
}
}
}
}
])
// 09:30 and 10:45 → same bin (08:00–10:00 boundary)
// 11:15 → next bin (10:00–12:00 boundary)binSize groups multiple units into one bin. Useful for dashboards that do not need minute-level precision but still want consistent Date keys instead of strings.
Apply a timezone so daily buckets follow local midnight, not UTC:
db.events.aggregate([
{
$project: {
title: 1,
eventAt: 1,
localDay: {
$dateTrunc: {
date: "$eventAt",
unit: "day",
timezone: "America/Los_Angeles"
}
}
}
}
])Without timezone, unit: "day" uses UTC midnights. With an Olson ID, truncation respects local calendar days — important for regional analytics and daylight saving boundaries.
$dateTrunc Worksdate is evaluated per document — a field, $$NOW, or literal ISODate.
MongoDB rounds down to the start of the unit (and binSize), optionally using timezone.
The truncated timestamp is ready as a $group key or chart bucket label source.
Pair with $group and $dateToString for labels, or $dateDiff to measure spans between buckets.
The $dateTrunc operator is the clearest way to bucket BSON dates by calendar periods in MongoDB aggregation pipelines. It replaces manual midnight calculations and string-based grouping with a single, readable expression that returns proper Date values.
Use timezone when buckets must follow local days, and binSize when you need wider intervals. Pair with $dateToString for display labels and ensure your MongoDB deployment is version 5.0 or later.
$dateTrunc as $group keys for time-series rollupstimezone for local calendar bucketingunit that matches your chart granularitybinSize for coarser buckets without changing unit logic$dateTrunc on MongoDB versions before 5.0timezone$dateTrunc suffices$dateTruncUse these points when bucketing dates by time periods in MongoDB.
Date → period start.
Purposedate, unit.
SyntaxBoundary timestamp.
OutputWider time bins.
OptionVersion requirement.
ImportantMove on to $dayOfMonth to extract the day number from a date, or review $dateToString for formatted output labels.
5 people found this page helpful