Documents

Documents

MongoDB stores data records as BSON documents. BSON is a binaryrepresentation of JSON documents, though it contains more datatypes than JSON. For the BSON spec, see bsonspec.org. See also BSON Types.

Document Structure

MongoDB documents are composed of field-and-value pairs and have thefollowing structure:

{
   field1: value1,
   field2: value2,
   field3: value3,
   ...
   fieldN: valueN
}

The value of a field can be any of the BSON data types, including other documents, arrays, and arraysof documents. For example, the following document contains values of varying types:

var mydoc = {
               _id: ObjectId("5099803df3f4948bd2f98391"),
               name: { first: "Alan", last: "Turing" },
               birth: new Date('Jun 23, 1912'),
               death: new Date('Jun 07, 1954'),
               contribs: [ "Turing machine", "Turing test", "Turingery" ],
               views : NumberLong(1250000)
            }

The above fields have the following data types:

_id holds an ObjectId.
name holds an embedded document that contains the fieldsfirst and last.
birth and death hold values of the Date type.
contribs holds an array of strings.
views holds a value of the NumberLong type.

Field Names

Field names are strings.

Documents have the following restrictions on fieldnames:

The field name _id is reserved for use as a primary key; itsvalue must be unique in the collection, is immutable, and may be ofany type other than an array.

Field names cannot contain the null character.
Top-level field names cannot start with the dollar sign ($) character.

Otherwise, starting in MongoDB 3.6, the server permits storage offield names that contain dots (i.e. .) and dollar signs (i.e.$).

Important

The MongoDB Query Language cannot always meaningfully expressqueries over documents whose field names contain these characters(see SERVER-30575).

Until support is added in the query language, the use of $ and. in field names is not recommended and is not supported bythe official MongoDB drivers.

BSON documents may have more than one field with the same name.Most MongoDB interfaces, however, represent MongoDBwith a structure (e.g. a hash table) that does not support duplicatefield names. If you need to manipulate documents that have more than onefield with the same name, see the driver documentation for your driver.

Some documents created by internal MongoDB processes may have duplicatefields, but no MongoDB process will ever add duplicate fields to anexisting user document.

Field Value Limit

MongoDB 2.6 through MongoDB versions with featureCompatibilityVersion (fCV) set to "4.0" or earlier
For indexed collections, the values for theindexed fields have a Maximum Index Key Length. SeeMaximum Index Key Length for details.

Dot Notation

MongoDB uses the dot notation to access the elements of an array andto access the fields of an embedded document.

Arrays

To specify or access an element of an array by the zero-based indexposition, concatenate the array name with the dot (.) andzero-based index position, and enclose in quotes:

"<array>.<index>"

For example, given the following field in a document:

{
   ...
   contribs: [ "Turing machine", "Turing test", "Turingery" ],
   ...
}

To specify the third element in the contribs array, use the dotnotation "contribs.2".

For examples querying arrays, see:

Embedded Documents

To specify or access a field of an embedded document with dot notation,concatenate the embedded document name with the dot (.) andthe field name, and enclose in quotes:

"<embedded document>.<field>"

For example, given the following field in a document:

{
   ...
   name: { first: "Alan", last: "Turing" },
   contact: { phone: { type: "cell", number: "111-222-3333" } },
   ...
}

To specify the field named last in the name field, use thedot notation "name.last".
To specify the number in the phone document in thecontact field, use the dot notation "contact.phone.number".

For examples querying embedded documents, see:

Document Limitations

Documents have the following attributes:

Document Size Limit

The maximum BSON document size is 16 megabytes.

The maximum document size helps ensure that a single document cannotuse excessive amount of RAM or, during transmission, excessive amountof bandwidth. To store documents larger than the maximum size, MongoDBprovides the GridFS API. See mongofiles and thedocumentation for your driver for moreinformation about GridFS.

Document Field Order

MongoDB preserves the order of the document fields following writeoperations except for the following cases:

The _id field is always the first field in the document.
Updates that include renaming of field names mayresult in the reordering of fields in the document.

Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve thefield order in a document. Before version 2.6, MongoDB did notactively preserve the order of the fields in a document.

The _id Field

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.

The _id field has the following behavior and constraints:

By default, MongoDB creates a unique index on the _id fieldduring the creation of a collection.
The _id field is always the first field in the documents. If theserver receives a document that does not have the _id fieldfirst, then the server will move the field to the beginning.
The _id field may contain values of any BSON data type, other than an array.

Warning

To ensure functioning replication, do not store valuesthat are of the BSON regular expression type in the _idfield.

The following are common options for storing values for _id:

Use an ObjectId.
Use a natural unique identifier, if available. This saves space andavoids an additional index.
Generate an auto-incrementing number.
Generate a UUID in your application code. For a more efficientstorage of the UUID values in the collection and in the _idindex, store the UUID as a value of the BSON BinData type.

Index keys that are of the BinData type are more efficiently storedin 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 awarethat driver implementations may implement UUID serialization anddeserialization logic differently, which may not be fully compatiblewith other drivers. See your driver documentation forinformation concerning UUID interoperability.

Note

Most MongoDB driver clients will include the _id field andgenerate an ObjectId before sending the insert operation toMongoDB; however, if the client sends a document without an _idfield, the mongod will add the _id field and generatethe ObjectId.