The $isoWeekYear operator extracts the ISO week-numbering year from a date. It answers “which ISO year owns this week?” — which can differ from the calendar year near January and December. Pair it with $isoWeek for accurate weekly reporting.
01
ISO Week Year
Year for ISO weeks.
02
Syntax
One date argument.
03
vs $year
Not always the same.
04
$group Stage
Year-week buckets.
05
Use Cases
Weekly KPI reports.
06
Pair $isoWeek
Complete week keys.
Fundamentals
Definition and Usage
In MongoDB’s aggregation framework, the $isoWeekYear operator takes a date expression and returns the ISO 8601 week-numbering year as an integer. This is the year that the ISO week belongs to — not necessarily the same as the calendar year shown on the date. For example, ISODate("2023-01-01T00:00:00Z") has calendar year 2023 but $isoWeekYear returns 2022 because that Sunday falls in ISO week 52 of 2022.
Use $isoWeekYear together with $isoWeek whenever you group, filter, or label data by week. Without it, week 1 in January could be mixed with week 1 from a different ISO year.
💡
Beginner Tip
Think of $year as “what year is on the calendar” and $isoWeekYear as “what ISO year owns this week.” For most mid-year dates they match; near January and December they often do not.
Foundation
📝 Syntax
The $isoWeekYear operator takes a single date expression:
mongosh
{ $isoWeekYear: <dateExpression> }
Syntax Rules
Argument — any expression that evaluates to a BSON Date.
Return value — integer year in the ISO week-numbering system (UTC).
Null input — returns null when the date is null or missing.
Use inside $project, $addFields, $match with $expr, or $group.
Always combine with $isoWeek for week-based grouping or filtering.
Using $isoWeekYear (not $year) in the label ensures 2024-12-30 displays as 2025-W01, matching international ISO week conventions.
Applications
🚀 Use Cases
Weekly KPI dashboards — group metrics by ISO year-week without boundary errors.
Year-boundary filtering — select events in a specific ISO week of a specific ISO year.
Data validation — compare $year vs $isoWeekYear to audit date-heavy imports.
ISO calendar pipelines — complete the trio with $isoWeek and $isoDayOfWeek.
🧠 How $isoWeekYear Works
1
MongoDB reads the date expression
The pipeline evaluates the input — a field like "$eventDate" or an ISODate literal.
Input
2
$isoWeekYear finds the ISO year
MongoDB determines which ISO week-numbering year contains the date’s ISO week, using ISO 8601 rules in UTC.
Calculate
3
The year integer is stored
The ISO week year is written to your output field or combined with $isoWeek in a $group key.
Output
=
📊
Accurate year-week data
You get correct ISO year identifiers for weekly reports, even across calendar year boundaries.
Wrap Up
Conclusion
The $isoWeekYear operator completes the ISO weekly calendar toolkit in MongoDB aggregation pipelines. It provides the correct year for ISO week grouping — essential whenever you use $isoWeek and especially critical for dates in early January or late December.
For beginners, remember: wrap any date expression in { $isoWeekYear: ... } and always pair it with $isoWeek for week-based keys. Do not substitute calendar $year when ISO week accuracy matters.
Always pair $isoWeekYear with $isoWeek in $group keys
Use both operators when filtering a specific ISO year-week
Compare with $year to audit boundary dates in imports
Sort weekly reports by ISO year then ISO week
Format labels as YYYY-Www using $isoWeekYear
❌ Don’t
Replace $isoWeekYear with calendar $year for weekly grouping
Filter by $isoWeek alone without the ISO year
Assume January dates belong to the same ISO year as the calendar
Use on string dates without converting to BSON Date first
Forget UTC when comparing with local-time business rules
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $isoWeekYear
Use these points for accurate ISO weekly reporting.
5
Core concepts
📅01
ISO Week Year
Year that owns the week.
Purpose
📝02
Simple Syntax
{ $isoWeekYear: date }
Syntax
🛠03
Pair $isoWeek
Complete week keys.
Usage
⚠04
vs $year
Differs at boundaries.
Important
📈05
$group Key
year + week together.
Pattern
❓ Frequently Asked Questions
$isoWeekYear returns the ISO 8601 week-numbering year for a BSON Date. It is the year that owns the ISO week containing the date — which can differ from the calendar year near January and December.
The syntax is { $isoWeekYear: <dateExpression> }. Pass a field reference like "$orderDate", a literal ISODate, or another expression that evaluates to a date.
$year returns the calendar year (e.g. 2023 for any date in 2023). $isoWeekYear returns the ISO week year — for example, 2023-01-01 can be ISO week year 2022 because it falls in week 52 of 2022.
Yes. Always pair them when grouping or filtering by week. Week 1 of ISO year 2024 and week 1 of ISO year 2025 are different buckets even though both are "week 1."
$isoWeekYear returns null when the input date is null or refers to a missing field. It does not throw an error.
