DOCS-671 min-max edits

Author: kay-kim

source/reference/method/cursor.max.txt

@@ -9,8 +9,8 @@ cursor.max()
    The :method:`max() <cursor.max()>` method specifies the *exclusive*
    upper bound for a specific index in order to constrain the results
    of the :method:`find() <db.collection.find()>` method. The
-   :method:`max() <cursor.max()>` method provides a straight-forward
-   way to specify an upper bound on multiple-key index.
+   :method:`max() <cursor.max()>` method provides a way to specify an
+   upper bound on compound key indexes.
 
    The :method:`max() <cursor.max()>` method takes the following parameter:
 
@@ -23,116 +23,107 @@ cursor.max()
 
              { field1: <max value>, field2: <max value2> ... fieldN:<max valueN>} 
 
-          The fields correspond to *all* the keys of a particular
-          index *in order*. :program:`mongod` determines the index
-          using the fields in the ``indexbounds``; however, you can
-          explicitly specify the particular index with the
-          :method:`hint() <cursor.hint()>` method.
-
-   .. note::
-
-      - The :method:`max() <cursor.max()>` method exist primarily to
-        support the :program:`mongos` (sharding) process.
-
-      - Because the :method:`max() <cursor.max()>` method requires a
-        corresponding index, it may be preferable to use the
-        :operator:`$lt` operator in the query instead.
-
-      - If you use :method:`max() <cursor.max()>` method with the
-        :method:`min() <cursor.min()>` method to specify a range, the
-        index bounds specified in :method:`min() <cursor.min()>` method
-        and the :method:`max() <cursor.max()>` method must both refer
-        to the keys of the same index.
-
-      - The :method:`max() <cursor.max()>` method is a shell wrapper
-        around the special operator :operator:`$max`.
+          The fields correspond to *all* the keys of a particular index
+          *in order*. You can explicitly specify the particular index
+          with the :method:`hint() <cursor.hint()>` method. Otherwise,
+          :program:`mongod` 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 the following example of the :method:`max() <cursor.max()>`
    method:
 
-   The examples assume a collection ``contacts`` with the following documents:
+   The examples assume a collection ``products`` with the following documents:
 
    .. code-block:: javascript
-   
-      { "_id" : 1, "fname" : "ant", "lname" : "arctica" }
-      { "_id" : 2, "fname" : "bob", "lname" : "cat" }
-      { "_id" : 3, "fname" : "house", "lname" : "cat" }
-      { "_id" : 4, "fname" : "wild", "lname" : "cat" }
-      { "_id" : 7, "fname" : "big", "lname" : "dog" }
-      { "_id" : 5, "fname" : "ant", "lname" : "eater" }
-      { "_id" : 6, "fname" : "ant", "lname" : "elope" }
 
