Docs Home → Develop Applications → MongoDB Manual
$toDate (aggregation)![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
$toDate
New in version 4.0.
Converts a value to a date. If the value cannot be converted to a date,
$toDate
errors. If the value is null or missing,$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" } } Tip
See also:
Behavior![](/docs/v5.2/assets/link.svg)
The following table lists the input types that can be converted to a date:
Input Type | Behavior |
---|---|
Double | Returns a date that corresponds to the number of milliseconds represented by the truncated double value. Positive number corresponds to the number of milliseconds since Jan 1, 1970. Negative number corresponds to the number of milliseconds before Jan 1, 1970. |
Decimal | Returns a date that corresponds to the number of milliseconds represented by the truncated decimal value. Positive number corresponds to the number of milliseconds since Jan 1, 1970. Negative number corresponds to the number of milliseconds before Jan 1, 1970. |
Long | Returns a date that corresponds to the number of milliseconds represented by the long value. Positive number corresponds to the number of milliseconds since Jan 1, 1970. Negative number corresponds to the number of milliseconds before Jan 1, 1970. |
String | Returns a date that corresponds to the date string. The string must be a valid date string, such as:
|
ObjectId | Returns a date that corresponds to the timestamp of the
ObjectId. |
Timestamp | Returns a date that corresponds to the timestamp. |
The following table lists some conversion to date examples:
Example | Results |
---|---|
{$toDate: 120000000000.5} | ISODate("1973-10-20T21:20:00Z") |
{$toDate: NumberDecimal("1253372036000.50")} | ISODate("2009-09-19T14:53:56Z") |
{$toDate: NumberLong("1100000000000")} | ISODate("2004-11-19T11:33:20Z") |
{$toDate: NumberLong("-1100000000000")} | ISODate("1935-02-22T12:26:40Z") |
{$toDate: ObjectId("5ab9c3da31c2ab715d421285")} | ISODate("2018-03-27T04:08:58Z") |
{$toDate: "2018-03-20"} | ISODate("2018-03-20T00:00:00Z") |
{$toDate: "2018-03-20 11:00:06 +0500"} | ISODate("2018-03-20T06:00:06Z") |
{$toDate: "Friday"} | Error |
{$toDate: Timestamp({ t: 1637688118, i: 1 })} | ISODate("2021-11-23T17:21:58.00Z") |
Example![](/docs/v5.2/assets/link.svg)
Create a collection orders
with the following documents:
db.orders.insertMany( [ { _id: 1, item: "apple", qty: 5, price: 2, order_date: new Date( "2018-03-20" ) }, { _id: 2, item: "pie", qty: 10, price: 3, order_date: new Date( "2018-03-22" ) }, { _id: 3, item: "ice cream", qty: 2, price: 4, order_date: "2018-03-15" }, { _id: 4, item: "almonds" , qty: 5, price: 7, order_date: "2018-03-15 +10:00" } ] )
The following aggregation operation on the orders
collection
converts 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: 7, order_date: '2018-03-15 +10:00', convertedDate: ISODate("2018-03-14T14:00:00.000Z") }, { _id: 3, item: 'ice cream', qty: 2, price: 4, order_date: '2018-03-15', convertedDate: ISODate("2018-03-15T00:00:00.000Z") }, { _id: 1, item: 'apple', qty: 5, price: 2, order_date: ISODate("2018-03-20T00:00:00.000Z"), convertedDate: ISODate("2018-03-20T00:00:00.000Z") }, { _id: 2, item: 'pie', qty: 10, price: 3, order_date: ISODate("2018-03-22T00:00:00.000Z"), convertedDate: ISODate("2018-03-22T00:00:00.000Z") }
Note
If the conversion operation encounters an error, the aggregation
operation stops and throws an error. To override this behavior, use
$convert
instead.