> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $toDate (expression operator)

## Definition

Converts a value to a date. If the value cannot be converted to a date, [`$toDate`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todate.md#mongodb-expression-exp.-toDate) errors. If the value is null or missing, [`$toDate`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todate.md#mongodb-expression-exp.-toDate) returns null.

[`$toDate`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todate.md#mongodb-expression-exp.-toDate) has the following syntax:

```javascript
{
   $toDate: <expression>
}
```

The [`$toDate`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todate.md#mongodb-expression-exp.-toDate) takes any valid [expression.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

The [`$toDate`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todate.md#mongodb-expression-exp.-toDate) is a shorthand for the following [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) expression:

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

**See also:**

- [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert)

- [`$dateFromString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datefromstring.md#mongodb-expression-exp.-dateFromString)

## Behavior

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: "2018-03-20"; "2018-03-20T12:00:00Z"; "2018-03-20T12:00:00+0500" |
| 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: Decimal128("1253372036000.50")}` | ISODate("2009-09-19T14:53:56Z") |
| `{$toDate: Long("1100000000000")}` | ISODate("2004-11-19T11:33:20Z") |
| `{$toDate:  Long("-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

Create a collection `orders` with the following documents:

```javascript
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:

```javascript
// 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:

```javascript
{
   _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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) instead.