$isoWeek (ISO Week Number)
Last updated: 2026-10-09
$isoWeek (ISO Week Number)
$isoWeek returns the ISO 8601 week number of a date (1 to 53). ISO weeks start on Monday, and week 1 is the week containing the first Thursday — unlike the US-style $week (Sunday start, may return 0). Great for international week-based stats; usually paired with $isoWeekYear to form a year-week key. timezone drives the week boundary.
| Category | Date |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $isoWeek: { date: <date-expression>, timezone: <timezone> } }⚙️ Parameters
| date | Required; the date expression. |
|---|---|
| timezone | Optional timezone; defaults to UTC. |
Returns：ISO week number (1-53); null if date is null.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $isoWeek: aggregate sales by ISO week
db.sales.aggregate([
{ $group: {
_id: { $isoWeek: { date: '$soldAt', timezone: 'Asia/Shanghai' } },
total: { $sum: '$amount' }
} }
])Output：
{ "_id": 39, "total": 9800 }
{ "_id": 40, "total": 10450 }📌 Notes
- ISO weeks start Monday; week 1 contains the year's first Thursday
- Unlike $week, $isoWeek never returns 0 — range is 1 to 53
- Usually paired with $isoWeekYear and $isoDayOfWeek for a full week key
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat is the return range?
A1 to 53 — never 0.
QWhat differs from $week?
A$week starts Sunday and may return 0; $isoWeek follows ISO 8601 starting Monday.
QHow do weeks spanning years count?
AISO assigns them to the year containing the Thursday; use $isoWeekYear for the right year.
