The $week operator extracts the week of the year (0–53) from a BSON date inside MongoDB aggregation pipelines. Use it to build weekly sales reports, group events by calendar week, or filter documents from a specific week.
Date → 0–53.
One date argument.
MongoDB calendar.
Year + week keys.
Weekly reports.
ISO vs MongoDB.
In MongoDB’s aggregation framework, the $week operator takes a date expression and returns an integer from 0 to 53 representing the week of the year. MongoDB weeks start on Sunday, and week 1 is the week that contains the first Sunday of the year.
This is useful for weekly dashboards, trend analysis, and grouping time-series data when your organization follows a Sunday-based calendar. For ISO 8601 week numbering (Monday start), use $isoWeek instead.
Week numbers repeat every year, so always combine $week with $year when grouping. Otherwise, week 10 from 2023 and week 10 from 2024 land in the same bucket.
The $week operator takes a single date expression:
{ $week: <dateExpression> }// Extract week from a field
{ $week: "$orderDate" }
// Group by year and week
{
$group: {
_id: {
year: { $year: "$orderDate" },
week: { $week: "$orderDate" }
},
total: { $sum: "$amount" }
}
}
// Filter a specific week
{
$match: {
$expr: {
$and: [
{ $eq: [ { $year: "$orderDate" }, 2024 ] },
{ $eq: [ { $week: "$orderDate" }, 25 ] }
]
}
}
}Date.null when the date is null or missing.$project, $addFields, $group, or $match with $expr.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date extraction) |
| Syntax | { $week: <dateExpression> } |
| Return type | Integer (0–53) |
| Week starts on | Sunday |
| Pair with | $year for unique year-week keys |
| MongoDB version | 3.4+ |
{
$week: "$orderDate"
}Week of orderDate
{
year: { $year: "$d" },
week: { $week: "$d" }
}Group key pattern
{
$week: ISODate("2024-06-15")
}Returns week number
nullReturns null
Extract week numbers, group sales by year and week, filter a specific week, and compare with $isoWeek using an orders collection.
Add a week number field from orderDate with $project.
Suppose you have an orders collection with order timestamps:
[
{
"_id": 1,
"customer": "Alice",
"orderDate": ISODate("2024-06-10T14:30:00Z"),
"amount": 120.00
},
{
"_id": 2,
"customer": "Bob",
"orderDate": ISODate("2024-06-15T09:00:00Z"),
"amount": 85.50
},
{
"_id": 3,
"customer": "Carol",
"orderDate": ISODate("2024-06-17T16:45:00Z"),
"amount": 210.00
}
]Add the week number alongside each order:
db.orders.aggregate([
{
$project: {
customer: 1,
orderDate: 1,
amount: 1,
orderWeek: { $week: "$orderDate" },
orderYear: { $year: "$orderDate" }
}
}
])$week returns the Sunday-based week number. Including $year alongside it makes the result easier to interpret in reports.
Group revenue by week, filter a specific week, and compare calendar systems.
Build a weekly revenue summary:
db.orders.aggregate([
{
$group: {
_id: {
year: { $year: "$orderDate" },
week: { $week: "$orderDate" }
},
orderCount: { $sum: 1 },
totalRevenue: { $sum: "$amount" }
}
},
{
$sort: {
"_id.year": 1,
"_id.week": 1
}
}
])
// Example bucket:
// { _id: { year: 2024, week: 24 }, orderCount: 5, totalRevenue: 1250.00 }Combining $year and $week in _id creates a unique key for each calendar week. Without $year, weeks from different years would merge incorrectly.
Find all orders from week 25 of 2024:
db.orders.aggregate([
{
$match: {
$expr: {
$and: [
{ $eq: [ { $year: "$orderDate" }, 2024 ] },
{ $eq: [ { $week: "$orderDate" }, 25 ] }
]
}
}
},
{
$project: {
customer: 1,
orderDate: 1,
amount: 1
}
}
])$expr lets you use date expressions inside $match. Always filter by both year and week to avoid pulling data from the same week number in other years.
Create a readable week label for dashboards:
db.orders.aggregate([
{
$group: {
_id: {
year: { $year: "$orderDate" },
week: { $week: "$orderDate" }
},
totalRevenue: { $sum: "$amount" }
}
},
{
$project: {
weekLabel: {
$concat: [
{ $toString: "$_id.year" },
"-W",
{ $toString: "$_id.week" }
]
},
totalRevenue: 1
}
},
{ $sort: { weekLabel: 1 } }
])
// weekLabel: "2024-W24" → totalRevenue: 1250.00Pair $week with $concat and $toString to produce human-readable labels like 2024-W24 for charts and exports.
See how MongoDB calendar weeks differ from ISO weeks on the same dates:
db.orders.aggregate([
{
$project: {
orderDate: 1,
mongoWeek: { $week: "$orderDate" },
isoWeek: { $isoWeek: "$orderDate" }
}
}
])
// Dates near year boundaries or Mondays can show
// different week numbers between $week and $isoWeek$week uses Sunday-based weeks; $isoWeek uses ISO 8601 Monday-based weeks. Pick one convention and use it consistently across your reports.
Test week extraction on a fixed ISODate:
db.orders.aggregate([
{
$project: {
demo: {
$week: ISODate("2024-01-01T00:00:00Z")
}
}
}
])
// January 1, 2024 was a Monday.
// $week returns 0 because the first Sunday of 2024
// had not yet occurred in MongoDB's calendar.Early January dates often fall in week 0 because MongoDB week 1 starts on the first Sunday. This is why pairing with $year and understanding the calendar rules matters.
$week WorksThe input expression is evaluated per document — a field, literal ISODate, or nested date expression.
MongoDB counts weeks from the first Sunday of the year in UTC, returning 0–53.
The week number is ready for $group, $match, or display in projected fields.
Combine with $year, $month, or $isoWeek for richer calendar logic.
The $week operator extracts week-of-year numbers from BSON dates in MongoDB aggregation pipelines. Its Sunday-based calendar and 0–53 range are the key details to remember when building weekly reports.
Always pair $week with $year when grouping. For ISO Monday-based weeks, use $isoWeek and $isoWeekYear. Next in the series: $where.
$week with $year in $group keys$isoWeek when your team expects ISO 8601 numbering$week alone without $year$week with $dayOfWeek (weekday 1–7)$week and $isoWeek in one dashboard without labels$dateFromString first$weekUse these points when extracting weeks from dates in MongoDB.
Date → 0–53.
PurposeDate expression.
SyntaxWeek 1 = 1st Sun.
CalendarUnique week keys.
PatternISO Monday weeks.
CompareMove on to $where for JavaScript-based filtering, or review $isoWeek for ISO calendar weeks.
5 people found this page helpful