DOCSP-49577-blocking-sort (#11837)

* replace blocking with in-memory

* mr feedback

* mr feedback

* asya feedback

* asya feedback

* asya feedback

Author: shuangela

source/includes/fact-multikey-index-sort-limitation.rst

@@ -1,6 +1,6 @@
-When you sort based on an array field that is indexed with a
-:ref:`multikey index <index-type-multikey>`, the query plan includes a
-:term:`blocking sort` stage unless both of the following are true:
+When you sort based on an array field that is indexed with a :ref:`multikey index
+<index-type-multikey>`, the query plan includes an :term:`in-memory sort` stage unless
+both of the following are true:
 
 - The index :ref:`boundaries <multikey-index-bounds-intersecting>` for
   all sort fields are ``[MinKey, MaxKey]``.

source/reference/command/find.txt

@@ -258,12 +258,12 @@ The command accepts the following fields:
 
        ``allowDiskUse`` has no effect if MongoDB can satisfy the
        specified :ref:`sort <find-cmd-sort>` using an index, *or* if the
-       blocking sort requires less than 100 megabytes of memory.
+       in-memory sort requires less than 100 megabytes of memory.
 
        For more complete documentation on ``allowDiskUse``, 
        see :method:`cursor.allowDiskUse()`.
 
-       For more information on memory restrictions for large blocking
+       For more information on memory restrictions for large in-memory
        sorts, see :ref:`sort-index-use`.
 
    * - :ref:`let <find-let-syntax>`

source/reference/explain-results.txt

@@ -1229,18 +1229,8 @@ Sort Stage
 ----------
 
 If MongoDB cannot use an index or indexes to obtain the sort order, the
-results include a ``SORT`` stage indicating a blocking sort operation.
-Blocking sorts do not block concurrent operations on the
-collection or database. The name refers to the requirement that the
-``SORT`` stage reads all input documents before returning any output
-documents, blocking the flow of data for that specific query.
-
-If MongoDB requires using more than 100 megabytes of system memory for
-the blocking sort operation, MongoDB returns an error *unless* the query
-specifies :method:`cursor.allowDiskUse()`. :method:`cursor.allowDiskUse()` 
-allows MongoDB to use temporary files on disk to store data exceeding the 100 
-megabyte system memory limit while processing a blocking sort operation. If the 
-explain plan does not contain an explicit ``SORT`` stage, then MongoDB can use 
+results include a ``SORT`` stage indicating an in-memory sort operation.
+If the explain plan does not contain an explicit ``SORT`` stage, then MongoDB used
 an index to obtain the sort order.
 
 .. _explain-output-query-shape-hash:

source/reference/glossary.txt

@@ -126,11 +126,8 @@ Glossary
 
    blocking sort
       A sort that must be performed in memory before the output is returned. 
-      Blocking sorts may impact performance for large data sets. Use an 
-      :term:`indexed sort` to avoid a blocking sort.
-
-      See :ref:`sort-index-use` for more information on blocking sort
-      operations.
+      In-memory sorts may impact performance for large data sets. Use an 
+      :term:`indexed sort` to avoid an in-memory sort.
 
    bounded collection scan
       A plan used by the :ref:`query optimizer <read-operations-query-optimization>` that
@@ -570,6 +567,14 @@ Glossary
       An operation produces the same result with the
       same input when run multiple times.
 
+   in-memory sort
+      A sort that must be performed in memory before the output is
+      returned. In-memory sorts may impact performance for large data sets. Use an 
+      :term:`indexed sort` to avoid an in-memory sort.
+
+      See :ref:`sort-index-use` for more information on indexed sort
+      operations.
+
    index
       A data structure that optimizes queries. See :doc:`/indexes`.
 
@@ -628,7 +633,7 @@ Glossary
 
    indexed sort
       A sort where an index provides the sorted result. Sort operations that 
-      use an index often have better performance than a :term:`blocking sort`. 
+      use an index often have better performance than an :term:`in-memory sort`. 
       See :ref:`Use Indexed to Sort Query Results <sorting-with-indexes>` for 
       more information.
 

source/reference/limits.txt

@@ -792,17 +792,7 @@ Operations
 .. limit:: Sort Operations
 
    If MongoDB cannot use an index or indexes to obtain the sort order,
-   MongoDB must perform a blocking sort operation on the data. The name
-   refers to the requirement that the ``SORT`` stage reads all input
-   documents before returning any output documents, blocking the flow of
-   data for that specific query.
-   
-   If MongoDB requires using more than 100 megabytes of system memory
-   for the blocking sort operation, MongoDB returns an error *unless*
-   the query specifies :method:`cursor.allowDiskUse()`. 
-   :method:`~cursor.allowDiskUse()` allows MongoDB to use temporary files on 
-   disk to store data exceeding the 100 megabyte system memory limit while 
-   processing a blocking sort operation.
+   MongoDB must perform an in-memory sort operation on the data. 
 
    For more information on sorts and index use, see
    :ref:`sort-index-use`.

source/reference/method.txt

@@ -334,7 +334,8 @@ Cursor
 
    * - :method:`cursor.allowDiskUse()`
 
-     - Allows MongoDB to use temporary files on disk to store data exceeding the 100 megabyte system memory limit while processing a blocking sort operation.
+     - Allows MongoDB to use temporary files on disk to store data exceeding the 100
+       megabyte system memory limit while processing an in-memory sort operation.
 
    * - :method:`cursor.allowPartialResults()`
 

source/reference/method/cursor.allowDiskUse.txt

@@ -33,7 +33,7 @@ Definition
 
       db.collection.find(<match>).sort(<sort>).allowDiskUse()
 
-See :ref:`sort-index-use` for more information on blocking sort
+See :ref:`sort-index-use` for more information on in-memory sort
 operations.
 
 Compatibility
@@ -80,16 +80,16 @@ Supports Large Non-Indexed Sorts Only
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :method:`cursor.allowDiskUse()` has no effect on sort operations
-answered using an index *or* non-indexed ("blocking") sort operations
+answered using an index *or* non-indexed ("in-memory") sort operations
 which require less than 100 megabytes of memory. For more complete
-documentation on blocking sorts and sort index use, see
+documentation on in-memory sorts and sort index use, see
 :ref:`sort-index-use`.
 
-To check if MongoDB must perform an blocking sort, append
+To check if MongoDB must perform an in-memory sort, append
 :method:`cursor.explain()` to the query and check the 
 :ref:`explain results <explain-results>`. If the query plan 
 contains a ``SORT`` stage, then MongoDB must perform an 
-blocking sort operation subject to the 100 megabyte memory limit.
+in-memory sort operation subject to the 100 megabyte memory limit.
 
 Example
 -------
@@ -124,7 +124,7 @@ field ``reading.timestamp``. The operation also includes
      allowDiskUse()
 
 Since ``reading.timestamp`` is not included in an index, MongoDB
-must perform a blocking sort operation to return results in the 
+must perform an in-memory sort operation to return results in the 
 requested sort order. By specifying :method:`~cursor.allowDiskUse()`,
 MongoDB can process the sort operation *even if* it requires more than
 100 megabytes of system memory. If :method:`~cursor.allowDiskUse()` 

source/reference/method/cursor.sort.txt

@@ -246,29 +246,17 @@ a sort operation *if* the sort uses the same indexes as the query
 predicate.
 
 If MongoDB cannot use an index or indexes to obtain the sort
-order, MongoDB must perform a blocking sort operation on the data.
-A blocking sort indicates that MongoDB must consume and process all 
-input documents to the sort before returning results. Blocking sorts do
-not block concurrent operations on the collection or database.
+order, MongoDB must perform an in-memory sort operation on the data.
 
 Sort operations that use an index often have better performance than
-blocking sorts. For more information on creating indexes to support
+in-memory sorts. For more information on creating indexes to support
 sort operations, see :ref:`sorting-with-indexes`.
 
-If MongoDB requires using more than 100 megabytes of system memory for
-the blocking sort operation, MongoDB returns an error *unless* the query
-specifies :method:`cursor.allowDiskUse()`.
-:method:`~cursor.allowDiskUse()` allows MongoDB to use temporary files
-on disk to store data exceeding the 100 megabyte system memory limit
-while processing a blocking sort operation.
+To check if MongoDB must perform an in-memory sort, append :method:`cursor.explain()` to
+the query and check the :ref:`explain results <explain-results>`. If the query plan
+contains a ``SORT`` stage, then MongoDB must perform an in-memory sort operation.
 
-To check if MongoDB must perform a blocking sort, append
-:method:`cursor.explain()` to the query and check the 
-:ref:`explain results <explain-results>`. If the query plan 
-contains a ``SORT`` stage, then MongoDB must perform a
-blocking sort operation subject to the 100 megabyte memory limit.
-
-To prevent blocking sorts from consuming too much memory:
+To prevent in-memory sorts from consuming too much memory:
 
 - Create an index to support the sort operation. See
   :doc:`/tutorial/sort-results-with-indexes` for more information and 

source/reference/method/js-cursor.txt

@@ -35,7 +35,7 @@ These methods modify the way that the underlying query is executed.
    * - :method:`cursor.allowDiskUse()`
      - Allows MongoDB to use temporary files on disk to store data 
        exceeding the 100 megabyte system memory limit while processing
-       a blocking sort operation.
+       an in-memory sort operation.
    * - :method:`cursor.allowPartialResults()`
      - Allows :method:`db.collection.find()` operations against a
        sharded collection to return partial results, rather than an

source/tutorial/equality-sort-range-guideline.txt

@@ -71,7 +71,7 @@ Sort
 "Sort" determines the order for results. Sort follows equality matches
 because the equality matches reduce the number of documents that need
 to be sorted. Sorting after the equality matches also allows MongoDB to
-do a non-blocking sort.
+do an index sort.
 
 An index can support sort operations when the query fields are a subset
 of the index keys. Sort operations on a subset of the index keys are
@@ -115,10 +115,9 @@ Range filters resemble the following:
    db.cars.find( { age: { $lt: 10 } } )
    db.cars.find( { priorAccidents: { $ne: null } } )
 
-MongoDB cannot perform an index sort on the results of a range filter.
-Place the range filter after the sort predicate so MongoDB can use a
-non-blocking index sort. For more information on blocking sorts, see
-:method:`cursor.allowDiskUse()`.
+MongoDB cannot perform an index sort on the results of a range filter. Place the range
+filter after the sort predicate so MongoDB can use an index sort. For more information on
+in-memory sorts, see :method:`cursor.allowDiskUse()`.
 
 Additional Considerations
 -------------------------

source/tutorial/sort-results-with-indexes.txt

@@ -21,19 +21,16 @@ a sort from an index that includes the sort fields. MongoDB *may*
 use multiple indexes to support a sort operation *if* the sort uses the
 same indexes as the query predicate. 
 
-If MongoDB cannot use an index or indexes to obtain the sort
-order, MongoDB must perform a blocking sort operation on the data.
-A blocking sort indicates that MongoDB must consume and process all 
-input documents to the sort before returning results. Blocking sorts do
-not block concurrent operations on the collection or database.
+If MongoDB cannot use an index or indexes to obtain the sort order, MongoDB must perform
+an in-memory sort operation on the data.
 
 Starting in MongoDB 6.0, if the server requires more than 100 megabytes 
 of memory for a pipeline execution stage, MongoDB automatically writes 
 temporary files to disk unless that query specifies
 ``{ allowDiskUse: false }``.
 
 Sort operations that use an index often have better performance than
-blocking sorts.
+in-memory sorts.
 
 .. note::