BSON Types

BSON is a binary serialization format used to store documentsand make remote procedure calls in MongoDB. The BSON specification islocated at bsonspec.org.

Each BSON type has both integer and string identifiers as listed in thefollowing table:

You can use these values with the $type operator to querydocuments by their BSON type. The $type aggregation operatorreturns the type of an operator expression using one of the listed BSON typestrings.

To determine a field’s type, see Check Types in the mongo Shell.

If you convert BSON to JSON, seethe Extended JSON reference.

The following sections describe special considerations for particularBSON types.

ObjectId

ObjectIds are small, likely unique, fast to generate, and ordered.ObjectId values consist of 12 bytes, where the first four bytes are atimestamp that reflect the ObjectId’s creation. Specifically:

• a 4-byte value representing the seconds since the Unix epoch,
• a 5-byte random value, and
• a 3-byte counter, starting with a random value.

In MongoDB, each document stored in a collection requires a unique_id field that acts as a primary key. If an inserteddocument omits the _id field, the MongoDB driver automaticallygenerates an ObjectId for the _id field.

This also applies to documents inserted through updateoperations with upsert: true.

MongoDB clients should add an _id field with a unique ObjectId.Using ObjectIds for the _id field provides the following additionalbenefits:

• in the mongo shell, you can access the creation time ofthe ObjectId, using the ObjectId.getTimestamp() method.

• sorting on an _id field that stores ObjectId values isroughly equivalent to sorting by creation time.

Important

While ObjectId values should increase over time, they are notnecessarily monotonic. This is because they:

• Only contain one second of temporal resolution, so ObjectIdvalues created within the same second do not have a guaranteedordering, and
• Are generated by clients, which may have differing system clocks.

See also

ObjectId()

String

BSON strings are UTF-8. In general, drivers for each programminglanguage convert from the language’s string format to UTF-8 whenserializing and deserializing BSON. This makes it possible to storemost international characters in BSON strings with ease.[1] In addition, MongoDB$regex queries support UTF-8 in the regex string.

Timestamps

BSON has a special timestamp type for internal MongoDB use and isnot associated with the regular Datetype. This internal timestamp type is a 64 bit value where:

• the most significant 32 bits are a time_t value (seconds sincethe Unix epoch)
• the least significant 32 bits are an incrementing ordinal foroperations within a given second.

While the BSON format is little-endian, and therefore stores the leastsignificant bits first, the mongod instancealways compares the time_t value beforethe ordinal value on all platforms, regardless ofendianness.

Within a single mongod instance, timestamp values arealways unique.

In replication, the oplog has a ts field. The values inthis field reflect the operation time, which uses a BSON timestampvalue.

Note

The BSON timestamp type is for internal MongoDB use. For mostcases, in application development, you will want to use the BSONdate type. See Date for moreinformation.

When inserting a document that contains top-level fields with emptytimestamp values, MongoDB replaces the empty timestamp values with thecurrent timestamp value, with the following exception. If the _idfield itself contains an empty timestamp value, it will always beinserted as is and not replaced.

Example

Insert a document with an empty timestamp value:

db.test.insertOne( { ts: new Timestamp() } );

Running db.test.find() would thenreturn a document which resembles the following:

{ "_id" : ObjectId("542c2b97bac0595474108b48"), "ts" : Timestamp(1412180887, 1) }

The server has replaced the empty timestamp value for ts with thetimestamp value at time of insert.

Date

BSON Date is a 64-bit integer that represents the number ofmilliseconds since the Unix epoch (Jan 1, 1970). This results in arepresentable date range of about 290 million years into the past andfuture.

The official BSON specificationrefers to the BSON Date type as the UTC datetime.

BSON Date type is signed. [2] Negative values representdates before 1970.

Example

Construct a Date using the new Date() constructor in themongo shell:

var mydate1 = new Date()

Example

Construct a Date using the ISODate() constructor in themongo shell:

var mydate2 = ISODate()

Example

Return the Date value as string:

mydate1.toString()

Example

Return the month portion of the Date value; months are zero-indexed,so that January is month 0:

mydate1.getMonth()