On this page
MongoDB stores data records as BSON documents. BSON is a binary representation of JSON documents, though it contains more data types than JSON. For the BSON spec, see bsonspec.org . See also BSON Types.
MongoDB documents are composed of field-and-value pairs and have the following structure:
The value of a field can be any of the BSON data types, including other documents, arrays, and arrays of documents. For example, the following document contains values of varying types:
The above fields have the following data types:
_idholds an ObjectId.
nameholds an embedded document that contains the fields
deathhold values of the Date type.
contribsholds an array of strings.
viewsholds a value of the NumberLong type.
Field names are strings.
Documents have the following restrictions on field names:
- The field name
_idis reserved for use as a primary key; its value must be unique in the collection, is immutable, and may be of any type other than an array.
Field names cannot contain the
Top-level field names cannot start with the dollar sign (
Otherwise, starting in MongoDB 3.6, the server permits storage of field names that contain dots (i.e.
.) and dollar signs (i.e.
The MongoDB Query Language cannot always meaningfully express queries over documents whose field names contain these characters (see SERVER-30575 ).
Until support is added in the query language, the use of
.in field names is not recommended and is not supported by the official MongoDB drivers.
BSON documents may have more than one field with the same name. Most MongoDB interfaces , however, represent MongoDB with a structure (e.g. a hash table) that does not support duplicate field names. If you need to manipulate documents that have more than one field with the same name, see the driver documentation for your driver.
Some documents created by internal MongoDB processes may have duplicate fields, but no MongoDB process will ever add duplicate fields to an existing user document.
MongoDB uses the dot notation to access the elements of an array and to access the fields of an embedded document.
To specify or access an element of an array by the zero-based index position, concatenate the array name with the dot (
.) and zero-based index position, and enclose in quotes:
For example, given the following field in a document:
To specify the third element in the
contribs array, use the dot notation
For examples querying arrays, see:
To specify or access a field of an embedded document with dot notation, concatenate the embedded document name with the dot (
.) and the field name, and enclose in quotes:
For example, given the following field in a document:
- To specify the field named
namefield, use the dot notation
- To specify the
phonedocument in the
contactfield, use the dot notation
For examples querying embedded documents, see:
Documents have the following attributes:
The maximum BSON document size is 16 megabytes.
The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See
mongofiles and the documentation for your driver for more information about GridFS.
MongoDB preserves the order of the document fields following write operations except for the following cases:
_idfield is always the first field in the document.
- Updates that include
renamingof field names may result in the reordering of fields in the document.
Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the field order in a document. Before version 2.6, MongoDB did not actively preserve the order of the fields in a document.
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.
_id field has the following behavior and constraints:
By default, MongoDB creates a unique index on the
_idfield during the creation of a collection.
_idfield is always the first field in the documents. If the server receives a document that does not have the
_idfield first, then the server will move the field to the beginning.
_idfield may contain values of any BSON data type, other than an array.
To ensure functioning replication, do not store values that are of the BSON regular expression type in the
The following are common options for storing values for
Use an ObjectId.
Use a natural unique identifier, if available. This saves space and avoids an additional index.
Generate an auto-incrementing number.
Generate a UUID in your application code. For a more efficient storage of the UUID values in the collection and in the
_idindex, store the UUID as a value of the BSON
Index keys that are of the
BinDatatype are more efficiently stored in the index if:
- the binary subtype value is in the range of 0-7 or 128-135, and
- the length of the byte array is: 0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, or 32.
Use your driver’s BSON UUID facility to generate UUIDs. Be aware that driver implementations may implement UUID serialization and deserialization logic differently, which may not be fully compatible with other drivers. See your driver documentation for information concerning UUID interoperability.
Most MongoDB driver clients will include the
_id field and generate an
ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an
_id field, the
mongod will add the
_id field and generate the
Query filter documents specify the conditions that determine which records to select for read, update, and delete operations.
You can use
<field>:<value> expressions to specify the equality condition and query operator expressions.