$dateToParts is a MongoDB aggregation expression that splits a BSON Date into numeric pieces—year, month, day, hour, minute, second, and millisecond—and returns them as one document.
Optionally set timezone for local calendar parts, or iso8601: true for ISO week fields.
Use dotted paths (for example "$parts.year") when you need one component.
Piece
Required?
Role
date
Yes
Date / Timestamp / ObjectId to split
timezone
No
Local parts instead of UTC
iso8601
No
true → ISO week-date fields
Pseudocode
Pseudocode
for each document:
d = evaluate(date)
if d is null or missing:
result = null
else:
result = {
year, month, day,
hour, minute, second, millisecond
} // or ISO week fields if iso8601 is true
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while splitting dates into parts.
We use one event with a start time. First we store it, then we split it into parts, then we project just year and month. Run these in mongosh after inserting the sample data once.
Example 1 — Sample Data
Imagine one event named Launch that starts at 2026-10-02 09:15 UTC. We save that Date in a collection named events.
Same split first.$dateToParts still builds the full parts document.
Pick fields with dotted paths."$parts.year" and "$parts.month" pull two integers out.
Shape the report.$project keeps only title, year, and month.
Easy check. October 2026 matches the original start date.
Edge Cases & Pitfalls
Check these before using $dateToParts in production pipelines.
type
Input must be a Date
String dates need $dateFromString first. $dateToParts does not parse text.
tz
Default parts are UTC
A late evening in New York can still be the next UTC day. Set timezone when reports must match local calendars.
iso
ISO week fields replace year/month/day
With iso8601: true, look for isoWeekYear / isoWeek / isoDayOfWeek—not year / month / day.
null
Null date becomes null
Missing or null dates return null, not an empty parts document. Handle them before grouping if needed.
Analysis
Performance Notes
Approach
Cost
Best for
$dateToParts alone
Per-document split
Reports that need several calendar fields
+ $project selected fields
Still O(docs)
Keeping only year/month for grouping
Single-field helpers ($year, …)
Often lighter
When you need only one component
Splitting dates is cheap compared with large sorts or joins. Filter early with $match when only some documents need parts.
Remember
Key Takeaways
Role: Date → document of integer parts.
Default:year, month, day, plus time fields (UTC).
Inverse: rebuild with $dateFromParts.
Access: use paths like "$parts.year" after the split.
One line:$dateToParts answers “what are the year, month, day, and time pieces of this Date?”
Frequently Asked Questions
$dateToParts breaks a BSON Date into numeric components such as year, month, day, hour, minute, second, and millisecond. It returns a document of integers, not a single number.
Use { $dateToParts: { date: <dateExpression>, timezone: <string>, iso8601: <boolean> } }. Only date is required. timezone and iso8601 are optional.
$dateToParts splits one Date into components. $dateFromParts builds one Date from components. They are inverse operations.
Instead of year/month/day, you get isoWeekYear, isoWeek, and isoDayOfWeek (plus the usual time fields). Use it for ISO week-date reporting.
By default parts are in UTC. Pass an Olson ID such as "America/New_York" to extract parts as they appear in that local zone.
Run $dateToParts, then read the year field with $getField, or project "parts.year". For a single field, $year is a shorter alternative.
