From ab47d24b93fc638ead3091bf51dbb0d831e502fa Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 27 Nov 2012 19:54:58 -0500 Subject: [PATCH 1/2] DOCS-800 added dot notation documentation --- source/applications/read.txt | 63 ++++++++----- source/applications/update.txt | 7 +- source/core/document.txt | 93 +++++++++++++++++-- source/core/read-operations.txt | 156 +++++++++++++++++++++++++++++--- source/reference/glossary.txt | 19 ++++ 5 files changed, 293 insertions(+), 45 deletions(-) diff --git a/source/applications/read.txt b/source/applications/read.txt index 8b2ea9b58db..9b44e99aa1d 100644 --- a/source/applications/read.txt +++ b/source/applications/read.txt @@ -124,9 +124,11 @@ Consider the following examples that illustrate the use of the } ) + *Arrays* + - 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 +137,36 @@ 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 } + } + } + } + ) + + For more examples on accessing arrays, see :ref:`query documents + for arrays ` and :ref:`read operations + `. + + *Subdocuments* - 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 +178,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: @@ -201,6 +228,12 @@ Consider the following examples that illustrate the use of the first: 'Yukihiro' } + For more examples on accessing subdocuments, see :ref:`query + documents for subdocuments ` and + :ref:`read operations `. + + *Compound Query Criteria* + - The following operation returns all documents in the ``bios`` collection where either the field ``first`` in the sub-document ``name`` starts with the letter ``G`` **or** where the field @@ -230,24 +263,6 @@ 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 } - } - } - } - ) - - If there is a ```` argument, the :method:`find() ` method returns only those fields as specified in the ```` argument to include or exclude: @@ -282,7 +297,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: diff --git a/source/applications/update.txt b/source/applications/update.txt index 8f74b99c028..29c7aed3ef0 100644 --- a/source/applications/update.txt +++ b/source/applications/update.txt @@ -161,8 +161,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 +196,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 - `. + :operator:`$` positional 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..80d5b0e864b 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -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. @@ -246,6 +246,9 @@ Consider the following examples of query documents: { _id: 1, name: { first: 'John', last: 'Backus' } } + The ``name`` field must match the document exactly, including the + order of the fields. + - 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' }``: @@ -254,6 +257,79 @@ Consider the following examples of query documents: { $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] } + The ``name`` field must match the document exactly, including the + order of the fields. + +.. _document-query-arrays: + +*Query Documents for Arrays* + +You can specify query criteria for arrays at the array level and, with +:term:`dot-notation`, at the element level: + +- The following document specifies the query criteria where + ``contribs`` matches exactly the array ``[ 'Fortran', 'ALGOL', + 'Backus-Naur Form', 'FP' ]``, including the order of the elements: + + .. code-block:: javascript + + { contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ] } + +- The following document specifies the query criteria where the value + of ``contribs`` is an array that contains as one of its element + ``'ALGOL'``: + + .. code-block:: javascript + + { contribs: 'ALGOL' } + +- The following document specifies the query criteria where + ``contribs`` contains an element ``'ALGOL'`` in the second position. + Array indexes are zero-based: + + .. code-block:: javascript + + { 'contribs.1': 'ALGOL' } + +See :ref:`read operations ` for more +examples with arrays. + +.. _document-query-subdocuments: + +*Query Documents for Subdocuments* + +You can specify query criteria for subdocuments at the subdocument +level and, with :term:`dot-notation`, at the field level: + +- The following document specifies the query criteria where the value + of the field ``name`` is a subdocument that contains *only* the field + ``first`` equal to ``'John'`` and the field ``last`` equal to + ``'Backus'``, in that order. + + .. code-block:: javascript + + { name: { first: 'John', last: 'Backus' } } + +- The following document specifies the query criteria where the value + of the field ``name`` is a subdocument that contains the field + ``first`` equal to ``'John'`` and may contain other fields: + + .. code-block:: javascript + + { 'name.first': 'John' } + +- The following document specifies the query criteria where the value + of the field ``awards`` is an array that contains, as one of its + elements, a subdocument that contains the field ``award`` equal to + ``'National Medal of Science'`` and may contain other fields: + + .. code-block:: javascript + + { 'awards.award': 'National Medal of Science' } + +See :ref:`read operations ` for +more examples with subdocuments. + When passed as an argument to methods such as the :method:`find() ` method, the :method:`remove() ` method, or the :method:`update() @@ -295,7 +371,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 + :term:`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 @@ -315,6 +392,10 @@ When passed as an argument to the :method:`update() } ) +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 +416,10 @@ 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 +:term:`dot-notation` to access a field in a subdocument: .. code-block:: javascript @@ -355,7 +437,6 @@ the index to create: ` and :doc:`write ` operations. - .. _documents-sort-order: Sort Order Specification Documents diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt index c13048dd6e3..985ae9b2bdc 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,147 @@ collection of documents named ``inventory``: { price: { $lt: 9.95 } } ] } ) +.. _read-operations-dot-notation-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-dot-notation-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-dot-notation-array-of-subdocuments: + +*Array 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 +441,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/reference/glossary.txt b/source/reference/glossary.txt index e2b2ca53c46..e1e626a0289 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -903,3 +903,22 @@ 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 + 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 + + '.' From cbd983a9ee4b1ca48eb485aeb516abe3adf4d5ed Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 28 Nov 2012 15:27:25 -0500 Subject: [PATCH 2/2] DOCS-800 dot-notation edits --- source/applications/read.txt | 30 ++-- source/applications/update.txt | 7 +- source/core/document.txt | 194 +++++++++---------------- source/core/read-operations.txt | 99 +++++++------ source/includes/fact-dot-notation.rst | 17 +++ source/includes/fact-write-concern.rst | 4 - source/reference/glossary.txt | 20 +-- 7 files changed, 154 insertions(+), 217 deletions(-) create mode 100644 source/includes/fact-dot-notation.rst diff --git a/source/applications/read.txt b/source/applications/read.txt index 9b44e99aa1d..35f4d230d68 100644 --- a/source/applications/read.txt +++ b/source/applications/read.txt @@ -124,8 +124,6 @@ Consider the following examples that illustrate the use of the } ) - *Arrays* - - The following operation returns all documents in the ``bios`` collection where the array field ``contribs`` contains the element ``'UNIX'``: @@ -156,16 +154,10 @@ Consider the following examples that illustrate the use of the } ) - For more examples on accessing arrays, see :ref:`query documents - for arrays ` and :ref:`read operations - `. - - *Subdocuments* - - 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'``; the query uses :term:`dot-notation` to + the value ``'Matsumoto'``; the query uses :term:`dot notation` to access fields in a subdocument: .. code-block:: javascript @@ -228,12 +220,6 @@ Consider the following examples that illustrate the use of the first: 'Yukihiro' } - For more examples on accessing subdocuments, see :ref:`query - documents for subdocuments ` and - :ref:`read operations `. - - *Compound Query Criteria* - - The following operation returns all documents in the ``bios`` collection where either the field ``first`` in the sub-document ``name`` starts with the letter ``G`` **or** where the field @@ -263,6 +249,11 @@ Consider the following examples that illustrate the use of the } ) + 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 in the ```` argument to include or exclude: @@ -323,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 29c7aed3ef0..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 @@ -162,7 +163,7 @@ Consider the following examples that illustrate the use of the - The :method:`update() ` method can perform the update using the position of the element and - :term:`dot-notation`. Arrays in MongoDB are zero-based. + :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,7 +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 :term:`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 80d5b0e864b..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: @@ -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,121 +238,11 @@ 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 ``name`` field must match the document exactly, including the - order of the fields. - -- 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' } } ] } - - The ``name`` field must match the document exactly, including the - order of the fields. - -.. _document-query-arrays: - -*Query Documents for Arrays* - -You can specify query criteria for arrays at the array level and, with -:term:`dot-notation`, at the element level: - -- The following document specifies the query criteria where - ``contribs`` matches exactly the array ``[ 'Fortran', 'ALGOL', - 'Backus-Naur Form', 'FP' ]``, including the order of the elements: - - .. code-block:: javascript - - { contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ] } - -- The following document specifies the query criteria where the value - of ``contribs`` is an array that contains as one of its element - ``'ALGOL'``: - - .. code-block:: javascript - - { contribs: 'ALGOL' } - -- The following document specifies the query criteria where - ``contribs`` contains an element ``'ALGOL'`` in the second position. - Array indexes are zero-based: - - .. code-block:: javascript - - { 'contribs.1': 'ALGOL' } - -See :ref:`read operations ` for more -examples with arrays. - -.. _document-query-subdocuments: - -*Query Documents for Subdocuments* - -You can specify query criteria for subdocuments at the subdocument -level and, with :term:`dot-notation`, at the field level: - -- The following document specifies the query criteria where the value - of the field ``name`` is a subdocument that contains *only* the field - ``first`` equal to ``'John'`` and the field ``last`` equal to - ``'Backus'``, in that order. - - .. code-block:: javascript - - { 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. -- The following document specifies the query criteria where the value - of the field ``name`` is a subdocument that contains the field - ``first`` equal to ``'John'`` and may contain other fields: - - .. code-block:: javascript - - { 'name.first': 'John' } - -- The following document specifies the query criteria where the value - of the field ``awards`` is an array that contains, as one of its - elements, a subdocument that contains the field ``award`` equal to - ``'National Medal of Science'`` and may contain other fields: - - .. code-block:: javascript - - { 'awards.award': 'National Medal of Science' } - -See :ref:`read operations ` for -more examples with subdocuments. - When passed as an argument to methods such as the :method:`find() ` method, the :method:`remove() ` method, or the :method:`update() @@ -341,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: @@ -352,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' } @@ -371,8 +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. The document uses - :term:`dot-notation` to access a field in a 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 @@ -382,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', @@ -392,6 +319,14 @@ 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. @@ -418,8 +353,9 @@ Index documents contain field and value pairs, in the following form: 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 -:term:`dot-notation` to access a field in a subdocument: +contained in the subdocument ``name`` field. The document uses +:ref:`dot notation ` to access a field in a +subdocument: .. code-block:: javascript @@ -478,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 985ae9b2bdc..70b189aa867 100644 --- a/source/core/read-operations.txt +++ b/source/core/read-operations.txt @@ -200,49 +200,13 @@ collection of documents named ``inventory``: { price: { $lt: 9.95 } } ] } ) -.. _read-operations-dot-notation-arrays: +.. _read-operations-subdocuments: -*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-dot-notation-subdocuments: - -*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 +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 @@ -260,7 +224,7 @@ subdocument level: producer: { company: 'ABC123', address: '123 Street' - } + } } ) @@ -268,7 +232,7 @@ subdocument level: 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 + 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: @@ -277,12 +241,51 @@ subdocument level: db.inventory.find( { 'producer.company': 'ABC123' } ) -.. _read-operations-dot-notation-array-of-subdocuments: +.. _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: -*Array 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. +: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. @@ -307,10 +310,10 @@ When a field contains an array of subdocuments you can use db.inventory.find( { 'memos.by': 'shipping' } ) - To match by multiple fields in the subdocument, you can use either - dot-notation or the :doc:`$elemMatch ` + dot notation or the :doc:`$elemMatch ` operator: - The following example uses dot-notation to query for documents + 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'``: @@ -442,7 +445,7 @@ operation: db.collection.ensureIndex( { : , : , ... } ) - The ``field`` specifies the field to index. The field may be a field - from a subdocument, using :term:`dot-notation` to specify subdocument + 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 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 e1e626a0289..7f3f51818cf 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -904,21 +904,5 @@ Glossary disk. MongoDB calls ``fsync()`` on its database files at least every 60 seconds. - dot-notation - 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 - - '.' + dot notation + .. include:: /includes/fact-dot-notation.rst