MongoDB $dateFromParts Operator

What Is $dateFromParts?

$dateFromParts is a MongoDB aggregation expression that builds a Date from separate numbers: year, month, day, and optional hour/minute/second. Use it when a document stores date pieces as fields instead of one Date.

$dateFromParts = Date from { year, month, day, ... }

{
  $dateFromParts: {
    year: <n>,          // required
    month: <n>,         // default 1
    day: <n>,           // default 1
    hour: <n>,          // default 0
    minute: <n>,        // default 0
    second: <n>,        // default 0
    millisecond: <n>,   // default 0
    timezone: "<tz>"    // optional
  }
}

inverse → $dateToParts

How to Use $dateFromParts in MongoDB

Point each part at a field (or literal), then emit one Date.

1. Choose an expression stage ($addFields or $project).
2. Set at least year (add month and day for a full calendar date).
3. Optionally set time parts and timezone.
4. Use the resulting Date with filters, sorts, or other date operators.

Pseudocode

for each document:
    y = evaluate(year)
    m = evaluate(month) or 1
    d = evaluate(day) or 1
    h, mi, s, ms = time parts or 0
    if year is null or missing:
        result = null
    else:
        result = Date(y, m, d, h, mi, s, ms)  // + timezone if set
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while building dates from parts.

Live Preview

Watch $dateFromParts turn year/month/day (and time) into one Date.

year = 2026, month = 1, day = 10
$dateFromParts → 2026-01-10T00:00:00.000Z

Worked Walkthrough — Event Date

An event stores year 2026, month 1, and day 10 as separate numbers. We want one Date field.

Document:
  { year: 2026, month: 1, day: 10 }

$dateFromParts:
  year  = 2026
  month = 1
  day   = 10
  (time defaults to 00:00:00.000)

Result → 2026-01-10T00:00:00.000Z ✓

MongoDB Examples

We use one event with numeric date parts. First build a date-only value, then include hour and minute. Run these in mongosh after inserting the sample data once.

db.events.insertOne({
  _id: 1,
  title: "Launch day",
  year: 2026,
  month: 1,
  day: 10,
  hour: 9,
  minute: 30
});

db.events.find()

[
  {
    _id: 1,
    title: "Launch day",
    year: 2026,
    month: 1,
    day: 10,
    hour: 9,
    minute: 30
  }
]

Parts                 Date

year  2026  ┐
month    1  ├─→  2026-01-10T00:00:00Z
day     10  ┘

+ hour 9, minute 30
  →  2026-01-10T09:30:00Z

db.events.aggregate([
  {
    $addFields: {
      eventDate: {
        $dateFromParts: {
          year: "$year",
          month: "$month",
          day: "$day"
        }
      }
    }
  }
]);

{
  _id: 1,
  title: "Launch day",
  year: 2026,
  month: 1,
  day: 10,
  hour: 9,
  minute: 30,
  eventDate: ISODate("2026-01-10T00:00:00Z")
}

db.events.aggregate([
  {
    $addFields: {
      eventAt: {
        $dateFromParts: {
          year: "$year",
          month: "$month",
          day: "$day",
          hour: "$hour",
          minute: "$minute"
        }
      }
    }
  }
]);

{
  _id: 1,
  title: "Launch day",
  year: 2026,
  month: 1,
  day: 10,
  hour: 9,
  minute: 30,
  eventAt: ISODate("2026-01-10T09:30:00Z")
}

Performance Notes

Building a Date is cheap. Filter early with $match when only some documents need assembly.

Key Takeaways