DOCS-1601 agg sort limit on memory usage

source/includes/fact-agg-sort-limit.rst

@@ -1,6 +1,20 @@
 .. versionchanged:: 2.4
-   When a :pipeline:`$sort` immediately precedes a
-   :pipeline:`$limit` in the pipeline, the :pipeline:`$sort`
-   operation only maintains the top n results as it progresses, where n
-   is the specified limit. Before 2.4, :pipeline:`$sort` would sort
-   all the results in memory, and then limit the results to n results.
+
+   - When a :pipeline:`$sort` immediately precedes a :pipeline:`$limit`
+     in the pipeline, the :pipeline:`$sort` operation only maintains
+     the top n results as it progresses, where n is the specified
+     limit, and MongoDB only needs to store the number of items
+     specified by :pipeline:`$limit` in memory. Before MongoDB 2.4,
+     :pipeline:`$sort` would sort all the results in memory, and then
+     limit the results to n results.
+
+   - Unless the :pipeline:`$sort` operator can use an index or
+     immediately precedes a :pipeline:`$limit`, the :pipeline:`$sort`
+     operation must fit within memory. Before MongoDB 2.4, unless the
+     :pipeline:`$sort` operator can use an index, the :pipeline:`$sort`
+     operation must fit within memory.
+
+.. agg-sort-in-memory-limit
+
+:pipeline:`$sort` will produce an error if the operation consumes 10
+percent or more of RAM.

source/reference/aggregation/sort.txt

@@ -36,39 +36,22 @@ $sort (aggregation)
 
    .. include:: /includes/fact-sort-order.rst
 
-   .. note::
-
+   .. important::
       The :pipeline:`$sort` cannot begin sorting documents until
       previous operators in the pipeline have returned all output.
 
       .. todo:: mention the importance of order preserving objects
 
+      .. todo:: the following skip seems to be w/o context
+
       - :pipeline:`$skip`
 
    :pipeline:`$sort` operator can take advantage of an index when
    placed at the **beginning** of the pipeline or placed **before**
-   the following aggregation operators:
-
-   - :pipeline:`$project`
-   - :pipeline:`$unwind`
-   - :pipeline:`$group`.
+   the following aggregation operators: :pipeline:`$project`,
+   :pipeline:`$unwind`, and :pipeline:`$group`.
 
    .. include:: /includes/fact-agg-sort-limit.rst
 
-   .. warning::
-
-      .. versionchanged:: 2.4
-         Sorts immediately proceeded by a limit no longer need to fit into
-         memory. Previously, all sorts had to fit into memory or use
-         an index.
-
-      Unless the :pipeline:`$sort` operator can use an index, or
-      immediately precedes a :pipeline:`$limit`, the :pipeline:`$sort`
-      operation must fit within memory.
-
-      For :pipeline:`$sort` operations that immediately precede a
-      :pipeline:`$limit` stage, MongoDB only needs to store the number
-      of items specified by :pipeline:`$limit` in memory.
-
-      .. todo:: if a sort precedes the first $group in a sharded system,
-         all documents must go to the mongos for sorting.
+   .. todo:: if a sort precedes the first $group in a sharded system,
+      all documents must go to the mongos for sorting.

source/reference/limits.txt

@@ -167,6 +167,13 @@ Operations
    MongoDB will only return sorted results on fields without an index
    *if* the sort operation uses less than 32 megabytes of memory.
 
+.. _limit-agg-sort:
+
+.. limit:: Aggregation Sort Operation
+
+   .. include:: /includes/fact-agg-sort-limit.rst
+      :start-after: agg-sort-in-memory-limit
+
 .. limit:: 2d Geospatial queries cannot use the $or operator
 
    .. see:: :operator:`$or` and :doc:`/core/geospatial-indexes`.