- Data Models >
- Data Model Reference >
- Documents
Documents¶
On this page
MongoDB stores all data in documents, which are JSON-style data structures composed of field-and-value pairs:
Most user-accessible data structures in MongoDB are documents, including:
- All database records.
- Query selectors, which define what records to select for read, update, and delete operations.
- Update definitions, which define what fields to modify during an update.
- Index specifications, which define what fields to index.
- Data output by MongoDB for reporting and configuration, such as the
output of the
serverStatus
and the replica set configuration document.
Document Format¶
MongoDB stores documents on disk in the BSON serialization format. 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.
The mongo
JavaScript shell and the MongoDB language
drivers translate between BSON and the
language-specific document representation.
Document Structure¶
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. The following document contains values of varying types:
The above fields have the following data types:
_id
holds an ObjectId.name
holds an embedded document that contains the fieldsfirst
andlast
.birth
anddeath
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 field names:
- The field name
_id
is 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. - The field names cannot start with the dollar sign (
$
) character. - The field names cannot contain the dot (
.
) character. - The field names cannot contain the
null
character.
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.
Field Value Limit¶
For indexed collections, the values
for the indexed fields have a
Maximum Index Key Length
limit. See
Maximum Index Key Length
for details.
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 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.
Document Field Order¶
MongoDB preserves the order of the document fields following write operations except for the following cases:
- The
_id
field is always the first field in the document. - Updates that include
renaming
of 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.
The _id
Field¶
The _id
field has the following behavior and constraints:
By default, MongoDB creates a unique index on the
_id
field during the creation of a collection.The
_id
field is always the first field in the documents. If the server receives a document that does not have the_id
field first, 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 values that are of the BSON regular expression type in the
_id
field.
The following are common options for storing values for _id
:
Use an ObjectId.
Use a natural unique identifier, if available. This saves space and avoids an additional index.
Generate an auto-incrementing number. See Create an Auto-Incrementing Sequence Field.
Generate a UUID in your application code. For a more efficient storage of the UUID values in the collection and in the
_id
index, store the UUID as a value of the BSONBinData
type.Index keys that are of the
BinData
type 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.
Note
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 ObjectId
.
Dot Notation¶
MongoDB uses the dot notation to access the elements of an array and to access the fields of an embedded document.
To 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:
See also $
positional operator for update operations and
$
projection operator when array index position is unknown.
To 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:
See also
- Embedded Documents for dot notation examples with embedded documents.
- Arrays for dot notation examples with arrays.