MongoDB $dayOfYear Operator

What You’ll Learn

The $dayOfYear operator extracts the day number within a year (1–366) from a BSON Date inside MongoDB aggregation pipelines. Use it for “day N of the year” analytics, seasonal reporting, cohort comparisons, and detecting trends across different years.

Definition and Usage

In MongoDB’s aggregation framework, the $dayOfYear operator takes a date expression and returns an integer between 1 and 366. For example, $dayOfYear applied to ISODate("2024-01-01T00:00:00Z") returns 1, and ISODate("2024-12-31T00:00:00Z") returns 366 because 2024 is a leap year.

📝 Syntax

The $dayOfYear operator takes a single date expression:

{ $dayOfYear: <dateExpression> }

Syntax Rules

• Argument — any expression that evaluates to a BSON Date (field, $$NOW, or literal).
• Return value — integer from 1 to 366 (leap years can return 366).
• Null input — returns null when the date is null or missing.
• Use inside $project, $addFields, $set, $match (with $expr), or $group.

Examples Gallery

Extract day-of-year values, filter early-year events, group activity by day index, and build timezone-aware day-of-year logic with $dayOfYear.

[
  {
    "_id": ObjectId("609c26812e9274a86871bc6a"),
    "name": "Kickoff",
    "eventAt": ISODate("2024-01-01T09:00:00Z")
  },
  {
    "_id": ObjectId("609c26812e9274a86871bc6b"),
    "name": "Campaign",
    "eventAt": ISODate("2024-03-01T12:00:00Z")
  }
]

db.events.aggregate([
  {
    $project: {
      name: 1,
      eventAt: 1,
      dayOfYear: { $dayOfYear: "$eventAt" }
    }
  }
])

{ "name": "Kickoff",  "dayOfYear": 1 }
{ "name": "Campaign", "dayOfYear": 61 }

db.events.find({
  $expr: {
    $lte: [
      { $dayOfYear: "$eventAt" },
      7
    ]
  }
})

db.users.aggregate([
  {
    $group: {
      _id: {
        year: { $year: "$createdAt" },
        dayOfYear: { $dayOfYear: "$createdAt" }
      },
      signups: { $sum: 1 }
    }
  },
  { $sort: { "_id.year": 1, "_id.dayOfYear": 1 } }
])

db.events.aggregate([
  {
    $addFields: {
      localParts: {
        $dateToParts: {
          date: "$eventAt",
          timezone: "America/Los_Angeles"
        }
      }
    }
  },
  {
    $addFields: {
      localDate: {
        $dateFromParts: {
          year: "$localParts.year",
          month: "$localParts.month",
          day: "$localParts.day",
          timezone: "America/Los_Angeles"
        }
      }
    }
  },
  {
    $project: {
      name: 1,
      eventAt: 1,
      dayOfYearLocal: { $dayOfYear: "$localDate" }
    }
  }
])

🚀 Use Cases

• Seasonality analysis — compare activity by day index across years.
• Campaign planning — measure performance around holidays or seasonal peaks.
• Time-window filters — pick “first N days” or “last N days” of the year.
• Data quality checks — validate expected patterns such as end-of-year processing (days 360+).

💡 Best Practices