merge DOCS-799

Author: Sam Kleinman

source/administration/indexes.txt

@@ -44,7 +44,7 @@ all documents in a collection for documents that match the query.
       db.records.find( { user_id: 2 } )
 
    However, the following query, on the ``profile_url`` field is not
-   supported by this index::
+   supported by this index:
 
    .. code-block:: javascript
 

source/core/read-operations.txt

@@ -34,7 +34,7 @@ In the :program:`mongo` shell, the :method:`find()
 <db.collection.find()>` and :method:`findOne()
 <db.collection.findOne()>` methods perform read operations. The
 :method:`find() <db.collection.find()>` method has the following
-syntax:
+syntax [#formal-query-structure]_:
 
 .. code-block:: javascript
 
@@ -69,7 +69,7 @@ syntax:
   necessarily consistent unless you specify a sort (:method:`sort()
   <cursor.sort()>`).
 
-For example, the following operation on the ``inventory`` collection,
+For example, the following operation on the ``inventory`` collection
 selects all documents where the ``type`` field equals ``'food'`` and
 the ``price`` field has a value less than ``9.95``. The projection
 limits the response to the ``item`` and ``qty``, and ``_id`` field:
@@ -93,6 +93,20 @@ For additional documentation and examples of the main MongoDB read
 operators, refer to the :doc:`/applications/read` page of the
 :doc:`/crud` section.
 
+.. [#formal-query-structure]
+   :method:`db.collection.find( \<query\>, \<projection\> )
+   <db.collection.find()>` is a wrapper for the more formal query
+   structure with the :operator:`$query` operator:
+
+   .. code-block:: javascript
+
+      db.collection.find( { $query: <query>, ... }, <projection> )
+
+   Within the formal structure, in addition to the :operator:`$query`
+   operator, you can use the :doc:`meta query operators
+   </reference/meta-query-operators>` to modify the behavior of the
+   query.
+
 .. _read-operations-query-document:
 .. _read-operations-query-argument:
 
@@ -543,7 +557,7 @@ the query used an index. This query:
 - returned 5 documents, as indicated by the :data:`n` field;
 
 - scanned 5 documents from the index, as indicated by the
-  :data:`nscanned`` field;
+  :data:`nscanned` field;
 
 - then read 5 full documents from the collection, as indicated by
   the :data:`nscannedObjects` field.

source/reference/meta-query-operators.txt

@@ -11,25 +11,25 @@ Introduction
 
 In addition to the :doc:`MongoDB Query Operators
 </reference/operators>`, there are a number of "meta" operators that
-you may use to modify the output or behavior of a
-query. Specify these modifiers to a :method:`db.collection.find()` query, in the
-following form (for the :program:`mongo` shell):
+you may use to modify the output or behavior of a query. On the server,
+MongoDB treats the query and the options as a single object. The
+:program:`mongo` shell may provide :ref:`cursor methods
+<js-query-cursor-methods>` for these options. When possible, use these
+methods; otherwise, you can add these options using either of the
+following syntax:
 
 .. code-block:: javascript
 
-   db.collection.find( { [QUERY] } )._addSpecial( [MODIFIER] )
-
-Here, the query specified by ``[QUERY]`` runs on the collection
-named ``collection`` with the operation specified by the
-``[MODIFIER]``. The results are then processed by a modifier expression
-selected from the following list. Many of the operators have
-corresponding :doc:`methods in the shell </reference/javascript>`. For
-the proposes of this reference, this document assumes the above form
-where possible.
+   db.collection.find( { <query> } )._addSpecial( <option> )
+   db.collection.find( { $query: { <query> }, <option> } )
 
 Modifiers
 ---------
 
+Many of these operators have corresponding :ref:`methods in the shell
+<js-query-cursor-methods>`. These methods provide a straightforward and
+user-friendly interface and are the preferred way to add these options.
+
 .. include:: operator/returnKey.txt
    :start-after: mongodb
 
@@ -42,6 +42,9 @@ Modifiers
 .. include:: operator/comment.txt
    :start-after: mongodb
 
+.. include:: operator/max.txt
+   :start-after: mongodb
+   
 .. include:: operator/min.txt
    :start-after: mongodb
 

source/reference/operator/comment.txt

@@ -7,13 +7,12 @@ $comment
 .. operator:: $comment
 
    The :operator:`$comment` makes it possible to attach a comment to a
-   query. Because these comments propagate to the
-   :dbcommand:`profile` log, adding :operator:`$comment` modifiers can
-   make your profile data much easier to interpret and trace. Consider
-   the following example:
+   query. Because these comments propagate to the :dbcommand:`profile`
+   log, adding :operator:`$comment` modifiers can make your profile
+   data much easier to interpret and trace. Use one of the following
+   forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$comment" , "[COMMENT]" )
-
-   Here, ``[COMMENT]`` represents the text of the comment.
+      db.collection.find( { <query> } )._addSpecial( "$comment", <comment to add> )
+      db.collection.find( { $query: { <query> }, $comment: <comment to add> } )

source/reference/operator/explain.txt

@@ -6,19 +6,21 @@ $explain
 
 .. operator:: $explain
 
-   Use the :operator:`$explain` operator to return a :term:`document`
-   that describes the process and indexes used to return the
-   query. This may provide useful insight when attempting to optimize
-   a query. Consider the following example:
+   :operator:`$explain` operator provides information on the query
+   plan. It returns a :ref:`document <explain-output>` that describes
+   the process and indexes used to return the query. This may provide
+   useful insight when attempting to optimize a query.
+
+   The :program:`mongo` shell provides the :method:`cursor.explain()`
+   method:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial( "$explain", 1 )
+      db.collection.find().explain()
 
-   The JavaScript function :method:`cursor.explain()` provides equivalent
-   functionality in the :program:`mongo` shell. See the following
-   example, which is equivalent to the above:
+   You can also specify the option in either of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find().explain()
+      db.collection.find()._addSpecial( "$explain", 1 )
+      db.collection.find( { $query: {}, $explain: 1 } )

source/reference/operator/hint.txt

@@ -6,16 +6,23 @@ $hint
 
 .. operator:: $hint
 
-   Use the :operator:`$hint` operator to force the query optimizer to
-   use a specific index to fulfill the query.  Use :operator:`$hint`
-   for testing query performance and indexing strategies. Consider
-   the following form:
+   The :operator:`$hint` operator forces the query optimizer to use a
+   specific index to fulfill the query. You can use :operator:`$hint`
+   for testing query performance and indexing strategies. The
+   :program:`mongo` shell provides the :method:`cursor.hint()` method:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial( "$hint", { _id : 1 } )
+      db.collection.find().hint( { age: 1 } )
 
    This operation returns all documents in the collection named
-   ``collection`` using the index on the ``_id`` field. Use this
+   ``collection`` using the index on the ``age`` field. Use this
    operator to override MongoDB's default index selection process and
    pick indexes manually.
+
+   You can also specify the option in either of the following forms:
+
+   .. code-block:: javascript
+
+      db.collection.find()._addSpecial( "$hint", { age : 1 } )
+      db.collection.find( { $query: {}, $hint: { age : 1 } } )

source/reference/operator/max.txt

@@ -6,24 +6,74 @@ $max
 
 .. operator:: $max
 
-   Specify a :operator:`$max` value to specify an upper boundary for
-   the value of a field. :program:`mongod` enforces this boundary with
-   an index of that field.
+   Specify a :operator:`$max` value to specify the *exclusive* upper
+   bound for a specific index in order to constrain the results of
+   :method:`find() <db.collection.find()>`. The :program:`mongo` shell
+   provides the :method:`cursor.max()` wrapper method:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial("$max" , { value : 100 })
+      db.collection.find( { <query> } ).max( { field1: <max value>, ... fieldN: <max valueN> } )
 
-   This operation above limits the documents returned to those that
-   match the query described by ``[QUERY]`` where the field
-   ``value`` is less than ``20``. :program:`mongod` infers the
-   index based on on the ``query`` unless specified by the
-   :method:`cursor.hint()` function.
+   You can also specify the option with either of the two forms:
 
-   Use operation alone or in conjunction with :operator:`$min`
-   to limit results to a specific range.
+   .. code-block:: javascript
+
+      db.collection.find( { <query> } )._addSpecial( "$max", { field1: <max value1>, ... fieldN: <max valueN> } )
+      db.collection.find( { $query: { <query> }, $max: { field1: <max value1>, ... fieldN: <max valueN> } } )
+
+   The :operator:`$max` specifies the upper bound for *all* keys of a
+   specific index *in order*.
+
+   Consider the following operations on a collection named
+   ``collection`` that has an index ``{ age: 1 }``:
+
+   .. code-block:: javascript
+
+      db.collection.find( { <query> } ).max( { age: 100 } )
+
+   This operation above limits the query to those documents where the
+   field ``age`` is less than ``100`` using the index ``{ age: 1 }``.
+   
+   You can explicitly specify the corresponding index with
+   :method:`cursor.hint()`. Otherwise, MongoDB selects the index using
+   the fields in the ``indexbounds``; however, if multiple indexes
+   exist on same fields with different sort orders, the selection of
+   the index may be ambiguous.
+
+   Consider a collection named ``collection`` that has the following
+   two indexes:
+
+   .. code-block:: javascript
+
+      { age: 1, type: -1 }
+      { age: 1, type: 1 }
+
+   Without explicitly using :method:`cursor.hint()`, it is unclear
+   which index the following operation will select:
+
+   .. code-block:: javascript
+
+      db.collection.find().max( { age: 50, type: 'B' } )
+
+   Use operation alone or in conjunction with :operator:`$min` to limit
+   results to a specific range for the *same* index, as in the
+   following example:
+
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20 } ).max( { age: 25 } )
 
    .. note::
 
-      In most cases, you should avoid this operator in favor of
-      :operator:`$lt`.
+      Because :method:`cursor.max()` requires an index on a field, and
+      forces the query to use this index, you may prefer the
+      :operator:`$lt` operator for the query if possible. Consider the
+      following example:
+
+      .. code-block:: javascript
+
+         db.collection.find( { _id: 7 } ).max( { age: 25 } )
+
+      The query will use the index on the ``age`` field, even if the
+      index on ``_id`` may be better.

source/reference/operator/maxScan.txt

@@ -7,11 +7,12 @@ $maxScan
 .. operator:: $maxScan
 
    Constrains the query to only scan the specified number of documents
-   when fulfilling the query. Use the following form:
+   when fulfilling the query. Use one of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$maxScan" , 50 )
+      db.collection.find( { <query> } )._addSpecial( "$maxScan" , <number> )
+      db.collection.find( { $query: { <query> }, $maxScan: <number> } )
 
    Use this modifier to prevent potentially long running queries from
    disrupting performance by scanning through too much data.

source/reference/operator/min.txt

@@ -6,24 +6,74 @@ $min
 
 .. operator:: $min
 
-   Specify a :operator:`$min` value to specify a lower boundary for
-   the value of a field. :program:`mongod` enforces this boundary with
-   an index of the field.
+   Specify a :operator:`$min` value to specify the *inclusive* lower
+   bound for a specific index in order to constrain the results of
+   :method:`find() <db.collection.find()>`. The :program:`mongo` shell
+   provides the :method:`cursor.min()` wrapper method:
 
    .. code-block:: javascript
 
-      db.collection.find( { [QUERY] } )._addSpecial("$min" , { value : 20})
+      db.collection.find( { <query> } ).min( { field1: <min value>, ... fieldN: <min valueN>} )
 
-   This operation above limits the documents returned to those that
-   match the query described by ``[QUERY]`` where the field
-   ``value`` is at least ``20``. :program:`mongod` infers the
-   index based on the ``query`` unless specified by the
-   :method:`cursor.hint()` function.
+   You can also specify the option with either of the two forms:
 
-   Use operation alone or in conjunction with :operator:`$max`
-   to limit results to a specific range.
+   .. code-block:: javascript
+
+      db.collection.find( { <query> } )._addSpecial( "$min", { field1: <min value1>, ... fieldN: <min valueN> } )
+      db.collection.find( { $query: { <query> }, $min: { field1: <min value1>, ... fieldN: <min valueN> } } )
+
+   The :operator:`$min` specifies the lower bound for *all* keys of a
+   specific index *in order*. 
+   
+   Consider the following operations on a collection named
+   ``collection`` that has an index ``{ age: 1 }``:
+
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20 } )
+
+   These operations limit the query to those documents where the field
+   ``age`` is at least ``20`` using the index ``{ age: 1 }``.
+
+   You can explicitly specify the corresponding index with
+   :method:`cursor.hint()`. Otherwise, MongoDB selects the index using
+   the fields in the ``indexbounds``; however, if multiple indexes
+   exist on same fields with different sort orders, the selection of
+   the index may be ambiguous.
+
+   Consider a collection named ``collection`` that has the following
+   two indexes:
+
+   .. code-block:: javascript
+
+      { age: 1, type: -1 }
+      { age: 1, type: 1 }
+
+   Without explicitly using :method:`cursor.hint()`, it is unclear
+   which index the following operation will select:
+
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20, type: 'C' } )
+
+   You can use :operator:`$min` in conjunction with :operator:`$max` to
+   limit results to a specific range for the *same* index, as in the
+   following example:
+   
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20 } ).max( { age: 25 } )
 
    .. note::
 
-      In most cases, you should avoid this operator in favor of
-      :operator:`$gte`.
+      Because :method:`cursor.min()` requires an index on a field, and
+      forces the query to use this index, you may prefer the
+      :operator:`$gte` operator for the query if possible. Consider the
+      following example:
+
+      .. code-block:: javascript
+
+         db.collection.find( { _id: 7 } ).min( { age: 25 } )
+
+      The query will use the index on the ``age`` field, even if the
+      index on ``_id`` may be better.