$toDate (aggregation)

Definition

• $toDate

New in version 4.0.

Converts a value to a date. If the value cannot be convertedto a date, $toDate errors. If the value is null ormissing, $toDate returns null.

$toDate has the following syntax:

{
   $toDate: <expression>
}

The $toDate takes any valid expression.

The $toDate is a shorthand for the following$convert expression:

{ $convert: { input: <expression>, to: "date" } }

See also

$convert and $dateFromString

Behavior

The following table lists the input types that can be converted to adate:

The following table lists some conversion to date examples:

Example

Create a collection orders with the following documents:

db.orders.insert( [
   { _id: 1, item: "apple", qty: 5, order_date: new Date("2018-03-10") },
   { _id: 2, item: "pie", qty: 10,  order_date: new Date("2018-03-12")},
   { _id: 3, item: "ice cream", qty: 2, price: "4.99", order_date: "2018-03-05" },
   { _id: 4, item: "almonds" ,  qty: 5, price: 5,  order_date: "2018-03-05 +10:00"}
] )

The following aggregation operation on the orders collectionconverts the order_date to date before sorting by the date value:

// Define stage to add convertedDate field with the converted order_date value
 
dateConversionStage = {
   $addFields: {
      convertedDate: { $toDate: "$order_date" }
   }
};
 
// Define stage to sort documents by the converted date
 
sortStage = {
   $sort: { "convertedDate": 1 }
};
 
db.orders.aggregate( [
   dateConversionStage,
   sortStage
])

The operation returns the following documents:

{ "_id" : 4, "item" : "almonds", "qty" : 5, "price" : 5, "order_date" : "2018-03-05 +10:00", "convertedDate" : ISODate("2018-03-04T14:00:00Z") }
{ "_id" : 3, "item" : "ice cream", "qty" : 2, "price" : "4.99", "order_date" : "2018-03-05", "convertedDate" : ISODate("2018-03-05T00:00:00Z") }
{ "_id" : 1, "item" : "apple", "qty" : 5, "order_date" : ISODate("2018-03-10T00:00:00Z"), "convertedDate" : ISODate("2018-03-10T00:00:00Z") }
{ "_id" : 2, "item" : "pie", "qty" : 10, "order_date" : ISODate("2018-03-12T00:00:00Z"), "convertedDate" : ISODate("2018-03-12T00:00:00Z") }

Note

If the conversion operation encounters an error, the aggregationoperation stops and throws an error. To override this behavior, use$convert instead.