Documents (original) (raw)

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.

A MongoDB document.

MongoDB stores records as documents for deployments hosted in the following environments:

MongoDB documents are composed of field-and-value pairs and have the following 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 arrays of 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:

Field names are strings.

Documents have the following restrictions on field names:

The MongoDB Query Language doesn't support documents with duplicate field names:

Starting in MongoDB 6.1, to see if a document has duplicate field names, use the validate command with the full field set totrue. In any MongoDB version, use the $objectToArrayaggregation operator to see if a document has duplicate field names.

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:


{

   ...

   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:

See also:

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" } },

   ...

}

Warning

Partition fields cannot use field names that contain a dot (.).

For examples querying embedded documents, see:

Documents have the following attributes:

The maximum BSON document size is 16 mebibytes.

The maximum document size helps ensure that a single document cannot use an excessive amount of RAM or, during transmission, an excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. For more information about GridFS, see mongofiles and the documentation for your driver

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

For queries, the field order behavior is as follows:

For write operations, MongoDB preserves the order of the document fields_except_ for the following cases:

In MongoDB, each document stored in a standard 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.

Note

In time series collections, documents do not require a unique _id field because MongoDB does not create an index on the _id field.

The _id field has the following behavior and constraints:

Warning

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

The following are common options for storing values for _id:

Note

Most MongoDB driver clients include the _id field and generate an ObjectId before sending the insert operation to MongoDB. However, if the client sends a document without an _idfield, the mongod adds the _id field and generates the ObjectId.

In addition to defining data records, MongoDB uses the document structure throughout, including but not limited to: query filters, update specifications documents, and index specification 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 operatorexpressions.


{

  <field1>: <value1>,

  <field2>: { <operator>: <value> },

  ...

}

For examples, see:

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


{

  <operator1>: { <field1>: <value1>, ... },

  <operator2>: { <field2>: <value2>, ... },

  ...

}

For examples, see Update specifications.

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


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

For more information on the MongoDB document model, download theMongoDB Application Modernization Guide.

The download includes the following resources: