$isoWeekYear is a MongoDB aggregation expression that returns the ISO 8601 week-numbering year for a date—the year that owns the ISO week containing that date. Near year boundaries it can differ from the calendar $year.
Remember
$isoWeekYear = year that owns the ISO week
{ $isoWeekYear: <dateExpression> }
or
{ $isoWeekYear: { date: <date>, timezone: "<tz>" } }
2025-12-29 → isoWeekYear 2026 (week 1)
calendar $year → 2025
null / missing → null
always pair with $isoWeek for keys
Pass a Date field (for example "$orderDate") to $isoWeekYear.
Also extract $isoWeek when you need a full year-week key.
Optionally set timezone when the local calendar day matters.
Piece
Required?
Role
Date expression
Yes
Source Date to inspect
timezone
No
Interpret the date in a named zone
$isoWeek
Recommended
Week half of the ISO key
Pseudocode
Pseudocode
for each document:
d = evaluate(dateExpression)
if d is null or missing:
result = null
else:
week = ISO_8601_week(d)
result = year that owns that week
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while building ISO year-week keys.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $isoWeekYear: <date> }
vs $year
Week-year vs calendar year
Boundary tip
Late Dec / early Jan may disagree
Pair with
$isoWeek
Report key
2026-W01 style labels
Sample check
2025-12-29 → ISO year 2026
Try it
Live Preview
Watch $isoWeekYear (and calendar $year) for dates near the year boundary.
An order was placed on Monday, 2025-12-29. That day is still calendar 2025, but it starts ISO week 1 of 2026.
Calculation
Document:
{ order: "Notebook", orderDate: 2025-12-29 }
Calendar year ($year):
2025
ISO week containing this Monday:
2025-12-29 … 2026-01-04 → week 1 of 2026
$isoWeekYear → 2026
$isoWeek → 1
Report key: 2026-W01 ✓
Code
MongoDB Examples
We use one boundary order date. First extract the ISO week-year, then compare it with calendar $year and add $isoWeek. Run these in mongosh after inserting the sample data once.
Example 1 — Sample Data
Imagine one order placed on 2025-12-29 (a Monday at the year boundary). We save it in a collection named orders.
Same stored document. Still using orderDate: 2025-12-29 from Example 1.
Calendar vs ISO.$year stays 2025; $isoWeekYear jumps to 2026.
Complete key. With $isoWeek = 1, the report label is 2026-W01.
Edge Cases & Pitfalls
Check these before using $isoWeekYear in production pipelines.
boundary
Do not assume it equals $year
Late December and early January are the danger zone. Always verify week-year near those dates.
pair
Week alone is not unique
“Week 1” repeats every year. Pair with $isoWeek for unique buckets.
tz
Timezone can flip the day
A UTC evening may be the next local morning. Set timezone when reports follow a local calendar.
null
Null dates stay null
Missing or null dates return null. Validate dates before grouping by week-year.
Analysis
Performance Notes
Approach
Cost
Best for
$isoWeekYear per document
Cheap date extract
Weekly keys on the fly
Group by year + week
Extract + group
ISO weekly rollups
Store key on write
No recompute
Hot weekly dashboards
Year extraction is cheap. Filter early with $match when only some documents need a week-year.
Remember
Key Takeaways
Role: year that owns the ISO week.
vs $year: can differ near Dec/Jan.
Pairing: always use with $isoWeek for keys.
Sample: 2025-12-29 → ISO year 2026, week 1.
One line:$isoWeekYear answers “which year owns this date’s ISO week?”—not always the calendar year.
Frequently Asked Questions
$isoWeekYear returns the ISO 8601 week-numbering year for a date—the year that owns the ISO week containing that date. Use it inside aggregation stages such as $project, $addFields, and $group.
Use { $isoWeekYear: <dateExpression> }, or { $isoWeekYear: { date: <dateExpression>, timezone: <tz> } }. Pass a Date field, ISODate literal, or any expression that resolves to a date.
$year is the calendar year printed on the date. $isoWeekYear is the year of the ISO week. Near late December and early January they can disagree—for example 2025-12-29 can be ISO week-year 2026.
Yes. Week 1 of 2025 and week 1 of 2026 are different buckets. Pair both operators for correct year-week keys.
$isoWeekYear returns null when the input is null or the field is missing.
Usually only near year boundaries. If a date’s ISO week belongs mostly to the other calendar year, $isoWeekYear follows the week, not the printed calendar year.
