- Data Models >
- Data Model Reference >
- BSON Types
BSON Types¶
On this page
BSON is a binary serialization format used to store documents and make remote procedure calls in MongoDB. The BSON specification is located at bsonspec.org.
BSON supports the following data types as values in documents. Each data
type has a corresponding number that can be used with the
$type
operator to query documents by BSON type.
Type | Number |
Double | 1 |
String | 2 |
Object | 3 |
Array | 4 |
Binary data | 5 |
Undefined | 6 |
Object id | 7 |
Boolean | 8 |
Date | 9 |
Null | 10 |
Regular Expression | 11 |
JavaScript | 13 |
Symbol | 14 |
JavaScript (with scope) | 15 |
32-bit integer | 16 |
Timestamp | 17 |
64-bit integer | 18 |
Min key | 255 |
Max key | 127 |
When comparing values of different BSON types, MongoDB uses the following comparison order, from lowest to highest:
- MinKey (internal type)
- Null
- Numbers (ints, longs, doubles)
- Symbol, String
- Object
- Array
- BinData
- ObjectId
- Boolean
- Date, Timestamp
- Regular Expression
- MaxKey (internal type)
MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison.
The comparison treats a non-existent field as it would an empty BSON
Object. As such, a sort on the a
field in documents { }
and {
a: null }
would treat the documents as equivalent in sort order.
With arrays, a less-than comparison or an ascending sort compares the
smallest element of arrays, and a greater-than comparison or a
descending sort compares the largest element of the arrays. As such,
when comparing a field whose value is a single-element array (e.g. [
1 ]
) with non-array fields (e.g. 2
), the comparison is between
1
and 2
. A comparison of an empty array (e.g. [ ]
) treats
the empty array as less than null
or a missing field.
To determine a field’s type, see Check Types in the mongo Shell.
If you convert BSON to JSON, see Data Type Fidelity for more information.
The next sections describe special considerations for particular BSON types.
ObjectId¶
ObjectIds are: small, likely unique, fast to generate, and ordered. These values consists of 12-bytes, where the first four bytes are a timestamp that reflect the ObjectId’s creation. Refer to the ObjectId documentation for more information.
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
$regex
queries support UTF-8 in the regex string.
[1] | Given strings using UTF-8
character sets, using sort() on strings
will be reasonably correct. However, because internally
sort() uses the C++ strcmp api, the
sort order may handle some characters incorrectly. |
Timestamps¶
BSON has a special timestamp type for internal MongoDB use and is not associated with the regular Date type. 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 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.
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. See Date for more information.
If you create a BSON Timestamp using the empty constructor (e.g. new
Timestamp()
), MongoDB will only generate a timestamp if you use
the constructor in the first field of the document. [2]
Otherwise, MongoDB will generate an empty timestamp value
(i.e. Timestamp(0, 0)
.)
Changed in version 2.1: mongo
shell displays the Timestamp value with the wrapper:
Prior to version 2.1, the mongo
shell display the
Timestamp value as a document:
[2] | If the first field in the document is In the following example, MongoDB will generate a Timestamp
value, even though the |
Date¶
BSON Date is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). The official BSON specification refers to the BSON Date type as the UTC datetime.
Changed in version 2.0: BSON Date type is signed. [3] Negative values represent dates before 1970.
Example
Construct a Date using the new Date()
constructor in the
mongo
shell:
Example
Construct a Date using the ISODate()
constructor in the
mongo
shell:
Example
Return the Date
value as string:
Example
Return the month portion of the Date value; months are zero-indexed,
so that January is month 0
:
[3] | Prior to version 2.0, Date values were
incorrectly interpreted as unsigned integers, which affected
sorts, range queries, and indexes on Date fields. Because
indexes are not recreated when upgrading, please re-index if you
created an index on Date values with an earlier version, and
dates before 1970 are relevant to your application. |