The $isoWeek operator extracts the ISO 8601 week number (1–53) from a date. Use it in aggregation pipelines to build weekly sales reports, group events by ISO week, or filter records for a specific week of the year.
01
ISO Week Number
Date → integer 1–53.
02
Syntax
One date argument.
03
Monday Start
ISO 8601 calendar.
04
$group Stage
Weekly aggregations.
05
Use Cases
Reports, dashboards.
06
Pair $isoWeekYear
Year-week keys.
Fundamentals
Definition and Usage
In MongoDB’s aggregation framework, the $isoWeek operator takes a date expression and returns the ISO 8601 week number as an integer from 1 to 53. ISO weeks start on Monday, and week 1 is the first week that contains a Thursday (the week that includes January 4). For example, $isoWeek on ISODate("2024-06-17T00:00:00Z") returns 25.
Weekly business reports often use ISO week numbers because they align with international standards. Combine $isoWeek with $isoWeekYear when you need a unique year-week identifier, especially for dates near January or December where the ISO week may belong to a different calendar year.
💡
Beginner Tip
Do not use calendar month alone when you need “week of year” reporting. ISO week boundaries do not match month boundaries. For example, January 1 can fall in week 52 or 53 of the previous ISO year.
Foundation
📝 Syntax
The $isoWeek operator takes a single date expression:
mongosh
{ $isoWeek: <dateExpression> }
Syntax Rules
Argument — any expression that evaluates to a BSON Date.
Return value — integer 1 through 53 (ISO week number in UTC).
Null input — returns null when the date is null or missing.
Use inside $project, $addFields, $match with $expr, or $group.
Pair with $isoWeekYear for complete ISO year-week grouping.
💡 Year Boundary Edge Cases
Calendar year and ISO week year can differ near January and December:
The padded week number (e.g. W05) follows common ISO week label formats like 2024-W25. This prevents collisions when the same week number appears in different ISO years.
Grouping by both $isoWeek and $isoWeekYear produces accurate weekly buckets even when dates span year boundaries. This is the standard pattern for weekly KPI dashboards.
Bonus — Year Boundary Example
See how a January date can belong to the previous ISO year’s final week:
January 1, 2023 was a Sunday and falls in ISO week 52 of 2022. Using $year alone would mis-group this event. Always pair $isoWeek with $isoWeekYear near year boundaries.
Applications
🚀 Use Cases
Weekly sales reports — group revenue, orders, or signups by ISO week for trend analysis.
Operations dashboards — compare week-over-week metrics using standard ISO week numbers.
Time-based filtering — isolate events or transactions for a specific week of the year.
ISO calendar pipelines — combine with $isoDayOfWeek and $isoWeekYear for full weekly analysis.
🧠 How $isoWeek Works
1
MongoDB reads the date expression
The pipeline evaluates the input — a field like "$orderDate" or an ISODate literal.
Input
2
$isoWeek applies ISO 8601 rules
MongoDB determines which Monday-starting week the date falls in and assigns the ISO week number (1–53).
Calculate
3
The week number is stored
The integer is written to your output field or used as part of a $group key for weekly aggregation.
Output
=
📊
Weekly reporting data
You get standard ISO week numbers ready for grouping, filtering, and dashboard charts.
Wrap Up
Conclusion
The $isoWeek operator is essential for ISO 8601 weekly reporting in MongoDB aggregation pipelines. It turns dates into week numbers 1–53, enabling clean weekly grouping and filtering without manual date math.
For beginners, the key idea is simple: wrap any date expression in { $isoWeek: ... } inside a stage like $project or $group. Always pair it with $isoWeekYear when dates may fall near January or December, and remember that ISO weeks start on Monday.
Use ISO week numbers for international weekly reports
Sort by year then week when displaying weekly time series
Filter with $expr and $eq for specific weeks
Combine with $isoDayOfWeek for day-within-week analysis
❌ Don’t
Use calendar $month alone when you need ISO week grouping
Assume week 1 always starts on January 1
Forget year-boundary edge cases in January and December
Use on string dates without converting to BSON Date first
Confuse $isoWeek with $week (non-ISO numbering)
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $isoWeek
Use these points when building weekly reports in MongoDB.
5
Core concepts
📅01
ISO Week
Integer 1–53.
Purpose
📝02
Simple Syntax
{ $isoWeek: date }
Syntax
🛠03
$group Weekly
Revenue by week.
Usage
📈04
+ $isoWeekYear
Unique year-week key.
Pattern
⚠05
Year Edges
Jan/Dec can surprise.
Edge case
❓ Frequently Asked Questions
$isoWeek returns the ISO 8601 week number (1–53) for a BSON Date. It is an aggregation expression operator used inside stages like $project, $addFields, and $group.
The syntax is { $isoWeek: <dateExpression> }. Pass a field reference like "$orderDate", a literal ISODate, or another expression that evaluates to a date.
ISO weeks start on Monday. Week 1 is the first week of the year that contains a Thursday (equivalently, the week containing January 4). Some dates near year boundaries belong to week 52 or 53 of the previous year, or week 1 of the next.
Yes, when grouping or filtering by week. A date in early January might be ISO week 1 of the new year while still being in the previous calendar year, or vice versa. Pair both operators for accurate year-week keys.
$isoWeek returns null when the input date is null or refers to a missing field. It does not throw an error.
