DOCS-11338 - Add multikey index sort limitation to tutorial and manual pages

Author: jeff-allen-mongo

source/core/index-multikey.txt

@@ -41,7 +41,7 @@ an array; you do not need to explicitly specify the multikey type.
 
 .. versionchanged:: 3.4
 
-   *For the WiredTiger and In-Memory storage engines only*, 
+   *For the WiredTiger and In-Memory storage engines only*,
 
    Starting in MongoDB 3.4, for multikey indexes created using MongoDB
    3.4 or later, MongoDB keeps track of which indexed field or fields
@@ -104,7 +104,7 @@ array. That is:
   A compound multikey index ``{ a: 1, b: 1 }`` is permissible since for
   each document, only one field indexed by the compound multikey index
   is an array; i.e. no document contains array values for both ``a``
-  and ``b`` fields. 
+  and ``b`` fields.
 
   However, after creating the compound multikey index, if you attempt
   to insert a document where both ``a`` and ``b`` fields are arrays,
@@ -131,6 +131,11 @@ For an example, see :ref:`multikey-embedded-documents`.
 
    - :ref:`index-unique-index`
 
+Sorting
+~~~~~~~
+
+.. include:: /includes/fact-multikey-index-sort-limitation.rst
+
 Shard Keys
 ~~~~~~~~~~
 

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

@@ -0,0 +1,9 @@
+As a result of changes to sorting behavior on array fields in MongoDB
+3.6, when sorting on an array indexed with a
+:doc:`multikey index </core/index-multikey/>` the query plan includes
+a blocking SORT stage. The new sorting behavior may negatively impact
+performance.
+
+In a blocking SORT, all input must be consumed by the sort step before
+it can produce output. In a non-blocking, or *indexed* sort, the
+sort step scans the index to produce results in the requested order.

source/release-notes/3.6-compatibility.txt

@@ -130,13 +130,9 @@ account when choosing the array element which will act as the
 As a result of this change, applications that currently sort by an
 array field may experience a different sort order.
 
-.. note ::
+.. note::
 
-   As of version 3.6, the query engine cannot use a
-   :doc:`multikey index </core/index-multikey/>` to provide a
-   non-blocking sort by an array field. If you try to sort in this
-   manner, the query plan will include a blocking SORT stage, which
-   may negatively impact performance.
+   .. include:: /includes/fact-multikey-index-sort-limitation.rst
 
 .. _3.6-find-method-sort:
 

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

@@ -20,6 +20,10 @@ memory. Sort operations that use an index often have better performance
 than those that do not use an index. In addition, sort operations that
 do *not* use an index will abort when they use 32 megabytes of memory.
 
+.. note::
+
+   .. include:: /includes/fact-multikey-index-sort-limitation.rst
+
 .. _sort-results-single-field:
 
 Sort with a Single Field Index