DOCS-10322 BACKPORT (#2565)

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

Author: Dave Cuthbert

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,39 +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>`, :doc:`2d </core/2d>`,
-:doc:`geoHaystack </core/geohaystack>`, and :doc:`text
-</core/index-text>` indexes are always ``sparse``.
+: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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _sparse-compound-indexes:
 
-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.
-
-For sparse compound indexes that contain a geospatial key (i.e.
-:doc:`2dsphere </core/2dsphere>`, :doc:`2d </core/2d>`, or
-:doc:`geoHaystack </core/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 :doc:`text </core/index-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,14 +173,18 @@ provides two special indexes: :doc:`2d indexes </core/2d>` that uses
 planar geometry when returning results and :doc:`2dsphere indexes
 </core/2dsphere>` that use spherical geometry to return results.
 
-See :doc:`/core/geospatial-indexes` for a high level introduction to
+.. include:: /includes/indexes/sparse-index-considerations.rst
+
+See :ref:`index-feature-geospatial` for a high level introduction to
 geospatial indexes.
 
 Text Search Indexes
 ~~~~~~~~~~~~~~~~~~~
 
 .. include:: /includes/indexes/text-search-indexes-overview.rst
 
+.. include:: /includes/indexes/sparse-index-considerations.rst
+
 Hashed Indexes
 ~~~~~~~~~~~~~~