diff --git a/draft/applications/create.txt b/draft/applications/create.txt index 76fe81ad54a..935ffa1dc9e 100644 --- a/draft/applications/create.txt +++ b/draft/applications/create.txt @@ -14,8 +14,8 @@ create operations: - :ref:`save ` -Additionally, the three methods exhibit the following behavior during -the create operation: +The three methods exhibit the following behavior during the create +operation: - If the new document does not specify an :term:`_id` field, these methods add the ``_id`` field to the document and assign as @@ -29,9 +29,11 @@ the create operation: schema change to the collection or any change to the existing documents. -MongoDB v2.2 has a 16 megabytes limit on document size. +The following restrictions apply on the documents to be added: -.. include:: /includes/warning-document-field-name-restrictions.rst +- .. include:: /includes/fact-document-max-size.rst + +- .. include:: /includes/fact-document-field-name-restrictions.rst .. note:: diff --git a/draft/core/documents.txt b/draft/core/documents.txt index 5356f484784..8082f0a31b6 100644 --- a/draft/core/documents.txt +++ b/draft/core/documents.txt @@ -4,10 +4,26 @@ Documents .. default-domain:: mongodb -The document structure in MongoDB refer to the data structure of the -records stored in :term:`collections `, the query criteria, -the update actions, and other arguments to MongoDB methods and -operators. +The document structure in MongoDB refer to the data structure of: + +- the :ref:`records ` stored in :term:`collections + ` + +- the :ref:`query selectors ` that determine + which records to select for read, update, and delete operations + +- the :ref:`update actions ` that specifies + the particular field updates to perform during an update operation + +- the :ref:`index ` on a collection + +- the various other arguments to MongoDB methods and operators, such as: + + - :ref:`sort order ` for the :method:`sort() + ` method. + +Structure +--------- The document structure in MongoDB are :term:`BSON` objects with support for the full range of :term:`BSON types`; however, conceptually, @@ -26,15 +42,24 @@ structure: Having support for the full range of :term:`BSON types`, MongoDB documents may contain ``field:value`` pairs where the value can be -another document, an array, an array of documents as well as the basic -types such as ``Double``, ``String``, or ``Date``. +another document, an array, an array of documents as well +as the basic types such as ``Double``, ``String``, or ``Date``. -.. include:: /includes/warning-document-field-name-restrictions.rst +.. _documents-records: -Consider the following examples of MongoDB documents: +Document as records +------------------- -- The following document specifies a record in a collection. Documents - in a collection contain a unique ``_id`` field: +For documents that specify records to be stored in a collection, the +following restrictions apply: + +- .. include:: /includes/fact-document-max-size.rst + +- .. include:: /includes/fact-document-field-name-restrictions.rst + +.. include:: /includes/note-insert-id-field.rst + +The following document specifies a record in a collection: .. code-block:: javascript @@ -54,89 +79,164 @@ Consider the following examples of MongoDB documents: ] } - .. include:: /includes/note-insert-id-field.rst - -- The following documents specify the query criteria: +The document contains the following fields: + +- field ``_id`` whose value must be unique - - The following document specifies the query criteria where ``_id`` - is equal to ``1``: +- field ``name`` whose value is another *Document* that contains the + fields ``first`` and ``last`` + +- fields ``birth`` and ``death`` whose value is a *Date* - .. code-block:: javascript +- field ``contribs`` whose value is an *array of Strings* - { _id: 1 } +- field ``awards`` whose value is an *array of Documents* - - The following document specifies the query criteria where ``_id`` - is greater than ``3``: +.. _documents-query-selectors: - .. code-block:: javascript +Document as query selectors +--------------------------- - { _id: { $gt: 3 } } +Query selector documents may contain any or all of the following: - - The following document specifies the query criteria where ``_id`` - is equal to ``1`` **and** the ``name`` field equals the document ``{ - first: 'John', last: 'Backus' }``: +- Simple ``field:value`` pair(s) to specify the equality condition. - .. code-block:: javascript +- :doc:`Query operator ` expressions to specify + other conditions. - { _id: 1, name: { first: 'John', last: 'Backus' } } +Consider the following examples of query selector documents: - When passed as an argument to methods such as the :method:`find() - ` method or the :method:`update() - ` method, the query document determines which - records are returned or updated: +- The following document specifies the query criteria where ``_id`` is + equal to ``1``: .. code-block:: javascript - db.csbios.find( { _id: 1 } ) - db.csbios.find( { _id: { $gt: 3 } } ) - db.csbios.update( { _id: 1, name: { first: 'John', last: 'Backus' } }, - ... ) - -- The following document specifies the update actions: + { _id: 1 } + +- The following document specifies the query criteria where ``_id`` is + greater than ``3``: .. code-block:: javascript - { $set: { 'name.middle': 'Warner' }, - $push: { awards: { award: 'IBM Fellow', - year: '1963', - by: 'IBM' } + { _id: { $gt: 3 } } - When passed as an argument to the :method:`update() - ` method, the document specifies the update - actions to perform on the document: +- The following document specifies the compound query criteria where + ``_id`` is equal to ``1`` **and** the ``name`` field equals the + document ``{ first: 'John', last: 'Backus' }``: .. code-block:: javascript - db.csbios.update( { _id: 1 }, - { $set: { 'name.middle': 'Warner' }, - $push: { awards: { award: 'IBM Fellow', - year: '1963', - by: 'IBM' } } } - ) + { _id: 1, name: { first: 'John', last: 'Backus' } } -- The following document specifies the sort order: +- The following document specifies the compound query criteria where + ``_id`` is equal to ``1`` **or** the ``name`` field equals the + document ``{ first: 'John', last: 'Backus' }``: .. code-block:: javascript - { 'name.last': 1, 'name.first':1 } + { $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] } - When passed as an argument to the :method:`sort() ` - method, the document specifies the sort order of the results: +When passed as an argument to methods such as the :method:`find() +` method, the :method:`remove() +` method, or the :method:`update() +` method, the query selector document +determines which records are returned, removed, or updated: - .. code-block:: javascript +.. code-block:: javascript - db.csbios.find().sort( { 'name.last': 1, 'name.first': 1 } ) + db.csbios.find( { _id: 1 } ) + db.csbios.remove( { _id: { $gt: 3 } } ) + db.csbios.update( { _id: 1, name: { first: 'John', last: 'Backus' } }, + ... ) -- The following document specifies the multi-key index to create: +.. _documents-update-actions: - .. code-block:: javascript +Document as update actions +-------------------------- - { _id:1, 'name.last': 1 } +The update actions documents contain :ref:`update operators +` expressions. - When passed as an argument to the :method:`ensureIndex() - ` method, the document specifies the - multi-key index to create on the fields ``_id`` and ``name.last``: +Consider the following example of an update actions document: - .. code-block:: javascript +.. code-block:: javascript + + { $set: { 'name.middle': 'Warner' }, + $push: { awards: { award: 'IBM Fellow', + year: '1963', + by: 'IBM' } + +When passed as an argument to the :method:`update() +` method, the update actions document: + +- Modifies the field ``name`` whose value is another document. + Specifically, the :operator:`$set` operator updates the ``middle`` + field in the ``name`` subdocument. + +- Adds an element to the field ``awards`` whose value is an array. + Specifically, the :operator:`$push` operator adds another document as + element to the field ``awards``. + +.. code-block:: javascript + + db.csbios.update( { _id: 1 }, + { $set: { 'name.middle': 'Warner' }, + $push: { awards: { award: 'IBM Fellow', + year: '1963', + by: 'IBM' } } } + ) + +.. _documents-index: + +Document as index +----------------- + +The index documents contain ``field:value`` pairs where: + +- the ``field`` is the field to index on + +- the ``value`` is either 1 for ascending or -1 for descending. + +The following document specifies the multi-key index on the ``_id`` +field and the ``last`` field contained in the subdocument ``name`` +field: + +.. code-block:: javascript + + { _id:1, 'name.last': 1 } + +When passed as an argument to the :method:`ensureIndex() +` method, the index documents specifies +the index to create: + +.. code-block:: javascript + + db.csbios.ensureIndex( { _id: 1, 'name.last': 1 } ) + +.. _documents-sort-order: + +Document as sort order +---------------------- + +The sort order documents contain ``field:value`` pairs where: + +- the ``field`` is the field to sort + +- the ``value`` is either 1 for ascending or -1 for descending. + +The following document specifies the sort order using the fields from a +subdocument ``name``: first sort by the ``last`` field ascending, then +by the ``first`` field also ascending: + +.. code-block:: javascript + + { 'name.last': 1, 'name.first':1 } + +When passed as an argument to the :method:`sort() ` +method, the sort order document sorts the results of the +:method:`find() ` method: + +.. code-block:: javascript + + db.csbios.find().sort( { 'name.last': 1, 'name.first': 1 } ) - db.csbios.ensureIndex( { _id: 1, 'name.last': 1 } ) diff --git a/source/includes/fact-document-field-name-restrictions.rst b/source/includes/fact-document-field-name-restrictions.rst new file mode 100644 index 00000000000..f01d0c3e35e --- /dev/null +++ b/source/includes/fact-document-field-name-restrictions.rst @@ -0,0 +1,9 @@ +:doc:`/core/documents` stored as records in collections have the +following restrictions on the field names: + +- The field name ``_id`` is reserved for use as a primary key; its + value must be unique. + +- The field names must **not** start with the ``$`` character. + +- The field names must **not** contain the ``.`` character. diff --git a/source/includes/fact-document-max-size.rst b/source/includes/fact-document-max-size.rst new file mode 100644 index 00000000000..139879dfb3a --- /dev/null +++ b/source/includes/fact-document-max-size.rst @@ -0,0 +1 @@ +MongoDB v2.2 has a 16 megabytes limit on document size. \ No newline at end of file diff --git a/source/includes/fact-write-concerns.rst b/source/includes/fact-write-concerns.rst index c66ab176052..dea333ec82a 100644 --- a/source/includes/fact-write-concerns.rst +++ b/source/includes/fact-write-concerns.rst @@ -5,5 +5,6 @@ command to confirm the result of the write operation: { getLastError: 1 } -Refer to the documentation on :ref:`write concern ` and -:doc:`/applications/write-operations` for more information. +Refer to the documentation on :ref:`write concern +` in the :doc:`/core/write-operations` +section for more information. diff --git a/source/includes/note-insert-id-field.rst b/source/includes/note-insert-id-field.rst index a04cf91c64c..be74da1822e 100644 --- a/source/includes/note-insert-id-field.rst +++ b/source/includes/note-insert-id-field.rst @@ -1,7 +1,7 @@ .. note:: - Most MongoDB clients will include ``_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 :program:`mongod` will add the ``_id`` field and generate the - ``ObjectId``. + 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 :program:`mongod` will add the ``_id`` field and generate + the ``ObjectId``. diff --git a/source/includes/warning-document-field-name-restrictions.rst b/source/includes/warning-document-field-name-restrictions.rst deleted file mode 100644 index e50d1fb1cf2..00000000000 --- a/source/includes/warning-document-field-name-restrictions.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. warning:: - - :doc:`core/documents` stored as records in collections have - the following restrictions on the field names: - - - The field names must **not** start with the ``$`` character. - - - The field names must **not** contain the ``.`` character.