-   The collection has the following three indexes:
+      { "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
+      { "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
+      { "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
+      { "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
+      { "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
+      { "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
+      { "_id" : 7, "item" : "orange", "type" : "cara cara", "price" : 2.99 }
+      { "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
+      { "_id" : 9, "item" : "orange", "type" : "satsuma", "price" : 1.99 }
+      { "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 }
+      
+   The collection has the following four indexes:
 
    .. code-block:: javascript
 
-      { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.contacts", "name" : "_id_" }
-      { "v" : 1, "key" : { "lname" : 1, "fname" : 1 }, "ns" : "test.contacts", "name" : "lname_1_fname_1" }
-      { "v" : 1, "key" : { "lname" : 1 }, "ns" : "test.contacts", "name" : "lname_1" }
+      { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.products", "name" :"_id_" },
+      { "v" : 1, "key" : { "item" : 1, "type" : 1 }, "ns" :"test.products", "name" : "item_1_type_1" },
+      { "v" : 1, "key" : { "item" : 1, "type" : -1 }, "ns" : "test.products", "name" : "item_1_type_-1" }
+      { "v" : 1, "key" : { "price" : 1 }, "ns" : "test.products", "name" : "price_1" }
 
-   - Specify a lower, inclusive bounds for the index
-     ``lname_1_fname_1`` in the query execution. Using the ordering of
-     ``lname_1_fname_1``, the :method:`max() <cursor.max()>` method
-     limits the query to the documents that are below the bound of
-     ``lname`` equal to ``dog`` and ``fname`` equal to ``big``:
+   - Using the ordering of ``item_1_type_1`` index, the :method:`max()
+     <cursor.max()>` method limits the query to the documents that are
+     below the bound of ``item`` equal to ``apple`` and ``type`` equal
+     to ``jonagold``:
 
      .. code-block:: javascript
 
-        db.contacts.find().max( { lname: 'dog', fname: 'big' } )
+        db.products.find().max( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )
 
      The query returns the following documents:
 
      .. code-block:: javascript
 
-        { "_id" : 1, "fname" : "ant", "lname" : "arctica" }
-        { "_id" : 2, "fname" : "bob", "lname" : "cat" }
-        { "_id" : 3, "fname" : "house", "lname" : "cat" }
-        { "_id" : 4, "fname" : "wild", "lname" : "cat" }
-
-     The equivalent query with the :operator:`$lt` operator is:
+        { "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
+        { "_id" : 2, "item" : "apple", "type" : "fuji", "price" : 1.99 }
+        { "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 }
 
-     .. code-block:: javascript
+     If the query did not explicitly specify the index with the
+     :method:`hint() <cursor.hint()>` method, it is ambiguous as to
+     whether :program:`mongod` would select the ``{ item: 1, type: 1
+     }`` index ordering or the ``{ item: 1, type: -1 }`` index ordering.
 
-        db.contacts.find( { lname: { $lt: 'dog' } } )
+   - Using the ordering of the index ``price_1``, the :method:`max()
+     <cursor.max()>` method limits the query to the documents that are
+     below the index key bound of ``price`` equal to ``1.99`` and the
+     :method:`min() <cursor.min()>` method limits the query to the
+     documents that are at or above the index key bound of ``price``
+     equal to ``1.39``:
 
-     Note that the equivalent query with the :operator:`$lt` operator
-     is **not**:
-     
      .. code-block:: javascript
 
-        db.contacts.find( { lname: { $lt: 'dog' } , fname: { $lt: 'big' } } )
+         db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )
 
-     The query with the :operator:`$lt` operator returns only the
-     documents with both ``lname`` value less than ``dog`` **and**
-     ``fname`` value less than ``big``:
+     The query returns the following documents:
 
      .. code-block:: javascript
 
-        { "_id" : 1, "fname" : "ant", "lname" : "arctica" }
+        { "_id" : 6, "item" : "apple", "type" : "cortland", "price" : 1.29 }
+        { "_id" : 4, "item" : "apple", "type" : "jonathan", "price" : 1.29 }
+        { "_id" : 5, "item" : "apple", "type" : "mcintosh", "price" : 1.29 }
+        { "_id" : 3, "item" : "apple", "type" : "jonagold", "price" : 1.29 }
+        { "_id" : 10, "item" : "orange", "type" : "navel", "price" : 1.39 }
 
-   - Specify a range for the index ``lname_1`` in the query execution.
-     The :method:`min() <cursor.min()>` method limits the query to the
-     documents that are at or above the index key bound of ``lname``
-     equal to ``cat`` and the :method:`max() <cursor.max()>` method
-     limits the query to the documents that are below the index key
-     bound of ``lname`` equal to ``eater``:
+   .. note::
 
-     .. code-block:: javascript
+      - Because the :method:`max() <cursor.max()>` method requires a
+        corresponding index as well as enforces the use of that index,
+        it may be preferable to use the :operator:`$lt` operator in the
+        query if possible. Consider the following example:
 
-        db.contacts.find().min( { lname: 'cat' } ).max( { lname: 'eater' } )
+        .. code-block:: javascript
 
-     The query returns the following documents:
+           db.products.find( { _id: 7 } ).max( { price: 1.39 } )   
 
-     .. code-block:: javascript
+        The query will use the index on the ``price`` field, even if
+        the index on ``_id`` may be better.
 
-        { "_id" : 3, "fname" : "house", "lname" : "cat" }
-        { "_id" : 2, "fname" : "bob", "lname" : "cat" }
-        { "_id" : 4, "fname" : "wild", "lname" : "cat" }
-        { "_id" : 7, "fname" : "big", "lname" : "dog" }
+      - The :method:`max() <cursor.max()>` method exist primarily to
+        support the :program:`mongos` (sharding) process.
 
-     The equivalent query with the :operator:`$gte` and the
-     :operator:`$lt` operators is:
+      - If you use :method:`max() <cursor.max()>` method with the
+        :method:`min() <cursor.min()>` method to specify a range, the
+        index bounds specified in :method:`min() <cursor.min()>` method
+        and the :method:`max() <cursor.max()>` method must both refer
+        to the keys of the same index.
 
-     .. code-block:: javascript
+      - The :method:`max() <cursor.max()>` method is a shell wrapper
+        around the special operator :operator:`$max`.
 
-        db.contacts.find( { lname: { $gte:'cat', $lt: 'eater' } } )