merge: DOCS-800

Author: Sam Kleinman

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 }
-                      }
-            }
-          }
-       )
+    In this query, the parameters (i.e. the selections of both fields)
+    combine using an implicit logical AND for criteria on different
+    fields ``contribs`` and ``name.first``. For multiple AND criteria
+    on the same field, use the :operator:`$and` operator.
 
 - If there is a ``<projection>`` argument, the :method:`find()
   <db.collection.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,16 @@ Consider the following examples that illustrate the use of the
           }
        )
 
+.. seealso::
+
+   - :term:`dot notation` for information on "reaching into" embedded
+     sub-documents.
+
+   - :ref:`read-operations-arrays` for more examples on accessing arrays
+
+   - :ref:`read-operations-subdocuments` for more examples on accessing
+     subdocuments
+
 Cursor
 ~~~~~~
 

source/applications/update.txt

@@ -73,7 +73,8 @@ Consider the following examples that illustrate the use of the
 - If the ``<update>`` argument contains only :ref:`update operator
   <update-operators>` expressions such as the :operator:`$set` operator
   expression, the :method:`update() <db.collection.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() <db.collection.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() <db.collection.update()>` method can perform
     the update of an array that contains subdocuments by using the
-    :operator:`$` positional operator and the :wiki:`dot notation
-    <Dot+Notation+(Reaching+into+Objects)>`.
+    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``

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,21 @@ 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.
+
 Document Types in MongoDB
 -------------------------
 
@@ -215,44 +235,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 </reference/operators>` expressions to specify additional
-conditions. Refer to :doc:`read </applications/read>`, :doc:`update
-</applications/update>`, and :doc:`delete </applications/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
+``<field>:<value>`` expressions to specify the equality condition and
+:doc:`query operator </reference/operators>` expressions to specify
+additional conditions.
 
 When passed as an argument to methods such as the :method:`find()
 <db.collection.find()>` method, the :method:`remove()
@@ -265,7 +251,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' } },
-                       ... )
+                   <update>,
+                   <options> )
+
+.. 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 +275,14 @@ Update documents specify the data modifications to perform during
 an :method:`update() <db.collection.update()>` operation to modify
 existing records in a collection. You can use :ref:`update operators
 <update-operators>` to specify the exact actions to perform on the
-document fields. See the :ref:`update operators <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 +294,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 <document-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 +305,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 +316,18 @@ When passed as an argument to the :method:`update()
       }
    )
 
+.. seealso::
+
+   - :ref:`update operators <update-operators>` page for the available
+     update operators and syntax.
+
+   - :doc:`update </applications/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 +348,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 <index-type-multi-key>` on the ``_id``
-field and the ``last`` field contained in the subdocument ``name``
-field:
+The following document specifies the :ref:`multi-key index
+<index-type-multi-key>` on the ``_id`` field and the ``last`` field
+contained in the subdocument ``name`` field. The document uses
+:ref:`dot notation <document-dot-notation>` to access a field in a
+subdocument:
 
 .. code-block:: javascript
 
@@ -355,7 +370,6 @@ the index to create:
    </core/read-operations>` and :doc:`write </core/write-operations>`
    operations.
 
-
 .. _documents-sort-order:
 
 Sort Order Specification Documents
@@ -397,8 +411,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: