$month (Get Month)
Last updated: 2026-10-09
$month (Get Month)
$month returns the month of a date (1 to 12) — one of the most-used expressions for monthly reports. Pair it with $year as the $group key to build a year-month dimension. It returns an integer without zero padding; use %m of $dateToString for a two-digit string. timezone defines the month boundary and defaults to UTC — always set it for business monthly reports.
| Category | Date |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $month: { date: <date-expression>, timezone: <timezone> } }⚙️ Parameters
| date | Required; the date expression. |
|---|---|
| timezone | Optional timezone; defaults to UTC. |
Returns：The month (1-12); null if date is null.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $month + $year: order totals by month
db.orders.aggregate([
{ $group: {
_id: { y: { $year: { date: '$orderDate' } }, m: { $month: { date: '$orderDate' } } },
total: { $sum: '$amount' }
} }
])Output：
{ "_id": { "y": 2026, "m": 9 }, "total": 45600 }
{ "_id": { "y": 2026, "m": 10 }, "total": 52300 }📌 Notes
- January is 1, December is 12
- Always pair month with year — month alone mixes years
- Defaults to UTC — set timezone explicitly for monthly reports
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QDoes it return 1 to 12?
AYes — January is 1, December is 12.
QHow to output 2026-09 style strings?
AUse the %Y-%m format of $dateToString, or combine $month with $year manually.
QWhy is my monthly stats shifted?
AUsually a timezone issue — pass a local zone like Asia/Shanghai.
