Merge pull request #2433 from davemungo/DOCS-10322-highlight-sparse-index-behaviour-v6.1

DOCS-10322 highlight sparse index behavior v6.1

Author: mdb-ashley

source/core/index-compound.txt

@@ -207,6 +207,12 @@ Index Intersection
 
 .. include:: /includes/fact-index-intersection-vs-compound-indexes.rst
 
+Sparse Compound Indexes
+-----------------------
+
+.. include:: /includes/indexes/sparse-compound-indexes.rst
+
+
 Additional Considerations
 -------------------------
 

source/core/index-sparse.txt

@@ -31,11 +31,11 @@ field.
 Create a Sparse Index
 ---------------------
 
-To create a ``sparse`` index, use the
-:method:`db.collection.createIndex()` method with the ``sparse`` option
-set to ``true``. For example, the following operation in
-:binary:`~bin.mongosh` creates a sparse index on the ``xmpp_id`` field
-of the ``addresses`` collection:
+To create a sparse index, use the :method:`db.collection.createIndex()`
+method with the ``sparse`` option set to ``true``.
+
+For example, the following operation in :binary:`~bin.mongosh` creates a
+sparse index on the ``xmpp_id`` field of the ``addresses`` collection:
 
 .. code-block:: javascript
 
@@ -55,8 +55,8 @@ field.
 Behavior
 --------
 
-``sparse`` Index and Incomplete Results
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sparse Index and Incomplete Results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If a sparse index would result in an incomplete result set for queries
 and sort operations, MongoDB will not use that index unless a
@@ -69,38 +69,27 @@ behavior.
 
 .. include:: /includes/fact-sparse-index-hint-count.rst
 
-Indexes that are ``sparse`` by Default
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Indexes that are Sparse by Default
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :ref:`2dsphere (version 2) <2dsphere-v2>`, :ref:`2d <2d-index>`,
 :ref:`geoHaystack <index-geohaystack-index>`, and :ref:`text
-<index-feature-text>` indexes are always ``sparse``.
-
-``sparse`` Compound Indexes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+<index-feature-text>` indexes are always sparse.
 
-Sparse :doc:`compound indexes </core/index-compound>` that only contain
-ascending/descending index keys will index a document as long as the
-document contains at least one of the keys.
+.. _sparse-compound-indexes:
 
-For sparse compound indexes that contain a geospatial key (i.e.
-``2dsphere``, ``2d``, or ``geoHaystack`` index keys) along 
-with ascending/descending index key(s), only the existence of the 
-geospatial field(s) in a document determine whether the index 
-references the document.
+Sparse Compound Indexes
+~~~~~~~~~~~~~~~~~~~~~~~
 
-For sparse compound indexes that contain :ref:`text 
-<index-feature-text>` index keys along with ascending/descending index 
-keys, only the existence of the ``text`` index field(s) determine 
-whether the index references a document.
+.. include:: /includes/indexes/sparse-compound-indexes.rst
 
 .. _sparse-unique-index:
 
 ``sparse`` and ``unique`` Properties
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An index that is both ``sparse`` and :ref:`unique <index-type-unique>`
-prevents collection from having documents with duplicate values for a
+An index that is both sparse and :ref:`unique <index-type-unique>`
+prevents a collection from having documents with duplicate values for a
 field but allows multiple documents that omit the key.
 
 Examples

source/includes/indexes/sparse-compound-indexes.rst

@@ -0,0 +1,32 @@
+Compound indexes can contain different types of sparse indexes. The
+combination of index types determines how the compound index matches
+documents. 
+
+This table summarizes the behavior of a compound index that contains
+different types of sparse indexes:
+
+.. list-table::
+  :header-rows: 1
+
+  * - Compound Index Components
+    - Compound Index Behavior
+
+  * - | Ascending indexes
+      | Descending indexes
+    - Only indexes documents that contain a value for at least one of
+      the keys.
+
+  * - | Ascending indexes
+      | Descending indexes
+      | :ref:`Geospatial indexes <index-feature-geospatial>`
+    - Only indexes a document when it contains a value for one of
+      the ``geospatial`` fields. Does not index documents in the
+      ascending or descending indexes.
+
+  * - | Ascending indexes
+      | Descending indexes
+      | :ref:`Text indexes <index-feature-text>`
+    - Only indexes a document when it matches one of the ``text``
+      fields. Does not index documents in the ascending or descending
+      indexes.
+

source/includes/indexes/sparse-index-considerations.rst

@@ -0,0 +1,4 @@
+This index is a :ref:`sparse index <index-type-sparse>`. If you want to
+use a sparse index to create a :ref:`compound index
+<index-type-compound>`, first review the special considerations of using 
+:ref:`sparse compound indexes <sparse-compound-indexes>`.

source/indexes.txt

@@ -173,6 +173,8 @@ provides two special indexes: :ref:`2d indexes <2d-index>` that uses
 planar geometry when returning results and :ref:`2dsphere indexes
 <2dsphere-index>` that use spherical geometry to return results.
 
+.. include:: /includes/indexes/sparse-index-considerations.rst
+
 See :ref:`index-feature-geospatial` for a high level introduction to
 geospatial indexes.
 
@@ -181,6 +183,8 @@ Text Search Indexes
 
 .. include:: /includes/indexes/text-search-indexes-overview.rst
 
+.. include:: /includes/indexes/sparse-index-considerations.rst
+
 Hashed Indexes
 ~~~~~~~~~~~~~~