MongoDB $dateToString Operator

What Is $dateToString?

$dateToString is a MongoDB aggregation expression that formats a BSON Date as text using a format pattern such as "%Y-%m-%d". Use it for reports, exports, and display labels.

$dateToString = Date → formatted string

{ $dateToString: {
    date:     <dateExpression>,   // required
    format:   <string>,           // optional (common to set)
    timezone: <string>,           // optional (default UTC)
    onNull:   <expression>        // optional fallback
  }
}

common specs → %Y year, %m month, %d day,
               %H hour, %M minute, %S second

null / missing date → null (unless onNull is set)

How to Use $dateToString in MongoDB

Point at a Date field, choose a format pattern, then optionally set timezone or a null fallback.

1. Choose an expression stage ($addFields or $project).
2. Set date to a Date field (or Date expression).
3. Set format (for example "%Y-%m-%d" or "%d/%m/%Y %H:%M").
4. Optionally set timezone for local clock text, or onNull for missing dates.

Pseudocode

for each document:
    d = evaluate(date)
    if d is null or missing:
        result = onNull if set, else null
    else:
        result = format(d, formatPattern, timezone?)
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while formatting dates as strings.

Live Preview

Watch $dateToString turn a Date into text with different format patterns (UTC).

date = ISODate("2026-10-02T09:15:00.000Z")
format = "%Y-%m-%d"

$dateToString → "2026-10-02"

{ label: "2026-10-02" }

Worked Walkthrough — Date Label

An event starts at 2026-10-02T09:15:00Z. We want a simple display string: "2026-10-02".

Document:
  { starts_at: ISODate("2026-10-02T09:15:00.000Z") }

$dateToString: {
  date: "$starts_at",
  format: "%Y-%m-%d"
}

Step by step (UTC):
  %Y → 2026
  %m → 10
  %d → 02
  join with "-" → "2026-10-02"

Result:
  "2026-10-02"

MongoDB Examples

We use one event with a start time. First we store it, then we format a date-only label, then a date-and-time label. Run these in mongosh after inserting the sample data once.

db.events.insertOne({
  _id: 1,
  title: "Launch",
  starts_at: ISODate("2026-10-02T09:15:00.000Z")
});

db.events.find()

[
  {
    _id: 1,
    title: "Launch",
    starts_at: ISODate("2026-10-02T09:15:00.000Z")
  }
]

Date in → text out:

  starts_at = 2026-10-02T09:15:00.000Z

  format "%Y-%m-%d"      → "2026-10-02"
  format "%Y-%m-%d %H:%M" → "2026-10-02 09:15"

db.events.aggregate([
  {
    $addFields: {
      label: {
        $dateToString: {
          date: "$starts_at",
          format: "%Y-%m-%d"
        }
      }
    }
  }
]);

{
  _id: 1,
  title: "Launch",
  starts_at: ISODate("2026-10-02T09:15:00.000Z"),
  label: "2026-10-02"
}

db.events.aggregate([
  {
    $addFields: {
      when_label: {
        $dateToString: {
          date: "$starts_at",
          format: "%Y-%m-%d %H:%M"
        }
      }
    }
  }
]);

{
  _id: 1,
  title: "Launch",
  starts_at: ISODate("2026-10-02T09:15:00.000Z"),
  when_label: "2026-10-02 09:15"
}

Performance Notes

Formatting is cheap compared with large sorts or joins. Prefer keeping a real Date for filtering, and format late in the pipeline for display. Filter early with $match when only some rows need a label.

Key Takeaways