Documents

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.

• 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 of field names that contain dots (i.e. .) and dollar signs (i.e. $).

  Important

  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 $ and . in field names is not recommended and is not supported by the official MongoDB drivers.

The MongoDB Query Language does not support documents with duplicate field names. While some BSON builders may support creating a BSON document with duplicate field names, inserting these documents into MongoDB is not supported even if the insert succeeds, or appears to succeed. For example, inserting a BSON document with duplicate field names through a MongoDB driver may result in the driver silently dropping the duplicate values prior to insertion, or may result in an invalid document being inserted that contains duplicate fields. Querying against any such documents would lead to arbitrary and inconsistent results.

Field Value Limit

MongoDB 2.6 through MongoDB versions with featureCompatibilityVersion (fCV) set to "4.0" or earlier

For indexed collections, the values for the indexed fields have a Maximum Index Key Length. See Maximum Index Key Length for details.

Arrays

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:

"<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 dot notation "contribs.2".

For examples querying arrays, see:

• Query an Array

• Query an Array of Embedded Documents

Embedded Documents

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:

"<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 the dot notation "name.last".

• To specify the number in the phone document in the contact field, use the dot notation "contact.phone.number".

For examples querying embedded documents, see:

• Query on Embedded/Nested Documents

• Query an Array of Embedded Documents

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

Unlike JavaScript objects, the fields in a BSON document are ordered.

The _id Field

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 _id field.

This also applies to documents inserted through update operations with upsert: true.

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, regex, or undefined.

  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.

• 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 BSON BinData 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.

Query Filter Documents

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.

{
  <field1>: <value1>,
  <field2>: { <operator>: <value> },
  ...
}

For examples, see:

• Query Documents

• Query on Embedded/Nested Documents

• Query an Array

• Query an Array of Embedded Documents

Update Specification Documents

Update specification documents use update operators to specify the data modifications to perform on specific fields during an db.collection.update() operation.

{
  <operator1>: { <field1>: <value1>, ... },
  <operator2>: { <field2>: <value2>, ... },
  ...
}

For examples, see Update specifications.

Index Specification Documents

Index specification documents define the field to index and the index type:

{ <field1>: <type1>, <field2>: <type2>, ...  }