DOCSP-30780 wildcard compound index page (#3389)

* DOCSP-30780 wildcard indexes

* Staging

* Staging

* Review feedback

* Review feedback

* Staging

* Staging

* Review feedback

* Force build

Author: Dave Cuthbert

source/core/index-wildcard.txt

@@ -31,6 +31,7 @@ You can:
 - :ref:`Create a wildcard index on a single field
   <ex-wildcard-single-field>`
 - :ref:`Create a wildcard index on all fields <ex-wildcard-all-fields>`
+- :ref:`Create a compound wildcard index <wildcard-index-compound>`
 - :ref:`Query and sort with wildcard indexes
   <wildcard-index-query-sort-support>`
 
@@ -225,8 +226,6 @@ Restrictions
   For more information on shard key selection, see
   :ref:`sharding-shard-key`.
 
-- You cannot create a :ref:`compound <index-type-compound>` index.
-
 - You cannot specify the following properties for a wildcard index:
 
   - :ref:`Time to Live (TTL) <index-feature-ttl>`
@@ -238,13 +237,15 @@ Restrictions
   - :ref:`2dsphere (Geospatial) indexes <2dsphere-index>`
   - :ref:`Hashed indexes <index-type-hashed>`
 
-.. important::
-
-   .. include:: /includes/indexes/wildcard-index-note-text.rst 
+.. include:: includes/indexes/wildcard-restrictions-compound.rst
 
 For complete documentation on wildcard index creation restrictions, see 
 :ref:`Wildcard Index Restrictions <wildcard-index-restrictions-create>`.
 
+.. important::
+
+   .. include:: /includes/indexes/wildcard-index-note-text.rst 
+
 Additional Considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -263,6 +264,7 @@ Learn More
    :hidden:
 
    /reference/indexes/index-wildcard-single
+   /reference/indexes/index-wildcard-compound
    /reference/indexes/index-wildcard-query-and-sort
    /reference/indexes/index-wildcard-restrictions
 

source/includes/extracts-wildcard-indexes.yaml

@@ -90,9 +90,10 @@ content: |
        }
      }
 
-  With the exception of explicitly including  ``_id`` field, you cannot
-  combine inclusion and exclusion statements in the
-  ``wildcardProjection`` document.
+  All of the statements in the ``wildcardProjection`` document must be
+  either inclusion or exclusion statements. You can also include the
+  ``_id`` field with exclusion statements. This is the only exception to
+  the rule. 
 ---
 ref: wildcard-index-inclusion-exclusion
 content: |

source/includes/indexes/index-creation-methods.rst

@@ -2,4 +2,4 @@ To create wildcard indexes, use a standard index creation command:
 
 - :dbcommand:`createIndexes`
 - :method:`~db.collection.createIndex()`
-- :method:`~db.collection.createIndexes()`
+- :method:`~db.collection.createIndexes()`

source/includes/indexes/wildcard-indexes-considerations.rst

@@ -1,17 +1,23 @@
-- Wildcard indexes can support at most *one* field in any given query 
-  predicate. For more information on wildcard index query
-  support, see :ref:`wildcard-index-query-sort-support`.
-
 - Wildcard indexes omit the ``_id`` field by default. To include the
-  ``_id`` field in the wildcard index, you must explicitly include it in
-  the wildcardProjection document (i.e. ``{ "_id" : 1 }``).
+  ``_id`` field in a wildcard index, you must explicitly include it in
+  the ``wildcardProjection`` document.
+  
+  .. code-block:: javascript
+    
+     db.salesData.createIndex(
+        { "$**" : 1 },
+        { "wildcardProjection" :
+           { "_id": 1, "customers.lastName": 1, "customers.FirstName": 1, }
+        }
+     )
 
-- You can create multiple wildcard indexes in a collection.
+- You can create more than one wildcard index on a collection.
 
 - A wildcard index may cover the same fields as other indexes in the 
   collection.
 
-- Wildcard indexes are :ref:`sparse <index-type-sparse>` and only
-  contain entries for documents that have the indexed field, even if the
-  index field contains a null value.
+- Wildcard indexes are :ref:`sparse <index-type-sparse>`. They only
+  include entries for documents that contain the indexed field.
 
+  The document is not indexed if all of the fields in the compound
+  wildcard index are missing.

source/includes/indexes/wildcard-projection-specifications.rst

@@ -0,0 +1,20 @@
+
+``wildcardProjection`` works with specifications like:
+
+.. code-block:: javascript
+   :copyable: false
+
+   { "$**": 1 }  
+   { "userID":, "$**": 1 }  
+
+However, you can't define an index that includes the same field in the
+wildcard fields and the regular (non-wildcard) fields. To define the
+index correctly, use a ``wildcardProjection`` to exclude duplicated
+fields from the wildcard pattern.
+
+``wildcardProjection`` does not work with a specification like:
+
+.. code-block:: javascript
+   :copyable: false
+
+    ``{ "path.to.field.$**" : 1 }``  

source/includes/indexes/wildcard-restrictions-compound.rst

