Each BSON type has both integer and string identifiers as listed in the following table:
|Decimal128||19||“decimal”||New in version 3.4.|
You can use these values with the
$type operator to query documents by their BSON type. The
$type aggregation operator returns the type of an operator expression using one of the listed BSON type strings.
To determine a field’s type, see Check Types in the mongo Shell.
If you convert BSON to JSON, see the Extended JSON reference.
The following sections describe special considerations for particular BSON types.
ObjectIds are small, likely unique, fast to generate, and ordered. ObjectId values are 12 bytes in length, consisting of:
- a 4-byte timestamp value, representing the ObjectId’s creation, measured in seconds since the Unix epoch
- a 5-byte random value
- a 3-byte incrementing counter, initialized to a random value
While the BSON format itself is little-endian, the timestamp and counter values are big-endian, with the most significant bytes appearing first in the byte sequence.
In MongoDB, each document stored in a collection requires a unique _id field that acts as a primary key. If an inserted document omits the
_id field, the MongoDB driver automatically generates an ObjectId for the
This also applies to documents inserted through update operations with upsert: true.
MongoDB clients should add an
_id field with a unique ObjectId. Using ObjectIds for the
_id field provides the following additional benefits:
sorting on an
_idfield that stores
ObjectIdvalues is roughly equivalent to sorting by creation time.
While ObjectId values should increase over time, they are not necessarily monotonic. This is because they:
- Only contain one second of temporal resolution, so ObjectId values created within the same second do not have a guaranteed ordering, and
- Are generated by clients, which may have differing system clocks.
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.  In addition, MongoDB
$regex queries support UTF-8 in the regex string.
|||Given strings using UTF-8 character sets, using
BSON has a special timestamp type for internal MongoDB use and is not associated with the regular Date type. This internal timestamp type is a 64 bit value where:
- the most significant 32 bits are a
time_tvalue (seconds since the Unix epoch)
- the least significant 32 bits are an incrementing
ordinalfor operations within a given second.
While the BSON format is little-endian, and therefore stores the least significant bits first, the
mongod instance always compares the
time_t value before the
ordinal value on all platforms, regardless of endianness.
Within a single
mongod instance, timestamp values are always unique.
In replication, the oplog has a
ts field. The values in this field reflect the operation time, which uses a BSON timestamp value.
The BSON timestamp type is for internal MongoDB use. For most cases, in application development, you will want to use the BSON date type. See Date for more information.
When inserting a document that contains top-level fields with empty timestamp values, MongoDB replaces the empty timestamp values with the current timestamp value, with the following exception. If the
_id field itself contains an empty timestamp value, it will always be inserted as is and not replaced.
Insert a document with an empty timestamp value:
db.test.find() would then return a document which resembles the following:
The server has replaced the empty timestamp value for
ts with the timestamp value at time of insert.
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.
The official BSON specification refers to the BSON Date type as the UTC datetime.
BSON Date type is signed.  Negative values represent dates before 1970.
Construct a Date using the
new Date() constructor in the
Construct a Date using the
ISODate() constructor in the
Date value as string:
Return the month portion of the Date value; months are zero-indexed, so that January is month
|||Prior to version 2.0,