The $dateToParts operator decomposes a BSON Date into numeric parts such as year, month, day, hour, minute, second, and millisecond. Use it for dashboards, grouping by calendar month, birthday matching (ignoring year), or feeding values into $dateFromParts.
Date → parts object.
date field required.
year, month, day, time.
Local calendar parts.
Reports, grouping.
Split vs build.
In MongoDB’s aggregation framework, the $dateToParts operator takes a single BSON Date and returns a document of integer components. For example, ISODate("2024-06-15T14:30:00Z") becomes { year: 2024, month: 6, day: 15, hour: 14, minute: 30, second: 0, millisecond: 0 } (in UTC unless you specify a timezone).
$dateToParts returns an object, not a single number. Access fields with dot notation in later stages, e.g. $dateParts.year. Requires MongoDB 5.0+.
The $dateToParts operator takes an object with a required date and optional options:
{
$dateToParts: {
date: <dateExpression>,
timezone: <stringExpression>,
iso8601: <booleanExpression>
}
}date — required; the BSON date to decompose (field, $$NOW, or literal).timezone — optional Olson timezone ID; parts reflect that zone instead of UTC.iso8601 — optional boolean; when true, also returns isoWeekYear, isoWeek, and isoDayOfWeek.year, month (1–12), day, hour, minute, second, millisecond.$dateFromParts.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | date |
| Return type | Document of integer parts |
| Month range | 1–12 (January = 1) |
| MongoDB version | 5.0+ |
{
$dateToParts: {
date: "$createdAt"
}
}UTC components
{
orderYear: {
$getField: {
field: "year",
input: {
$dateToParts: {
date: "$orderDate"
}
}
}
}
}Extract one part
{
$dateToParts: {
date: "$eventAt",
timezone: "America/New_York"
}
}Local calendar parts
{
$dateToParts: {
date: "$loggedAt",
iso8601: true
}
}isoWeekYear, isoWeek
Extract calendar parts from timestamps, report in local timezones, group sales by month, and use ISO week fields with $dateToParts.
Use an orders collection and extract year, month, and day from orderDate.
Suppose you have an orders collection with BSON date fields:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"item": "Laptop",
"orderDate": ISODate("2024-06-15T14:30:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"item": "Mouse",
"orderDate": ISODate("2024-03-22T09:15:00Z")
}
]Store the full parts object and flatten selected fields in $project:
db.orders.aggregate([
{
$project: {
item: 1,
orderDate: 1,
dateParts: {
$dateToParts: { date: "$orderDate" }
}
}
},
{
$project: {
item: 1,
orderYear: "$dateParts.year",
orderMonth: "$dateParts.month",
orderDay: "$dateParts.day"
}
}
])$dateToParts returns all time components in one object.timezone.$project or use dot notation in $group keys.Local timezone reporting, monthly aggregation, and ISO week analytics.
Extract calendar day as it appears in Eastern Time for regional dashboards:
db.events.aggregate([
{
$project: {
title: 1,
eventAt: 1,
localParts: {
$dateToParts: {
date: "$eventAt",
timezone: "America/New_York"
}
}
}
},
{
$project: {
title: 1,
localYear: "$localParts.year",
localMonth: "$localParts.month",
localDay: "$localParts.day",
localHour: "$localParts.hour"
}
}
])The same UTC instant can fall on different calendar days in different zones. Always set timezone when business reports use local dates rather than server UTC.
Use $dateToParts inside $group to bucket revenue by calendar month:
db.orders.aggregate([
{
$addFields: {
parts: { $dateToParts: { date: "$orderDate" } }
}
},
{
$group: {
_id: {
year: "$parts.year",
month: "$parts.month"
},
totalSales: { $sum: "$amount" },
orderCount: { $sum: 1 }
}
},
{ $sort: { "_id.year": 1, "_id.month": 1 } }
])Grouping on year and month from $dateToParts is cleaner than string formatting for analytics. Pair with $dateFromParts if you need month start/end boundaries.
Enable iso8601: true to get ISO week year and week number:
db.logs.aggregate([
{
$project: {
message: 1,
loggedAt: 1,
isoParts: {
$dateToParts: {
date: "$loggedAt",
iso8601: true
}
}
}
},
{
$project: {
message: 1,
isoWeekYear: "$isoParts.isoWeekYear",
isoWeek: "$isoParts.isoWeek",
isoDayOfWeek: "$isoParts.isoDayOfWeek"
}
}
])ISO week fields follow the ISO 8601 calendar (week 1 contains the first Thursday of the year). Use them for weekly KPIs that must align with international week numbering.
$dateFromParts.$dateToParts Worksdate is evaluated per document — a field, $$NOW, or literal ISODate.
MongoDB applies timezone and optional iso8601, then extracts calendar parts.
Integer fields like year and month are ready for projection, grouping, or matching.
Use in $group, $match, charts, or round-trip with $dateFromParts for custom date logic.
The $dateToParts operator is the standard way to break BSON dates into numeric components in MongoDB aggregation pipelines. It powers calendar-based grouping, local timezone reporting, and structured date transforms without string parsing.
Pair it with $dateFromParts when you need to rebuild dates from parts, or $dateToString when you need human-readable formatted output. Always specify timezone when reports must reflect local calendar days.
timezone for local calendar reportingyear and month for clean monthly analytics$dateFromPartsiso8601: true when ISO week numbering is required$dateToParts on MongoDB versions before 5.0$dateToParts with $dateFromPartstimezone$dateToParts — convert with $dateFromString first$dateToPartsUse these points when splitting dates into components in MongoDB.
Date → parts object.
Purposedate field.
Syntaxyear, month, day…
OutputLocal calendar parts.
OptionSplit vs build.
ImportantMove on to $dateToString to format dates as text, or review $dateFromParts to rebuild dates from components.
5 people found this page helpful