@@ -0,0 +1,90 @@
+- A :ref:`compound wildcard index <wildcard-index-compound>` can only
+  have one wildcard term.
+
+  This is an illegal index specification:
+
+  .. code-block:: javascript
+    :copyable: false
+
+     { userID: 1, “someThings.$**”: 1, “otherThings.$**”: 1 }
+
+
+- The non-wildcard terms in a ``compound wildcard index`` must be single
+  key terms. :ref:`Multi-key <index-type-multikey>` index terms are not
+  permitted.
+
+- The ``wildcardProjection`` option is only valid when the wildcard
+  field is ``$**``. You cannot use ``wildcardProjection`` when you
+  specify a field path for the wildcard index term. 
+
+  This is a valid definition: 
+
+  .. code-block:: javascript
+
+    {
+        key: { "$**": 1 },
+        name: "index_all_with_projection",
+        wildcardProjection: {
+           "someFields.name": 1,
+           "otherFields.values": 1
+        }
+    }
+
+  This is an invalid definition: 
+  
+  .. code-block:: javascript
+     :copyable: false
+
+    {
+        key: { "someFields.$**": 1 },
+        name: "invalid_index",
+        wildcardProjection: {
+           "someFields.name": 1,
+           "otherFields.values": 1
+        }
+    }
+
+- The ``_id`` field is omitted by default. If you need the ``_id``
+  field:
+  
+  - Specify a wildcard index as ``$**``
+  - Use a ``wildcardProjection``
+  - Specify the ``_id`` field
+
+
+  .. code-block:: javascript
+   
+     db.studentGrades.createIndex(
+        {
+           "$**": 1,
+        },
+        { 
+           wildcardProjection: {
+              _id: 1,
+              exams: 1, 
+              extraCredit: 1
+           }
+        }
+     )
+
+- The same field cannot be included in the wildcard fields and the
+  regular fields. You can use a ``wildcardProjection`` to exclude fields
+  from the wildcard pattern.
+
+  .. code-block:: javascript
+   
+     db.studentGrades.createIndex(
+        {
+           exams: 1,
+           "$**": 1,
+           homeworks: 1
+        },
+        { 
+           wildcardProjection: {
+              exams: 0, 
+              homeworks: 0
+           }
+        }
+     )
+
+     

source/includes/indexes/wildcard-restrictions.rst

@@ -1,15 +1,17 @@
-
-Wildcard indexes do not support the following index types or index
-properties:
+Wildcard indexes do not support:
 
 - :ref:`2d (Geospatial) indexes <2d-index-internals>`
 - :ref:`2dsphere (Geospatial) indexes <2dsphere-index>`
-- :ref:`Compound indexes <index-type-compound>`
 - :ref:`Hashed indexes <index-type-hashed>`
 - :ref:`Time to Live (TTL) indexes <index-feature-ttl>`
 - :ref:`Text indexes <index-feature-text>`
 - :ref:`Unique indexes <index-type-unique>`
 
-Wildcard indexes are :ref:`sparse <index-type-sparse>`; they don't
-index empty fields. Therefore, wildcard indexes cannot support 
-querying for documents where a field is ``null`` or does not exist.
+Wildcard indexes are :ref:`sparse <index-type-sparse>` indexes. They do
+not support queries when an indexed field does not exist. A wildcard
+index will index the document if the wildcard field has a ``null``
+value.
+
+Starting in MongoDB 7.0, wildcard indexes support ascending (``1``) and
+descending (``-1``) sort order. Earlier versions only supported
+ascending order.

source/includes/indexes/wildcard-use-wc-methods.rst

@@ -0,0 +1,17 @@
+          
+MongoDB supports several different index types, including:
+
+- :ref:`text <index-feature-text>` 
+- :ref:`geospatial <index-feature-geospatial>` 
+- :ref:`hashed indexes <index-type-hashed>`
+
+See :ref:`index types <index-types>` for more information.
+
+:ref:`Wildcard indexes <wildcard-index-core>` support workloads where
+users query against custom fields or a large variety of fields in a
+collection:
+
+- You can create a wildcard index on a specific field and its
+  subpaths or on all of the fields in a document.
+
+  For details see, :ref:`wildcard-index-core`.

source/reference/command/createIndexes.txt

@@ -171,50 +171,8 @@ Each document in the ``indexes`` array can take the following fields:
        type <index-types>`. If specifying direction, specify ``1`` for 
        ascending or ``-1`` for descending.
 
-       
-       MongoDB supports several different index types including
-       :ref:`text <index-feature-text>`, :ref:`geospatial
-       <index-feature-geospatial>`, and :ref:`hashed
-       indexes <index-type-hashed>`. See :ref:`index types
-       <index-types>` for more information.
-       
-       :ref:`Wildcard indexes <wildcard-index-core>`
-       support workloads where users query against custom fields or a
-       large variety of fields in a collection:
-       
-       - To create a wildcard index on all fields and subfields in a 
-         document, specify ``{ "$**" : 1 }`` as the index key. You
-         cannot specify a descending index key when creating a wildcard index.
-       
-         You can also either include *or* exclude specific fields and
-         their subfields from the index using the optional
-         ``wildcardProjection`` parameter.
-       
-         .. include:: /includes/extracts/wildcard-index-id.rst
-       
-       - You can create a wildcard index on a specific field
-         and its subpaths by specifying the full path to that field as 
-         the index key and append ``"$**"`` to the path:
-       
-         ``{ "path.to.field.$**" : 1 }`` 
-       
-         You cannot specify a descending index key when creating a
-         wildcard index.
-       
-         The path-specific wildcard index syntax is incompatible with 
-         the ``wildcardProjection`` option. You cannot specify 
-         additional inclusions or exclusions on the specified path.
-       
-       The wildcard index key **must** use one of the syntaxes listed
-       above. For example, you cannot specify a
-       :doc:`compound index key </core/index-compound>`.  For more 
-       complete documentation on wildcard indexes, including 
-       restrictions on their creation, see :ref:`wildcard-index-restrictions`.
-       
-       For examples of wildcard index creation, see 
-       :ref:`createIndexes-command-wildcard-examples`.
-       
- 
+       ..include:: /includes/indexes/wildcard-use-wc-methods.rst
+
    * - ``name``
 
      - string