MongoDB $toDate Operator

What You’ll Learn

The $toDate operator converts values to a BSON Date (ISODate) in MongoDB aggregation pipelines. Use it to parse ISO date strings, Unix millisecond timestamps, and ObjectIds into proper date types for sorting and filtering.

Definition and Usage

In MongoDB’s aggregation framework, the $toDate operator converts an expression to a BSON Date value. Imported CSV and JSON data often stores dates as strings like "2024-06-15T10:30:00Z" or as Unix millisecond numbers. $toDate turns those into real dates so you can sort chronologically, filter by range, and group by month or year.

$toDate is shorthand for { $convert: { input: <expression>, to: "date" } }. It is part of the same type-conversion family as $toBool, $toInt, and $toString.

📝 Syntax

The $toDate operator takes one expression:

{ $toDate: <expression> }

Literal Examples

{ $toDate: "2024-06-15T10:30:00Z" }
// Result: ISODate("2024-06-15T10:30:00.000Z")

{ $toDate: 1718448600000 }
// Result: ISODate from Unix milliseconds

{ $toDate: "$dateString" }
// Convert the dateString field

{ $toDate: "$_id" }
// ObjectId → creation timestamp as Date

Conversion Rules

• null — returns null.
• Date — returns the same date value.
• String — parses ISO-8601 date strings (invalid strings cause an error).
• Number — treats the value as milliseconds since the Unix epoch.
• ObjectId — extracts the embedded creation timestamp.
• Timestamp — converts to a Date value.
• Use inside $project, $addFields, or $set.

Examples Gallery

Parse ISO date strings, convert Unix timestamps, extract ObjectId creation times, and sort events chronologically.

[
  {
    "_id": 1,
    "title": "Product Launch",
    "dateString": "2024-06-15T10:30:00Z"
  },
  {
    "_id": 2,
    "title": "Team Meeting",
    "dateString": "2024-03-20T14:00:00Z"
  },
  {
    "_id": 3,
    "title": "Year-End Review",
    "dateString": "2024-12-01T09:00:00Z"
  }
]

db.events.aggregate([
  {
    $project: {
      title: 1,
      dateString: 1,
      eventDate: { $toDate: "$dateString" }
    }
  }
])

{ "_id": 1, "title": "Product Launch",  "dateString": "2024-06-15T10:30:00Z", "eventDate": ISODate("2024-06-15T10:30:00.000Z") }
{ "_id": 2, "title": "Team Meeting",    "dateString": "2024-03-20T14:00:00Z", "eventDate": ISODate("2024-03-20T14:00:00.000Z") }
{ "_id": 3, "title": "Year-End Review", "dateString": "2024-12-01T09:00:00Z", "eventDate": ISODate("2024-12-01T09:00:00.000Z") }

db.logs.aggregate([
  {
    $project: {
      message: 1,
      loggedAt: { $toDate: "$timestampMs" }
    }
  }
])

// timestampMs: 1718448600000
// → loggedAt: ISODate("2024-06-15T10:30:00.000Z")

db.orders.aggregate([
  {
    $project: {
      orderId: "$_id",
      createdAt: { $toDate: "$_id" }
    }
  }
])

// ObjectId("665a1b2c3d4e5f6789012345")
// → createdAt: ISODate from embedded timestamp

db.events.aggregate([
  {
    $addFields: {
      eventDate: { $toDate: "$dateString" }
    }
  },
  {
    $sort: { eventDate: 1 }
  },
  {
    $project: {
      title: 1,
      eventDate: 1
    }
  }
])

// Sorted earliest to latest:
{ "title": "Team Meeting",    "eventDate": ISODate("2024-03-20T14:00:00.000Z") }
{ "title": "Product Launch",  "eventDate": ISODate("2024-06-15T10:30:00.000Z") }
{ "title": "Year-End Review", "eventDate": ISODate("2024-12-01T09:00:00.000Z") }

db.events.aggregate([
  {
    $addFields: {
      eventDate: { $toDate: "$dateString" }
    }
  },
  {
    $match: {
      eventDate: {
        $gte: ISODate("2024-06-01T00:00:00Z"),
        $lt:  ISODate("2024-07-01T00:00:00Z")
      }
    }
  },
  {
    $project: { title: 1, eventDate: 1 }
  }
])

// Returns only June 2024 events

db.events.aggregate([
  {
    $project: {
      title: 1,
      eventDate: {
        $convert: {
          input: "$dateString",
          to: "date",
          onError: null,
          onNull: null
        }
      }
    }
  }
])

// "2024-06-15T10:30:00Z" → ISODate(...)
// "not-a-date"           → null (no pipeline error)

🚀 Use Cases

• CSV/JSON import cleanup — parse date strings stored as text into proper BSON dates.
• Chronological sorting — convert before $sort to avoid incorrect string ordering.
• Date range queries — enable $gte/$lt filters on imported date fields.
• ObjectId analysis — extract document creation time from _id without a separate timestamp field.
• Reporting and grouping — prepare dates for $dateTrunc, $dateToString, or monthly rollups.

💡 Best Practices