$week (Get Week Number)
Last updated: 2026-10-09
$week (Get Week Number)
$week returns the US-style week number of a date (0 to 53): weeks start on Sunday, week 1 begins with the year's first Sunday, and earlier dates fall in week 0. It differs from the ISO-standard $isoWeek; prefer $isoWeek for international stats. It returns an integer; timezone drives the week boundary and defaults to UTC.
| Category | Date |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $week: { date: <date-expression>, timezone: <timezone> } }⚙️ Parameters
| date | Required; the date expression. |
|---|---|
| timezone | Optional timezone; defaults to UTC. |
Returns：The week number (0-53); null if date is null.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $week: aggregate sales by US-style week
db.sales.aggregate([
{ $group: {
_id: { $week: { date: '$soldAt', timezone: 'Asia/Shanghai' } },
total: { $sum: '$amount' }
} }
])Output：
{ "_id": 38, "total": 8300 }
{ "_id": 39, "total": 9800 }📌 Notes
- Weeks start Sunday; dates before the year's first Sunday are week 0
- Unlike $isoWeek: that starts Monday and has no week 0
- Pair with year — straddling weeks are ambiguous, use $year to disambiguate
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhy does 0 appear?
ADates between Jan 1 and the first Sunday fall in week 0.
QWhich suits international business, $week or $isoWeek?
AUse $isoWeek for international business; $week is the US convention.
QWhat is the maximum?
A0 to 53, unlike $isoWeek's 1 to 53.
