$isoWeekYear (ISO Week Year)
Last updated: 2026-10-09
$isoWeekYear (ISO Week Year)
$isoWeekYear returns the year to which a date's ISO week belongs, used with $isoWeek. Because ISO weeks can straddle years (Dec 31 may fall in week 1 of the next year), the week's year can differ from the calendar year — only $isoWeekYear gives the right ownership. Typical use: building a year-week grouping key. timezone drives the week boundary.
| Category | Date |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $isoWeekYear: { date: <date-expression>, timezone: <timezone> } }⚙️ Parameters
| date | Required; the date expression. |
|---|---|
| timezone | Optional timezone; defaults to UTC. |
Returns：The ISO week year; null if date is null.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $isoWeekYear + $isoWeek: year-week grouping
db.sales.aggregate([
{ $group: {
_id: { y: { $isoWeekYear: { date: '$soldAt' } }, w: { $isoWeek: { date: '$soldAt' } } },
total: { $sum: '$amount' }
} }
])Output：
{ "_id": { "y": 2026, "w": 39 }, "total": 9800 }
{ "_id": { "y": 2026, "w": 40 }, "total": 10450 }📌 Notes
- Around year boundaries, the ISO week year can differ from the calendar year by 1
- Use together with $isoWeek; alone it is of little value
- Defaults to UTC — unify timezone before stats
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat differs from $year?
A$year is the calendar year; $isoWeekYear is the week's ISO year — they can differ in straddling weeks.
QWhen do I need it?
AFor year-week grouping, combine $isoWeekYear with $isoWeek as the key.
QIs it useful alone?
ANot really — it only expresses week ownership together with $isoWeek.
