MongoDB $dayOfYear Operator

What Is $dayOfYear?

$dayOfYear is a MongoDB aggregation expression that returns the day number within the year for a date as an integer from 1 to 366. January 1 is 1; December 31 is 365 or 366 in a leap year.

$dayOfYear = day number inside the year

{ $dayOfYear: <dateExpression> }
{ $dayOfYear: { date: <date>, timezone: <tz> } }

Jan 1      → 1
Feb 29     → 60   (leap years only)
Dec 31     → 365 or 366

default timezone → UTC
string date → error
null / missing → null

How to Use $dayOfYear in MongoDB

Pass a date field (or date + timezone), then filter or group on the day number if needed.

1. Choose an expression stage ($project or $addFields).
2. Ensure the argument is a Date / Timestamp / ObjectId (not a plain string).
3. Pass that expression to $dayOfYear (add timezone when you need a local calendar day).
4. Optionally filter ranges with $match (for example late-year days).

Pseudocode

for each document:
    d = evaluate(dateExpression)   // Date / Timestamp / ObjectId
    if d is null or missing:
        result = null
    else if d is a string:
        error
    else:
        // optional timezone shifts the calendar day first
        result = dayNumberInYear(d)   // 1 … 366
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while extracting day-of-year values.

Live Preview

Watch $dayOfYear turn a UTC date into a day number inside the year.

when = 2024-02-29T12:00:00.000Z
$dayOfYear → 60

{ title: "Leap Day", dayOfYear: 60 }

Worked Walkthrough — Why Leap Day Is 60

In 2024 (a leap year), February 29 is the 60th day. March 1 becomes day 61—one later than in a non-leap year.

UTC date: 2024-02-29T12:00:00Z

Days before Feb 29 in a leap year:
  Jan (31) + Feb 1–28 (28) = 59
  Feb 29 is the next day → 60

$dayOfYear(...) → 60

Compare:
  2023-03-01 → day 60   (no Feb 29)
  2024-03-01 → day 61   (leap day pushed March forward)
  2024-12-31 → day 366

MongoDB Examples

We store three 2024 dates (New Year, leap day, year end), extract the day-of-year, then keep late-year events. Run these in mongosh after inserting the sample data once.

db.milestones.insertMany([
  { _id: 1, title: "New Year", when: ISODate("2024-01-01T12:00:00Z") },
  { _id: 2, title: "Leap Day", when: ISODate("2024-02-29T12:00:00Z") },
  { _id: 3, title: "Year End", when: ISODate("2024-12-31T12:00:00Z") }
]);

db.milestones.find()

[
  { _id: 1, title: "New Year", when: ISODate("2024-01-01T12:00:00Z") },
  { _id: 2, title: "Leap Day", when: ISODate("2024-02-29T12:00:00Z") },
  { _id: 3, title: "Year End", when: ISODate("2024-12-31T12:00:00Z") }
]

Expected $dayOfYear (UTC, leap year 2024):

  New Year  2024-01-01 → 1
  Leap Day  2024-02-29 → 60
  Year End  2024-12-31 → 366

db.milestones.aggregate([
  {
    $project: {
      title: 1,
      dayOfYear: { $dayOfYear: "$when" },
      _id: 0
    }
  }
]);

{ title: "New Year", dayOfYear: 1 }
{ title: "Leap Day", dayOfYear: 60 }
{ title: "Year End", dayOfYear: 366 }

db.milestones.aggregate([
  {
    $addFields: {
      dayOfYear: { $dayOfYear: "$when" }
    }
  },
  {
    $match: {
      dayOfYear: { $gte: 300 }
    }
  },
  {
    $project: {
      title: 1,
      dayOfYear: 1,
      _id: 0
    }
  }
]);

{ title: "Year End", dayOfYear: 366 }

Performance Notes

Date extraction is cheap compared with large joins. Prefer an early date-range $match when you only need one year of data.

Key Takeaways