DOCS-1492 cursor.sort cursor.min

source/reference/method/cursor.min-param.yaml

@@ -0,0 +1,12 @@
+object:
+  name: cursor.min()
+  type: method
+field:
+  optional: false
+  type: param
+name: indexBounds
+type: document
+position: 1
+description: |
+  The inclusive lower bound for the index keys.
+...

source/reference/method/cursor.min.txt

@@ -4,128 +4,132 @@ cursor.min()
 
 .. default-domain:: mongodb
 
+Definition
+----------
+
 .. method:: cursor.min()
 
-   The :method:`min() <cursor.min()>` method specifies the *inclusive*
+   Specifies the *inclusive*
    lower bound for a specific index in order to constrain the results
    of :method:`find() <db.collection.find()>`. :method:`min()
    <cursor.min()>` provides a way to specify lower bounds on compound
    key indexes.
 
-   :method:`min() <cursor.min()>` takes the following parameter:
+   The :method:`min() <cursor.min()>` has the following parameter:
 
-   :param document indexBounds:
+   .. include:: /reference/method/cursor.min-param.rst
 
-          Specifies the inclusive lower bound for the index keys. The
-          ``indexBounds`` parameter has the following prototype form:
+   The ``indexBounds`` parameter has the following prototype form:
 
-          .. code-block:: javascript
+   .. code-block:: javascript
 
-             { field1: <min value>, field2: <min value2>, fieldN:<min valueN> }
+      { field1: <min value>, field2: <min value2>, fieldN:<min valueN> }
 
-          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,
-          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.
+   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,
+   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.
 
    .. seealso:: :method:`max() <cursor.max()>`.
 
-   Consider the following example of :method:`min() <cursor.min()>`,
-   which assumes a collection named ``products`` that holds the
-   following documents:
+Example
+-------
 
-   .. code-block:: javascript
+This example assumes a collection named ``products`` that holds the
+following documents:
 
-      { "_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 }
+.. code-block:: javascript
 
-   The collection has the following 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 }
 
-   .. code-block:: javascript
+The collection has the following indexes:
 
-      { "_id" : 1 }
-      { "item" : 1, "type" : 1 }
-      { "item" : 1, "type" : -1 }
-      { "price" : 1 }
+.. code-block:: javascript
 
-   - Using the ordering of ``{ item: 1, type: 1 }`` index,
-     :method:`min() <cursor.min()>` limits the query to the documents
-     that are at or above the index key bound of ``item`` equal to
-     ``apple`` and ``type`` equal to ``jonagold``, as in the following:
+   { "_id" : 1 }
+   { "item" : 1, "type" : 1 }
+   { "item" : 1, "type" : -1 }
+   { "price" : 1 }
 
-     .. code-block:: javascript
+- Using the ordering of ``{ item: 1, type: 1 }`` index,
+  :method:`min() <cursor.min()>` limits the query to the documents
+  that are at or above the index key bound of ``item`` equal to
+  ``apple`` and ``type`` equal to ``jonagold``, as in the following:
 
-        db.products.find().min( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )
+  .. code-block:: javascript
 
-     The query returns the following documents:
+     db.products.find().min( { item: 'apple', type: 'jonagold' } ).hint( { item: 1, type: 1 } )
 
-     .. code-block:: javascript
+  The query returns the following documents:
 
