DOCS-800 dot-notation edits

Author: kay-kim

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 <document-query-arrays>` and :ref:`read operations
-    <read-operations-dot-notation-arrays>`.
-
-  *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 <document-query-subdocuments>` and
-    :ref:`read operations <read-operations-dot-notation-subdocuments>`.
-
-  *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 ``<projection>`` argument, the :method:`find()
   <db.collection.find()>` method returns only those fields as specified
   in the ``<projection>`` 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
 ~~~~~~
 

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
@@ -162,7 +163,7 @@ Consider the following examples that illustrate the use of the
 
   - The :method:`update() <db.collection.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() <db.collection.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``

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 </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 ``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 <read-operations-dot-notation-arrays>` 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
+``<field>:<value>`` expressions to specify the equality condition and
+:doc:`query operator </reference/operators>` 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 <read-operations-dot-notation-subdocuments>` for
-more examples with subdocuments.
-                
 When passed as an argument to methods such as the :method:`find()
 <db.collection.find()>` method, the :method:`remove()
 <db.collection.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' } },
-                       ... )
+                   <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:
 
@@ -352,14 +278,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' }
@@ -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 <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
@@ -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 <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.
@@ -418,8 +353,9 @@ Index documents contain field and value pairs, in the following form:
 
 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
-:term:`dot-notation` to access a field in a subdocument:
+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
 
@@ -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: