Permalink
Fetching contributors…
Cannot retrieve contributors at this time
310 lines (205 sloc) 8.16 KB
.. _bson-document-format:
=========
Documents
=========
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
MongoDB stores data records as BSON documents. BSON is a binary
representation of :term:`JSON` documents, though it contains more data
types than JSON. For the BSON spec, see `bsonspec.org
<http://bsonspec.org/>`_. See also :doc:`/reference/bson-types`.
.. include:: /images/crud-annotated-document.rst
.. _document-structure:
Document Structure
------------------
MongoDB documents are composed of field-and-value pairs and have the
following structure:
.. code-block:: javascript
{
field1: value1,
field2: value2,
field3: value3,
...
fieldN: valueN
}
The value of a field can be any of the BSON :doc:`data types
</reference/bson-types>`, including other documents, arrays, and arrays
of documents. For example, the following document contains values of varying types:
.. code-block:: javascript
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 :ref:`objectid`.
- ``name`` holds an *embedded document* that contains the fields
``first`` 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.
.. include:: /includes/fact-document-field-name-restrictions.rst
BSON documents may have more than one field with the same name.
Most :doc:`MongoDB interfaces </applications/drivers>`, 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 :doc:`driver documentation
</applications/drivers>` 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 :doc:`indexed collections </indexes>`, the values
for the indexed fields have a
:limit:`Maximum Index Key Length <Index Key Limit>` limit. See
:limit:`Maximum Index Key Length <Index Key Limit>` for details.
.. _document-dot-notation:
Dot Notation
------------
MongoDB uses the *dot notation* to access the elements of an array and
to access the fields of an embedded document.
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:
.. code-block:: javascript
"<array>.<index>"
For example, given the following field in a document:
.. code-block:: javascript
{
...
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:
- :doc:`/tutorial/query-arrays`
- :doc:`/tutorial/query-array-of-documents/`
.. seealso::
- :update:`$` positional operator for update operations,
- :projection:`$` projection operator when array index position is
unknown
- :ref:`read-operations-arrays` for dot notation examples with arrays.
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:
.. code-block:: javascript
"<embedded document>.<field>"
For example, given the following field in a document:
.. code-block:: javascript
{
...
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:
- :doc:`/tutorial/query-embedded-documents`
- :doc:`/tutorial/query-array-of-documents/`
Document Limitations
--------------------
Documents have the following attributes:
Document Size Limit
~~~~~~~~~~~~~~~~~~~
.. include:: /includes/fact-document-max-size.rst
Document Field Order
~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/fact-update-field-order.rst
:start-after: order-of-document-fields
.. _document-id-field:
The ``_id`` Field
~~~~~~~~~~~~~~~~~
.. include:: /includes/fact-id-field.rst
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 :doc:`BSON data type
</reference/bson-types>`, 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.
.. See :issue:`SERVER-9562` for more information.
The following are common options for storing values for ``_id``:
- Use an :ref:`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.
.. include:: /includes/fact-bindata-storage-optimization.rst
- 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 :api:`driver documentation <>` for
information concerning UUID interoperability.
.. include:: /includes/note-insert-id-field.rst
Other Uses of the Document Structure
------------------------------------
In addition to defining data records, MongoDB uses the document
structure throughout, including but not limited to: :ref:`query filters
<document-query-filter>`, :ref:`update specifications documents
<document-update-specification>`, and :ref:`index specification
documents <document-index-specification>`
.. _document-query-filter:
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 :doc:`query operator </reference/operator/query>`
expressions.
.. code-block:: javascript
{
<field1>: <value1>,
<field2>: { <operator>: <value> },
...
}
For examples, see:
- :doc:`/tutorial/query-documents`
- :doc:`/tutorial/query-embedded-documents`
- :doc:`/tutorial/query-arrays`
- :doc:`/tutorial/query-array-of-documents/`
.. _document-update-specification:
Update Specification Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Update specification documents use :ref:`update operators
<update-operators>` to specify the data modifications to perform on
specific fields during an :method:`db.collection.update()` operation.
.. code-block:: javascript
{
<operator1>: { <field1>: <value1>, ... },
<operator2>: { <field2>: <value2>, ... },
...
}
For examples, see :ref:`Update specifications
<update-documents-modifiers>`.
.. _document-index-specification:
Index Specification Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Index specifications document define the field to index and the index
type:
.. code-block:: javascript
{ <field1>: <type1>, <field2>: <type2>, ... }