The $year operator extracts the calendar year from a BSON date inside MongoDB aggregation pipelines. Use it to group sales by year, filter documents from a specific year, or build year-month report keys with $month.
01
Extract Year
Date → 2024.
02
Syntax
One date argument.
03
$group Keys
Annual reports.
04
+$month
Year-month buckets.
05
+$week
Year-week keys.
06
vs $isoWeekYear
Calendar vs ISO.
Fundamentals
Definition and Usage
In MongoDB’s aggregation framework, the $year operator takes a date expression and returns an integer representing the calendar year. For example, $year on ISODate("2024-06-15T00:00:00Z") returns 2024.
This is one of the most common date operators for analytics. Combine it with $month for monthly trends, $week for weekly breakdowns, or use it alone to compare annual totals across years.
💡
Beginner Tip
$year returns the calendar year in UTC. For ISO week-based reporting where year boundaries differ, use $isoWeekYear with $isoWeek instead.
Foundation
📝 Syntax
The $year operator takes a single date expression:
mongosh
{ $year: <dateExpression> }
Common Patterns
mongosh
// Extract year from a field
{ $year: "$orderDate" }
// Group sales by year
{
$group: {
_id: { $year: "$orderDate" },
total: { $sum: "$amount" }
}
}
// Filter documents from 2024
{
$match: {
$expr: {
$eq: [ { $year: "$orderDate" }, 2024 ]
}
}
}
// Year + month grouping key
{
year: { $year: "$orderDate" },
month: { $month: "$orderDate" }
}
Syntax Rules
Argument — any expression that evaluates to a BSON Date.
Return value — integer calendar year (e.g. 2023, 2024) in UTC.
Null input — returns null when the date is null or missing.
Use inside $project, $addFields, $group, or $match with $expr.
Available in MongoDB 3.4+ aggregation and update pipelines with expressions.
💡 $year vs $isoWeekYear vs $month
$year — calendar year (wall-calendar year in UTC)
$isoWeekYear — ISO week-numbering year (can differ near Jan/Dec)
Use $year for standard calendar reporting. Use $isoWeekYear when your business follows ISO 8601 week numbering.
Applications
🚀 Use Cases
Annual revenue reports — group sales, sign-ups, or events by calendar year.
Year-over-year comparison — compare totals across consecutive years in dashboards.
Year filters — show only documents from the current or a selected year.
Composite time keys — combine with $month or $week for finer breakdowns.
Data partitioning logic — derive year labels for archival or export jobs.
🧠 How $year Works
1
MongoDB resolves the date
The input expression is evaluated per document — a field, literal ISODate, or nested date expression.
Input
2
Calendar year is extracted
MongoDB reads the UTC year component from the BSON date (e.g. 2024).
Extract
3
An integer is returned
The year is ready for $group, $match, or display in projected fields.
Output
=
📅
Year for time-based analytics
Combine with $month, $week, or $dayOfYear for richer reporting.
Wrap Up
Conclusion
The $year operator extracts the calendar year from BSON dates in MongoDB aggregation pipelines. It is essential for annual reports, year filters, and composite time keys with $month or $week.
Remember: results are in UTC, and ISO week reporting needs $isoWeekYear instead. Next in the series: $zip.
Use $year for standard calendar-year grouping and filtering
Pair with $month or $week for composite time keys
Store BSON dates for reliable year extraction
Use $dateToParts when timezone-aware years matter
Sort grouped results by year for chronological charts
❌ Don’t
Use $year for ISO week-year reporting (use $isoWeekYear)
Group by $week without also including $year
Assume local timezone — default extraction is UTC
Parse string dates directly — convert with $dateFromString first
Confuse $year with $dayOfYear (day 1–366 within a year)
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $year
Use these points when extracting years from dates in MongoDB.
5
Core concepts
📅01
Calendar Year
Date → 2024.
Purpose
📝02
One Argument
Date expression.
Syntax
🛠03
$group Key
Annual totals.
Pattern
🗃04
+ $month
Year-month keys.
Combine
⚠05
vs $isoWeekYear
Calendar vs ISO.
Compare
❓ Frequently Asked Questions
$year returns the calendar year (e.g. 2024) for a BSON Date. It is an aggregation expression operator used inside stages like $project, $addFields, and $group.
The syntax is { $year: <dateExpression> }. Pass a field reference like "$orderDate", a literal ISODate, or another expression that evaluates to a date.
$year returns the calendar year shown on a wall calendar. $isoWeekYear returns the ISO week-numbering year, which can differ near January and December when a date falls in week 52 or week 1 of an adjacent ISO year.
$year extracts the year in UTC. For timezone-aware year extraction, use $dateToParts with a timezone field and read the year component.
$year returns null when the input date is null or refers to a missing field. It does not throw an error.
