Add sort limit to $sort (aggregation) and cursor.sort() (#801) (#807)

* Adding sort limit in a few places

* Resolving comment

Co-authored-by: Ashley Brown <[email protected]>

Co-authored-by: Ashley Brown <[email protected]>

Author: mdb-ashley

source/includes/sort-limits.rst

@@ -0,0 +1 @@
+You can sort on a maximum of 32 keys.

source/reference/limits.txt

@@ -215,6 +215,20 @@ Indexes
 
    .. include:: /includes/extracts/collation-index-type-restrictions-addendum.rst
 
+.. limit:: Hidden Indexes
+
+   - You cannot :doc:`hide </core/index-hidden>` the ``_id`` index.
+
+   - You cannot use :method:`~cursor.hint()` on a :doc:`hidden index
+     </core/index-hidden>`.
+
+Sorts
+-----
+
+.. limit:: Maximum Number of Sort Keys
+
+   .. include:: /includes/sort-limits.rst
+
 Data
 ----
 

source/reference/method/cursor.sort.txt

@@ -57,8 +57,13 @@ Definition
    existing fields <sort-asc-desc>` or :ref:`sort on computed metadata
    <sort-metadata>`.
 
-Behaviors
----------
+Behavior
+--------
+
+Limits
+~~~~~~
+
+.. include:: /includes/sort-limits.rst
 
 Result Ordering
 ~~~~~~~~~~~~~~~

source/reference/operator/aggregation/sort.txt

@@ -52,6 +52,88 @@ Definition
    ``<field1>``. Then documents with the same ``<field1>`` values are
    further sorted by ``<field2>``.
 
+Behavior
+--------
+
+Limits
+~~~~~~
+
+.. include:: /includes/sort-limits.rst
+
+.. _sort-aggregation-consistent-sorting:
+
+Sort Consistency
+~~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-sort-consistency.rst
+
+Consider the following ``restaurant`` collection:
+
+.. code-block:: js
+
+   db.restaurants.insertMany( [
+      { "_id" : 1, "name" : "Central Park Cafe", "borough" : "Manhattan"},
+      { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "borough" : "Queens"},
+      { "_id" : 3, "name" : "Empire State Pub", "borough" : "Brooklyn"},
+      { "_id" : 4, "name" : "Stan's Pizzaria", "borough" : "Manhattan"},
+      { "_id" : 5, "name" : "Jane's Deli", "borough" : "Brooklyn"},
+   ] );
+
+The following command uses the :pipeline:`$sort` stage to sort on
+the ``borough`` field:
+
+.. code-block:: js
+
+   db.restaurants.aggregate(
+      [
+        { $sort : { borough : 1 } }
+      ]
+   )
+
+In this example, sort order may be inconsistent, since the ``borough``
+field contains duplicate values for both ``Manhattan`` and ``Brooklyn``.
+Documents are returned in alphabetical order by ``borough``, but the
+order of those documents with duplicate values for ``borough`` might not
+the be the same across multiple executions of the same sort. For
+example, here are the results from two different executions of the
+above command:
+
+.. code-block:: js
+   :copyable: false
+
+   { "_id" : 3, "name" : "Empire State Pub", "borough" : "Brooklyn" }
+   { "_id" : 5, "name" : "Jane's Deli", "borough" : "Brooklyn" }
+   { "_id" : 1, "name" : "Central Park Cafe", "borough" : "Manhattan" }
+   { "_id" : 4, "name" : "Stan's Pizzaria", "borough" : "Manhattan" }
+   { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "borough" : "Queens" }
+
+   { "_id" : 5, "name" : "Jane's Deli", "borough" : "Brooklyn" }
+   { "_id" : 3, "name" : "Empire State Pub", "borough" : "Brooklyn" }
+   { "_id" : 4, "name" : "Stan's Pizzaria", "borough" : "Manhattan" }
+   { "_id" : 1, "name" : "Central Park Cafe", "borough" : "Manhattan" }
+   { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "borough" : "Queens" }
+
+While the values for ``borough`` are still sorted in alphabetical order,
+the order of the documents containing duplicate values for ``borough``
+(i.e. ``Manhattan`` and ``Brooklyn``) is not the same.
+
+To achieve a *consistent sort*, add a field which contains exclusively
+unique values to the sort. The following command uses the
+:pipeline:`$sort` stage to sort on both the ``borough`` field and the
+``_id`` field:
+
+.. code-block:: js
+
+   db.restaurants.aggregate(
+      [
+        { $sort : { borough : 1, _id: 1 } }
+      ]
+   )
+
+Since the ``_id`` field is always guaranteed to contain exclusively
+unique values, the returned sort order will always be the same across
+multiple executions of the same sort.
+
 Examples
 --------