-        { "_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 }
-
-     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.
-
-   - Using the ordering of the index ``{ price: 1 }``, :method:`min()
-     <cursor.min()>` limits the query to the documents that are at or
-     above the index key bound of ``price`` equal to ``1.39`` and
-     :method:`max() <cursor.max()>` limits the query to the documents
-     that are below the index key bound of ``price`` equal to ``1.99``:
+  .. code-block:: javascript
 
-     .. code-block:: javascript
+     { "_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 }
 
-         db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )
+  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.
 
-     The query returns the following documents:
+- Using the ordering of the index ``{ price: 1 }``, :method:`min()
+  <cursor.min()>` limits the query to the documents that are at or
+  above the index key bound of ``price`` equal to ``1.39`` and
+  :method:`max() <cursor.max()>` limits the query to the documents
+  that are below the index key bound of ``price`` equal to ``1.99``:
 
-     .. code-block:: javascript
+  .. code-block:: javascript
+
+      db.products.find().min( { price: 1.39 } ).max( { price: 1.99 } ).hint( { price: 1 } )
 
-        { "_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 }
+  The query returns the following documents:
 
-   .. note::
+  .. code-block:: javascript
 
-      - Because :method:`min() <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:
+     { "_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 }
 
-        .. code-block:: javascript
+.. note::
+
+   - Because :method:`min() <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.products.find( { _id: 7 } ).min( { price: 1.39 } )
+        db.products.find( { _id: 7 } ).min( { price: 1.39 } )
 
-        The query will use the index on the ``price`` field, even if
-        the index on ``_id`` may be better.
+     The query will use the index on the ``price`` field, even if
+     the index on ``_id`` may be better.
 
-      - :method:`min() <cursor.min()>` exists primarily to support the
-        :program:`mongos` (sharding) process.
+   - :method:`min() <cursor.min()>` exists primarily to support the
+     :program:`mongos` (sharding) process.
 
-      - If you use :method:`min() <cursor.min()>` with :method:`max()
-        <cursor.max()>` to specify a range, the index bounds specified
-        in :method:`min() <cursor.min()>` and :method:`max()
-        <cursor.max()>` must both refer to the keys of the same index.
+   - If you use :method:`min() <cursor.min()>` with :method:`max()
+     <cursor.max()>` to specify a range, the index bounds specified
+     in :method:`min() <cursor.min()>` and :method:`max()
+     <cursor.max()>` must both refer to the keys of the same index.
 
-      - :method:`min() <cursor.min()>` is a shell wrapper around the
-        special operator :operator:`$min`.
+   - :method:`min() <cursor.min()>` is a shell wrapper around the
+     special operator :operator:`$min`.

source/reference/method/cursor.sort-param.yaml

@@ -0,0 +1,13 @@
+object:
+  name: cursor.sort()
+  type: method
+field:
+  optional: false
+  type: param
+name: sort
+type: document
+position: 1
+description: |
+  A document whose fields specify the attributes on which to sort the
+  result set.
+...

source/reference/method/cursor.sort.txt

@@ -4,60 +4,72 @@ cursor.sort()
 
 .. default-domain:: mongodb
 
-.. method:: cursor.sort(sort)
+Definition
+----------
 
-   :param sort: A document whose fields specify the attributes on
-                which to sort the result set.
+.. method:: cursor.sort(sort)
 
-   Append the :method:`sort() <cursor.sort()>` method to a cursor to
-   control the order that the query returns matching documents.  For
+   Controls the order that the query returns matching documents. For
    each field in the sort document, if the field's corresponding value
    is positive, then :method:`sort() <cursor.sort()>` returns query
-   results in ascending order for that attribute: if the field's
+   results in ascending order for that attribute. If the field's
    corresponding value is negative, then :method:`sort()
    <cursor.sort()>` returns query results in descending order.
 
+   The :method:`sort() <cursor.sort()>` method has the following parameter:
+
+   .. include:: /reference/method/cursor.sort-param.rst
+
    .. note::
 
       You must apply :method:`cursor.limit()` to the cursor before
       retrieving any documents from the database.
 
-   Consider the following example:
+Example
+-------
+
+The following query returns all documents in ``collection`` sorted by
+the ``age`` field in descending order.
+
+.. code-block:: javascript
+
+   db.collection.find().sort( { age: -1 } );
 
-   .. code-block:: javascript
+Specify a value of negative
+one (e.g. ``-1``), as above, to sort in descending order or a
+positive value (e.g. ``1``) to sort in ascending order.
 
-      db.collection.find().sort( { age: -1 } );
+Limit Results
+-------------
 
-   Here, the query returns all documents in ``collection`` sorted by
-   the ``age`` field in descending order. Specify a value of negative
-   one (e.g. ``-1``), as above, to sort in descending order or a
-   positive value (e.g. ``1``) to sort in ascending order.
+Unless you have an index for the specified key pattern, use
+:method:`cursor.sort()` in conjunction with :method:`cursor.limit()` to avoid
+requiring MongoDB to perform a large, in-memory
+sort. :method:`cursor.limit()` increases the speed and reduces the amount
+of memory required to return this query by way of an optimized
+algorithm.
 
-   Unless you have an index for the specified key pattern, use
-   :method:`cursor.sort()` in conjunction with :method:`cursor.limit()` to avoid
-   requiring MongoDB to perform a large, in-memory
-   sort. :method:`cursor.limit()` increases the speed and reduces the amount
-   of memory required to return this query by way of an optimized
-   algorithm.
+.. warning::
 
-   .. warning::
+   The sort function requires that the entire sort be able to
+   complete within 32 megabytes. When the sort option consumes more
+   than 32 megabytes, MongoDB will return an error. Use
+   :method:`cursor.limit()`, or create an index on the field that you're
+   sorting to avoid this error.
 
-      The sort function requires that the entire sort be able to
-      complete within 32 megabytes. When the sort option consumes more
-      than 32 megabytes, MongoDB will return an error. Use
-      :method:`cursor.limit()`, or create an index on the field that you're
-      sorting to avoid this error.
+Return Natural Order
+--------------------
 
-   The :operator:`$natural` parameter returns items according to their
-   order on disk. Consider the following query: 
+The :operator:`$natural` parameter returns items according to their
+order on disk. Consider the following query: 
 
-   .. code-block:: javascript
+.. code-block:: javascript
 
-      db.collection.find().sort( { $natural: -1 } )
+   db.collection.find().sort( { $natural: -1 } )
 
-   This will return documents in the reverse of the order on
-   disk. Typically, the order of documents on disks reflects insertion
-   order, *except* when documents move internal because of document
-   growth due to update operations.
+This will return documents in the reverse of the order on
+disk. Typically, the order of documents on disks reflects insertion
+order, *except* when documents move internal because of document
+growth due to update operations.
 
-   .. include:: /includes/fact-sort-order.rst
+.. include:: /includes/fact-sort-order.rst