IsoDate in MongoDB

1. Overview

In this article, we will learn the purpose of ISODate in the MongoDB database.

2. MongoDB BSON format

MongoDB stores data in BSON (Binary Javascript Object Notation) format both internally, and over the network. It is nothing but a binary-encoded serialization of JSON documents. Whatever you can represent in JSON can also be stored natively in MongoDB as BSON, and retrieved just as easily in JSON.

BSON adds some non-JSON-native data types, like dates and binary data, to provide some valuable support to users. Since JSON only supports a few basic data types and thus lacks support for dates and binary data and these objects are not natively representable in pure JSON.

A date or ISODate field in BSON is an 8-byte (64-bit integer).

3. MongoDB Date

To represent a BSON data type in a JSON document, you can use associated JSON representations in Strict mode and mongo Shell mode formats:

• Strict mode. Strict mode representations of BSON types conform to the JSON RFC. Any JSON parser can parse these strict mode representations as key/value pairs; however, only the MongoDB internal JSON parser recognizes the type information conveyed by the format. i.e., $date
• mongo Shell mode. The MongoDB internal JSON parser and the mongo shell can parse this mode.

Strict Mode	mongo Shell Mode
{ "$date": "<date>" }	new Date ( <date> )

In Strict mode, <date> is an ISO-8601 date format with a mandatory time zone field following the template YYYY-MM-DDTHH:mm:ss.mmm<+/-Offset>.

In Shell mode, <date> is the JSON representation of a 64-bit signed integer giving the number of milliseconds since epoch UTC.

3.1. MongoDB ISODate in shell mode

The Date() returns a date either as a string or as a Date object. This is a convenience JSON helper to create a Date field in MongoDB.

• Date() returns the current date as a string in mongosh.
• new Date() returns the specified 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 that accept the following formats:

• new Date("<YYYY-mm-dd>") returns the ISODate with the specified date.
• new Date("<YYYY-mm-ddTHH:MM:ss>") specifies the datetime in the client’s local timezone and returns the ISODate with the specified datetime in UTC.
• new Date("<YYYY-mm-ddTHH:MM:ssZ>") specifies the datetime in UTC and returns the ISODate with the specified datetime in UTC.
• new Date(<integer>) specifies the datetime as milliseconds since the UNIX epoch (Jan 1, 1970), and returns the resulting ISODate instance.

3.2. Example of ISODate

Let’s insert documents by using the above new Date() constructor variations and see how it behaves.

Atlas atlas-kd7riz-shard-0 [primary] test> db.createCollection("date")
{ ok: 1 }
Atlas atlas-kd7riz-shard-0 [primary] test> db.date.insertMany([{"_id": "US", "date": new Date("2022-11-27T00:00:00Z")
... }])
{ acknowledged: true, insertedIds: { '0': 'US' } }


Atlas atlas-kd7riz-shard-0 [primary] test> db.date.insertMany([{ "_id": "JP", "date": new Date("2022-11-27") }])
{ acknowledged: true, insertedIds: { '0': 'JP' } }


Atlas atlas-kd7riz-shard-0 [primary] test> db.date.insertMany([{ "_id": "BR", "date": new Date("2022-11-27T00:00:00") }])
{ acknowledged: true, insertedIds: { '0': 'BR' } }


Atlas atlas-kd7riz-shard-0 [primary] test> db.date.insertMany([{ "_id": "IN", "date": new Date(1669539683) }])
{ acknowledged: true, insertedIds: { '0': 'IN' } }

Atlas atlas-kd7riz-shard-0 [primary] test> db.date.insertMany([{ "_id": "ID", "date": new Date() }])
{ acknowledged: true, insertedIds: { '0': 'ID' } }

4. Conclusion

To sum up, we have learned the use of ISODate in the MongoDB database with examples. To learn more about MongoDB, refer to these articles.