MongoDB $month Operator

What You’ll Learn

The $month operator extracts the month (1–12) from a BSON Date inside MongoDB aggregation pipelines. Use it for seasonal sales reports, monthly dashboards, quarter filters, and year-over-year month comparisons.

Definition and Usage

In MongoDB’s aggregation framework, the $month operator takes a date expression and returns an integer from 1 to 12. For example, $month applied to ISODate("2024-06-15T14:30:00Z") returns 6 (June), and ISODate("2024-12-31T23:59:59Z") returns 12 (December).

Unlike JavaScript’s Date.getMonth(), which is 0-based (January = 0), MongoDB’s $month is 1-based. January is always 1 and December is always 12.

📝 Syntax

The $month operator takes a date expression, or an object with date and timezone:

{ $month: <dateExpression> }

// With timezone:
{
  $month: {
    date: <dateExpression>,
    timezone: <tz>
  }
}

Syntax Rules

• Argument — any expression that evaluates to a BSON Date (field, $$NOW, or literal).
• Return value — integer from 1 to 12 (January = 1, December = 12).
• Null input — returns null when the date is null or missing.
• Timezone — optional; use Olson timezone IDs like "America/New_York".
• Use inside $project, $addFields, $set, $match (with $expr), or $group.

Examples Gallery

Extract month values, filter seasonal date ranges, group sales by month, and read months in a local timezone.

[
  {
    "_id": ObjectId("609c26812e9274a86871bc6a"),
    "product": "Winter Jacket",
    "amount": 120,
    "orderedAt": ISODate("2024-01-15T10:00:00Z")
  },
  {
    "_id": ObjectId("609c26812e9274a86871bc6b"),
    "product": "Beach Towel",
    "amount": 25,
    "orderedAt": ISODate("2024-07-20T14:30:00Z")
  },
  {
    "_id": ObjectId("609c26812e9274a86871bc6c"),
    "product": "Gift Card",
    "amount": 50,
    "orderedAt": ISODate("2024-12-01T09:00:00Z")
  }
]

db.orders.aggregate([
  {
    $project: {
      product: 1,
      amount: 1,
      orderedAt: 1,
      month: { $month: "$orderedAt" }
    }
  }
])

{ "product": "Winter Jacket", "month": 1 }
{ "product": "Beach Towel",   "month": 7 }
{ "product": "Gift Card",     "month": 12 }

db.orders.find({
  $expr: {
    $in: [
      { $month: "$orderedAt" },
      [ 6, 7, 8 ]
    ]
  }
})

{ "product": "Beach Towel", "orderedAt": "2024-07-20T14:30:00.000Z" }

db.orders.aggregate([
  {
    $group: {
      _id: { $month: "$orderedAt" },
      totalRevenue: { $sum: "$amount" },
      orderCount: { $sum: 1 }
    }
  },
  { $sort: { "_id": 1 } }
])

db.orders.aggregate([
  {
    $project: {
      product: 1,
      orderedAt: 1,
      monthUtc: { $month: "$orderedAt" },
      monthPacific: {
        $month: {
          date: "$orderedAt",
          timezone: "America/Los_Angeles"
        }
      }
    }
  }
])

// orderedAt: 2024-01-01T06:00:00Z
// monthUtc: 1, monthPacific: 12 (still Dec 31 locally)

db.orders.aggregate([
  {
    $group: {
      _id: {
        year: { $year: "$orderedAt" },
        month: { $month: "$orderedAt" }
      },
      totalRevenue: { $sum: "$amount" }
    }
  },
  { $sort: { "_id.year": 1, "_id.month": 1 } }
])

🚀 Use Cases

• Seasonal analysis — compare summer vs winter sales using month ranges.
• Monthly dashboards — group revenue or events by month of year.
• Quarter filters — select Q1–Q4 using month ranges (1–3, 4–6, etc.).
• Subscription billing — identify renewal months or anniversary dates.

💡 Best Practices