diff --git a/source/applications/read.txt b/source/applications/read.txt index 8b2ea9b58db..35f4d230d68 100644 --- a/source/applications/read.txt +++ b/source/applications/read.txt @@ -126,7 +126,7 @@ Consider the following examples that illustrate the use of the - The following operation returns all documents in the ``bios`` collection where the array field ``contribs`` contains the element - ``UNIX``: + ``'UNIX'``: .. code-block:: javascript @@ -135,11 +135,30 @@ Consider the following examples that illustrate the use of the contribs: 'UNIX' } ) + + - The following operation returns all documents in the ``bios`` + collection where ``awards`` array contains a subdocument element + that contains the ``award`` field equal to ``'Turing Award'`` and the + ``year`` field greater than 1980: + + .. code-block:: javascript + + db.bios.find( + { + awards: { + $elemMatch: { + award: 'Turing Award', + year: { $gt: 1980 } + } + } + } + ) - The following operation returns all documents in the ``bios`` collection where the subdocument ``name`` contains a field - ``first`` with the value ``Yukihiro`` and a field ``last`` with the - value ``Matsumoto``: + ``first`` with the value ``'Yukihiro'`` and a field ``last`` with + the value ``'Matsumoto'``; the query uses :term:`dot notation` to + access fields in a subdocument: .. code-block:: javascript @@ -151,8 +170,8 @@ Consider the following examples that illustrate the use of the ) The query matches the document where the ``name`` field contains a - subdocument with the field ``first`` with the value ``Yukihiro`` - and a field ``last`` with the value ``Matsumoto``. For instance, + subdocument with the field ``first`` with the value ``'Yukihiro'`` + and a field ``last`` with the value ``'Matsumoto'``. For instance, the query would match documents with ``name`` fields that held either of the following values: @@ -230,23 +249,10 @@ Consider the following examples that illustrate the use of the } ) - - The following operation returns all documents in the ``bios`` - collection where ``awards`` array contains a subdocument element - that contains the ``award`` field equal to ``Turing Award`` and the - ``year`` field greater than 1980: - - .. code-block:: javascript - - db.bios.find( - { - awards: { - $elemMatch: { - award: 'Turing Award', - year: { $gt: 1980 } - } - } - } - ) + The query uses the comma to specify the logical AND for criteria on + different fields ``contribs`` and ``name.first``. For multiple AND + criteria on the same field, use the :operator:`$and` operator + instead of the comma. - If there is a ```` argument, the :method:`find() ` method returns only those fields as specified @@ -282,7 +288,7 @@ Consider the following examples that illustrate the use of the - The following operation finds the documents in the ``bios`` collection where the ``contribs`` field contains the element - ``OOP`` and returns all fields *except* the ``_id`` field, the + ``'OOP'`` and returns all fields *except* the ``_id`` field, the ``first`` field in the ``name`` subdocument, and the ``birth`` field from the matching documents: @@ -308,6 +314,15 @@ Consider the following examples that illustrate the use of the } ) +.. seealso:: + + - :term:`dot notation` for information on dot notation + + - :ref:`read-operations-arrays` for more examples on accessing arrays + + - :ref:`read-operations-subdocuments` for more examples on accessing + subdocuments + Cursor ~~~~~~ diff --git a/source/applications/update.txt b/source/applications/update.txt index 8f74b99c028..5535d9ff450 100644 --- a/source/applications/update.txt +++ b/source/applications/update.txt @@ -73,7 +73,8 @@ Consider the following examples that illustrate the use of the - If the ```` argument contains only :ref:`update operator ` expressions such as the :operator:`$set` operator expression, the :method:`update() ` method - updates the corresponding fields in the document. + updates the corresponding fields in the document. To update fields in + subdocuments, MongoDB uses :term:`dot notation`. The following operation queries the ``bios`` collection for the first document that has an ``_id`` field equal to ``1`` and sets the field @@ -161,8 +162,8 @@ Consider the following examples that illustrate the use of the field: - The :method:`update() ` method can perform - the update using the position of the element. Arrays in MongoDB are - zero-based. + the update using the position of the element and + :term:`dot notation`. Arrays in MongoDB are zero-based. The following operation queries the ``bios`` collection for the first document with ``_id`` field equal to ``1`` and updates the @@ -196,8 +197,7 @@ Consider the following examples that illustrate the use of the - The :method:`update() ` method can perform the update of an array that contains subdocuments by using the - :operator:`$` positional operator and the :wiki:`dot notation - `. + positional operator (i.e. :operator:`$`) and the :term:`dot notation`. The following operation queries the ``bios`` collection for the first document where the ``_id`` field equals ``6`` and the ``awards`` diff --git a/source/core/document.txt b/source/core/document.txt index ce2dd4bb5f8..a9f03c3ff98 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -56,10 +56,10 @@ the following structure: fieldN: valueN } -Having support for the full range of :term:`BSON types`, MongoDB -documents may contain field and 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``, and ``Date``. See also +Having support for the full range of BSON types, MongoDB documents may +contain field and 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``, and ``Date``. See also :ref:`document-bson-type-considerations`. Consider the following document that contains values of varying types: @@ -79,7 +79,7 @@ The document contains the following fields: - ``_id`` that holds an *ObjectId*. -- ``name`` that holds a *sub-document* that contains the fields +- ``name`` that holds a *subdocument* that contains the fields ``first`` and ``last``. - ``birth`` and ``death``, which both have *Date* types. @@ -88,6 +88,11 @@ The document contains the following fields: - ``views`` that holds a value of *NumberLong* type. +.. _document-type-operators: + +Type Operators +~~~~~~~~~~~~~~ + To determine the type of fields, the :program:`mongo` shell provides the following operators: @@ -119,6 +124,24 @@ the following operators: In this case ``typeof`` will return the more generic ``object`` type rather than ``ObjectId`` type. +.. _document-dot-notation: + +Dot Notation +~~~~~~~~~~~~ + +.. include:: /includes/fact-dot-notation.rst + +.. seealso:: + + - :ref:`read-operations-subdocuments` for dot notation examples + with subdocuments. + + - :ref:`read-operations-arrays` for dot notation examples with + arrays. + + - :ref:`read-operations-arrays-of-subdocuments` for dot notation + examples with arrays of subdocuments. + Document Types in MongoDB ------------------------- @@ -215,44 +238,10 @@ Query Specification Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Query documents specify the conditions that determine which records to -select for read, update, and delete operations. You can use field and -value expressions to specify the equality condition and :doc:`query -operator ` expressions to specify additional -conditions. Refer to :doc:`read `, :doc:`update -`, and :doc:`delete ` pages -for more examples. - -Consider the following examples of query documents: - -- The following document specifies the query criteria where ``_id`` is - equal to ``1``: - - .. code-block:: javascript - - { _id: 1 } - -- The following document specifies the query criteria where ``_id`` is - greater than ``3``: - - .. code-block:: javascript - - { _id: { $gt: 3 } } - -- 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 - - { _id: 1, name: { first: 'John', last: 'Backus' } } - -- 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 - - { $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] } +select for read, update, and delete operations. You can use +``:`` expressions to specify the equality condition and +:doc:`query operator ` expressions to specify +additional conditions. When passed as an argument to methods such as the :method:`find() ` method, the :method:`remove() @@ -265,7 +254,20 @@ for MongoDB to return, remove, or update, as in the following: db.bios.find( { _id: 1 } ) db.bios.remove( { _id: { $gt: 3 } } ) db.bios.update( { _id: 1, name: { first: 'John', last: 'Backus' } }, - ... ) + , + ) + +.. seealso:: + + - :ref:`read-operations-query-argument` and + :doc:`/applications/read` for more examples on selecting documents + for reads. + + - :doc:`/applications/update` for more examples on + selecting documents for updates. + + - :doc:`/applications/delete` for more examples on selecting + documents for deletes. .. _documents-update-actions: @@ -276,14 +278,14 @@ Update documents specify the data modifications to perform during an :method:`update() ` operation to modify existing records in a collection. You can use :ref:`update operators ` to specify the exact actions to perform on the -document fields. See the :ref:`update operators ` -page for the available update operators and syntax. +document fields. Consider the update document example: .. code-block:: javascript - { $set: { 'name.middle': 'Warner' }, + { + $set: { 'name.middle': 'Warner' }, $push: { awards: { award: 'IBM Fellow', year: '1963', by: 'IBM' } @@ -295,7 +297,8 @@ When passed as an argument to the :method:`update() - Modifies the field ``name`` whose value is another document. Specifically, the :operator:`$set` operator updates the ``middle`` - field in the ``name`` subdocument. + field in the ``name`` subdocument. The document uses :ref:`dot + notation ` to access a field in a subdocument. - Adds an element to the field ``awards`` whose value is an array. Specifically, the :operator:`$push` operator adds another document as @@ -305,7 +308,8 @@ When passed as an argument to the :method:`update() db.bios.update( { _id: 1 }, - { $set: { 'name.middle': 'Warner' }, + { + $set: { 'name.middle': 'Warner' }, $push: { awards: { award: 'IBM Fellow', year: '1963', @@ -315,6 +319,18 @@ When passed as an argument to the :method:`update() } ) +.. seealso:: + + - :ref:`update operators ` page for the available + update operators and syntax. + + - :doc:`update ` for more examples on + update documents. + +For additional examples of updates that involve array elements, +including where the elements are documents, see the :operator:`$` +positional operator. + .. _documents-index: .. _document-index-specification: @@ -335,9 +351,11 @@ Index documents contain field and value pairs, in the following form: - ``value`` is either 1 for ascending or -1 for descending. -The following document specifies the :ref:`multi-key index ` on the ``_id`` -field and the ``last`` field contained in the subdocument ``name`` -field: +The following document specifies the :ref:`multi-key index +` on the ``_id`` field and the ``last`` field +contained in the subdocument ``name`` field. The document uses +:ref:`dot notation ` to access a field in a +subdocument: .. code-block:: javascript @@ -355,7 +373,6 @@ the index to create: ` and :doc:`write ` operations. - .. _documents-sort-order: Sort Order Specification Documents @@ -397,8 +414,8 @@ method, the sort order document sorts the results of the .. _document-mongodb-type-considerations: .. _document-bson-type-considerations: -BSON Types ----------- +BSON Type Considerations +------------------------ The following BSON types require special consideration: diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt index c13048dd6e3..70b189aa867 100644 --- a/source/core/read-operations.txt +++ b/source/core/read-operations.txt @@ -134,15 +134,6 @@ collection of documents named ``inventory``: db.inventory.find( { type: "snacks" } ) - When the field holds an array an equality match will select documents if at - least *one* element in the array match the specified value. In the - following example, the query will match all documents where the array - in the ``tags`` field contains the element ``fruit``: - - .. code-block:: javascript - - db.inventory.find( { tags: "fruit" } ) - - A single-clause query document can also select all documents in a collection given a condition or set of conditions for one field in the collection's documents. Use the :ref:`query operators @@ -170,7 +161,7 @@ collection of documents named ``inventory``: In the following example, the query document specifies an equality match on a single field, followed by a range of values for a second - field using a :ref:`comparison operator `. + field using a :ref:`comparison operator `: .. code-block:: javascript @@ -209,6 +200,150 @@ collection of documents named ``inventory``: { price: { $lt: 9.95 } } ] } ) +.. _read-operations-subdocuments: + +Subdocuments +```````````` + +When the field holds a subdocument, you can query at the subdocument +level or, with the use of :term:`dot notation`, at the fields of the +subdocument level: + +- Equality match at the subdocument level will select documents if the + subdocument matches *exactly* the specified subdocument, including the + field order. + + In the following example, the query will match all documents where + the value of the field ``producer`` is a subdocument that contains + *only* the field ``company`` with the value ``'ABC123'`` and the field + ``address`` with the value ``'123 Street'``, in the exact order + + .. code-block:: javascript + + db.inventory.find( { + producer: { + company: 'ABC123', + address: '123 Street' + } + } + ) + +- Equality match at the field level for subdocuments will select + documents if the subdocument contains a field that matches the + specified value: + + In the following example, the query uses the :term:`dot notation` to match + all documents where the value of the field ``producer`` is a + subdocument that contains a field ``company`` with the value + ``'ABC123'`` and may contain other fields: + + .. code-block:: javascript + + db.inventory.find( { 'producer.company': 'ABC123' } ) + +.. _read-operations-arrays: + +Arrays +```````` + +When the field holds an array, you can query at the array level and at +the element level: + +- Equality match at the array level will select documents if the array + matches exactly the specified array, including the element order. In + the following example, the query will match all documents where the + value of the field ``tags`` is an array with only three elements, + ``'fruit'``, ``'food'``, and ``'citrus'``, in that order: + + .. code-block:: javascript + + db.inventory.find( { tags: [ 'fruit', 'food', 'citrus' ] } ) + +- Equality match at the element level can either check if the array + contains at least *one* element with the specified value or if the + element at a specified position equals the specified value. + + In the following example, the query will match all documents where + the value of the field ``tags`` is an array that contains, as one of + its elements, the element ``'fruit'``: + + .. code-block:: javascript + + db.inventory.find( { tags: 'fruit' } ) + + In the following example, the query uses the :term:`dot notation` to match + all documents where the value of the ``tags`` field is an array whose + first element equals ``'fruit'``: + + .. code-block:: javascript + + db.inventory.find( { 'tags.0' : 'fruit' } ) + +.. _read-operations-arrays-of-subdocuments: + +Arrays of Subdocuments +^^^^^^^^^^^^^^^^^^^^^^ + +When a field contains an array of subdocuments you can use +:term:`dot notation` to query by the fields of the subdocument. + +- If you know the index position of the subdocument, you can specify + the array position. + + The following example selects all documents where the ``memos`` + contains an array whose first element (i.e. index is ``0``) is a + subdocument with the field ``by`` with the value ``'shipping'``: + + .. code-block:: javascript + + db.inventory.find( { 'memos.0.by': 'shipping' } ) + +- If you do not know the specific index position, concatenate the array + name with the dot (``.``) and the field name. + + The following example selects all documents where the ``memos`` field + contains an array that contains at least one subdocument with the + field ``by`` with the value ``'shipping'``: + + .. code-block:: javascript + + db.inventory.find( { 'memos.by': 'shipping' } ) + +- To match by multiple fields in the subdocument, you can use either + dot notation or the :doc:`$elemMatch ` + operator: + + The following example uses dot notation to query for documents + where the value of the ``memos`` field is an array that has at least + one subdocument that contains the field ``memo`` equal to ``'on time'`` + and the field ``by`` equal to ``'shipping'``: + + .. code-block:: javascript + + db.inventory.find( + { + 'memos.memo': 'on time', + 'memos.by': 'shipping' + } + ) + + The following example uses :doc:`$elemMatch + ` to query for documents where the + value of the ``memos`` field is an array that has at least one + subdocument that contains the field ``memo`` equal to ``'on time'`` and + the field ``by`` equal to ``'shipping'``: + + .. code-block:: javascript + + db.inventory.find( { memos: { + $elemMatch: { + memo : 'on time', + by: 'shipping' + } + } + } + ) + Refer to the :doc:`/reference/operator` document for the complete list of query operators and :doc:`/reference/operators` for complete documentation of all query operators. @@ -309,7 +444,9 @@ operation: db.collection.ensureIndex( { : , : , ... } ) -- The ``field`` specifies the field to index. +- The ``field`` specifies the field to index. The field may be a field + from a subdocument, using :term:`dot notation` to specify subdocument + fields. You can create an index on a single field or a :ref:`compound index ` that includes multiple fields in the index. diff --git a/source/includes/fact-dot-notation.rst b/source/includes/fact-dot-notation.rst new file mode 100644 index 00000000000..f34573b70df --- /dev/null +++ b/source/includes/fact-dot-notation.rst @@ -0,0 +1,17 @@ +MongoDB uses the *dot notation* to access the elements of an array and +to access the fields of a subdocument. + +To access an element of an array by the zero-based index position, you +concatenate the array name with the dot (``.``) and zero-based index +position: + +.. code-block:: javascript + + '.' + +To access a field of a subdocument with *dot-notation*, you concatenate +the subdocument name with the dot (``.``) and the field name: + +.. code-block:: javascript + + '.' diff --git a/source/includes/fact-write-concern.rst b/source/includes/fact-write-concern.rst index 32e3f53cc82..a35c38501fe 100644 --- a/source/includes/fact-write-concern.rst +++ b/source/includes/fact-write-concern.rst @@ -6,9 +6,5 @@ confirm the result of the write operation: { getLastError: 1 } -Refer to the documentation on :ref:`write concern -` in the :doc:`/core/write-operations` -section for more information. - Refer to the documentation on :ref:`write concern ` and :doc:`/core/write-operations` for more information. diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index e2b2ca53c46..7f3f51818cf 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -903,3 +903,6 @@ Glossary A system call that flushes all dirty, in-memory pages to disk. MongoDB calls ``fsync()`` on its database files at least every 60 seconds. + + dot notation + .. include:: /includes/fact-dot-notation.rst