Date() and Datetime (mongosh method)

Date()

Returns a date either as a string or as a Date object. The date can contain a date and a time, known as a datetime.

The BSON specification states a Date object contains the UTC datetime. UTC is Coordinated Universal Time. The UTC datetime stores an unsigned 64-bit integer value, indicating the number of milliseconds after the Unix epoch (January 1st, 1970 at 00:00:00 UTC).

Compatibility

You can use Date() for deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

You can specify either of the following formats:

Date() returns the current date as a string in mongosh.
new Date() returns the current date as a Date object. mongosh wraps the Date object with the ISODate helper. The ISODate is in UTC.

You can specify a particular date by passing an ISO-8601 date string with a year within the inclusive range 0 through 9999 to the new Date() constructor or the ISODate() function. These functions accept the following formats:

new Date("<YYYY-mm-dd>") returns the ISODate with the specified date.
new Date("<YYYY-mm-ddTHH:MM:ss.sss>") specifies the datetime in the client's local timezone and returns the ISODate with the specified datetime in UTC. ss.sss specifies seconds (ss) and milliseconds (.sss). Milliseconds are set to 0 if omitted.
new Date("<YYYY-mm-ddTHH:MM:ss.sssZ>") specifies the datetime in UTC and returns the ISODate with the specified datetime in UTC. ss.sss specifies seconds (ss) and milliseconds (.sss). Milliseconds are set to 0 if omitted.
new Date(<integer>) specifies the datetime as milliseconds since the UNIX epoch (Jan 1, 1970), and returns the resulting ISODate instance.

Behavior

Internally, Date objects are stored as a signed 64-bit integer representing the number of milliseconds since the Unix epoch (Jan 1, 1970).

Not all database operations and drivers support the full 64-bit range. You may safely work with dates with years within the inclusive range 0 through 9999.

Examples

Use Date in a Query

If no document with the specified title exists in the movies collection, the following operation inserts a document with the field dateAdded set to the current date:

db.movies.updateOne(
   { title: "Upsert Demo Film 2099" },
   {
     $set: { genre: "Drama" },
     $setOnInsert: { dateAdded: new Date() }
   },
   { upsert: true }
)

{
  acknowledged: true,
  insertedId: "...",
  matchedCount: 0,
  modifiedCount: 0,
  upsertedCount: 1
}

Tip

$currentDate
NOW aggregation variable usage to update with aggregation pipeline

Return Date as a String

To return the date as a string, use the Date() method. For example:

var myDateString = Date();

Return Date as `Date` Object

mongosh wraps objects of Date type with the ISODate helper. However, the objects are Date types.

The following example uses new Date() to return a Date object with the specified UTC datetime:

var myDate = new Date("2016-05-18T16:00:00Z");

Tip

Insert and Return `ISODate` Objects

You can specify dates as ISODate objects.

The following example inserts documents with ISODate objects in the released field into the movies collection in the sample_mflix database:

db.movies.insertMany( [
   { title: "ISODate Demo: Chocolate", released: new ISODate("2020-05-18T14:10:30.123Z") },
   { title: "ISODate Demo: Strawberry", released: new ISODate("2021-03-20T11:30:05.000Z") },
   { title: "ISODate Demo: Vanilla", released: new ISODate("2021-01-15T06:31:15.456Z") }
] )

The following example returns documents where the released date is less than the ISODate specified in the $lt operator:

db.movies.find(
   { released: { $lt: ISODate("2021-02-25T10:03:46.234Z") },
     title: /^ISODate Demo:/ },
   { title: 1, released: 1, _id: 0 }
).sort( { released: 1 } ).toArray()

[
  {
    title: 'ISODate Demo: Chocolate',
    released: ISODate('2020-05-18T14:10:30.123Z')
  },
  {
    title: 'ISODate Demo: Vanilla',
    released: ISODate('2021-01-15T06:31:15.456Z')
  }
]

Back

BulkWriteResult

HexData