BSON Types

On this page

• ObjectId
• String
• Timestamps
• Date

BSONis a binary serialization format used to store documents and make remote procedure calls in MongoDB. The BSON specification is located atbsonspec.org.

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

You can use these values with the$typeoperator to query documents by their BSON type. The$typeaggregation operator returns the type of anoperator expressionusing one of the listed BSON type strings.

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

If you convert BSON to JSON, see theExtended JSONreference.

The following sections describe special considerations for particular BSON types.

ObjectId

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

• a 4-byte value representing the seconds since the Unix epoch,
• a 3-byte machine identifier,
• a 2-byte process id, and
• a 3-byte counter, starting with a random value.

In MongoDB, each document stored in a collection requires a unique_idfield that acts as aprimary key. If an inserted document omits the_idfield, the MongoDB driver automatically generates anObjectIdfor the_idfield.

This also applies to documents inserted through update operations withupsert: true.

MongoDB clients should add an_idfield with a unique ObjectId. Using ObjectIds for the_idfield provides the following additional benefits:

• in themongoshell, you can access the creation time of theObjectId, using theObjectId.getTimestamp()method.

• sorting on an_idfield that storesObjectIdvalues is roughly equivalent to sorting by creation time.

  IMPORTANT

  The relationship between the order ofObjectIdvalues and generation time is not strict within a single second. If multiple systems, or multiple processes or threads on a single system generate values, within a single second;ObjectIdvalues do not represent a strict insertion order. Clock skew between clients can also result in non-strict ordering even for values because client drivers generateObjectIdvalues.

SEE ALSO

ObjectId()

String

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

Timestamps

BSON has a special timestamp type for_internal_MongoDB use and isnotassociated with the regularDatetype. Timestamp values are a 64 bit value where:

• the first 32 bits are a
  time_t
  value (seconds since the Unix epoch)
• the second 32 bits are an incrementing
  ordinal
  for operations within a given second.

Within a singlemongodinstance, timestamp values are always unique.

In replication, theoploghas atsfield. The values in this field reflect the operation time, which uses a BSON timestamp value.

NOTE

The BSON timestamp type is for_internal_MongoDB use. For most cases, in application development, you will want to use the BSON date type. SeeDatefor more information.

If you insert a document containing an empty BSON timestamp in a top-level field, the MongoDB server will replace that empty timestamp with the current timestamp value. For example, if you create an insert a document with a timestamp value, as in the following operation:

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

Then, thedb.test.find()operation will return a document that resembles the following:

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

Iftswere a field in an embedded document, the server would have left it as an empty timestamp value.

Changed in version 2.6:Previously, the server would only replace empty timestamp values in the first two fields, including_id, of an inserted document. Now MongoDB will replace any top-level field.

Date

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

Theofficial BSON specificationrefers to the BSON Date type as theUTC datetime.

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

EXAMPLE

Construct a Date using thenewDate()constructor in themongoshell:

var
mydate1
=
new
Date
()

EXAMPLE

Construct a Date using theISODate()constructor in themongoshell:

var
mydate2
=
ISODate
()

EXAMPLE

Return theDatevalue as string:

mydate1
.
toString
()

EXAMPLE

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

mydate1
.
getMonth
()

| [2] | Prior to version 2.0,Datevalues were incorrectly interpreted as_unsigned_integers, which affected sorts, range queries, and indexes onDatefields. Because indexes are not recreated when upgrading, please re-index if you created an index onDatevalues with an earlier version, and dates before 1970 are relevant to your application. |
| :—- | :—- |