(DOCS-16615): Clarify case-insensitive regex query behavior (#6108) (#6158)

* (DOCS-16615): Clarify case-insensitive regex query behavior

* fix key formatting

* standardize hyphenation

* fix case

* fix placeholders

* reorg behavior

* reorg

* use admonition

* edits

* tweaks

* wording

Author: jeff-allen-mongo

source/core/index-case-insensitive.txt

@@ -1,7 +1,7 @@
 .. _index-feature-case-insensitive:
 
 ========================
-Case Insensitive Indexes
+Case-Insensitive Indexes
 ========================
 
 .. default-domain:: mongodb
@@ -12,44 +12,59 @@ Case Insensitive Indexes
    :depth: 2
    :class: singlecol
 
-.. versionadded:: 3.4
+Case-insensitive indexes support queries that perform string comparisons
+without regard for case. Case insensitivity is derived from
+:ref:`collation <collation>`.
 
-Case insensitive indexes support queries that perform string
-comparisons without regard for case.
+.. important::
 
-You can create a case insensitive index with
-:method:`db.collection.createIndex()` by specifying the ``collation``
-parameter as an option. For example:
-
-.. code-block:: javascript
+   .. include:: /includes/indexes/case-insensitive-regex-queries.rst
 
-   db.collection.createIndex( { "key" : 1 },
-                              { collation: {
-                                  locale : <locale>,
-                                  strength : <strength>
-                                }
-                              } )
+Command Syntax
+--------------
 
-To specify a collation for a case sensitive index, include:
+You can create a case-insensitive index with
+:method:`db.collection.createIndex()` by specifying the ``collation``
+option:
 
-- ``locale``: specifies language rules. See
-  :ref:`Collation Locales<collation-languages-locales>` for a list of
-  available locales.
+.. code-block:: javascript
 
-- ``strength``: determines comparison rules. A value of
-  ``1`` or ``2`` indicates a case insensitive collation.
+   db.collection.createIndex(
+      {
+         <field>: <sortOrder>
+      },
+      {
+         collation:
+            {
+               locale : <locale>,
+               strength : < 1 | 2 >
+            }
+      }
+   )
+
+To specify a collation for a case-insensitive index, include the
+following fields in the ``collation`` object:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 20
+
+   * - Field
+     - Description
+
+   * - ``locale``
+     - Specifies language rules. For a list of available locales, see
+       :ref:`collation-languages-locales`.
+   * - ``strength``
+     - Determines comparison rules. A ``strength`` value of 1 or 2
+       indicates case-insensitive collation. 
 
 For additional collation fields, see
 :ref:`Collation<collation-document-fields>`.
 
 Behavior
 --------
 
-Using a case insensitive index does not affect
-the results of a query, but it can increase performance; see
-:doc:`Indexes</indexes>` for a detailed discussion of the costs and
-benefits of indexes.
-
 To use an index that specifies a collation, query and sort operations
 must specify the same collation as the index. If a collection has
 defined a collation, all queries and indexes inherit that collation
@@ -60,26 +75,28 @@ Examples
 
 .. _no-default-collation-example:
 
-Create a Case Insensitive Index
+Create a Case-Insensitive Index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To use a case insensitive index on a collection with no default
+To use a case-insensitive index on a collection with no default
 collation, create an index with a collation and set the ``strength``
 parameter to ``1`` or ``2`` (see
 :ref:`Collation<collation-document-fields>` for a detailed
 description of the ``strength`` parameter). You must specify the same
 collation at the query level in order to use the index-level collation.
 
 The following example creates a collection with no default collation,
-then adds an index on the ``type`` field with a case insensitive
+then adds an index on the ``type`` field with a case-insensitive
 collation.
 
 .. code-block:: javascript
 
    db.createCollection("fruit")
 
-   db.fruit.createIndex( { type: 1},
-                         { collation: { locale: 'en', strength: 2 } } )
+   db.fruit.createIndex(
+      { type: 1 },
+      { collation: { locale: 'en', strength: 2 } }
+   )
 
 To use the index, queries must specify the same collation.
 
@@ -99,7 +116,7 @@ To use the index, queries must specify the same collation.
 
 .. _default-collation-example:
 
-Case Insensitive Indexes on Collections with a Default Collation
+Case-Insensitive Indexes on Collections with a Default Collation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When you create a collection with a default collation, all the indexes

source/includes/indexes/case-insensitive-regex-queries.rst

@@ -0,0 +1,3 @@
+Case-insensitive indexes typically do not improve performance for
+:query:`$regex` queries. The ``$regex`` implementation is not
+collation-aware and cannot utilize case-insensitive indexes efficiently.

source/reference/operator/query/regex.txt

@@ -91,8 +91,8 @@ expression.
      - Syntax Restrictions
 
    * - ``i``
-     - Case insensitivity to match upper and lower cases.
-          For an example, see :ref:`regex-case-insensitive`.
+     - Case insensitivity to match upper and lower cases. For an
+       example, see :ref:`regex-case-insensitive`.
      -
 
    * - ``m``
@@ -249,10 +249,16 @@ operator expressions.
 Index Use
 ~~~~~~~~~~
 
+Index use and performance for ``$regex`` queries varies depending on
+whether the query is case-sensitive or case-insensitive.
+
+Case-Sensitive Queries
+``````````````````````
+
 .. TODO Probably should clean up a bit of the writing here
 
-For case sensitive regular expression queries, if an index exists for
-the field, then MongoDB matches the regular expression against the
+For case sensitive regular expression queries, if an index exists
+for the field, then MongoDB matches the regular expression against the
 values in the index, which can be faster than a collection scan.
 
 Further optimization can occur if the regular expression is a "prefix
@@ -272,9 +278,10 @@ All of these expressions use an index if an appropriate index
 exists; however, ``/^a.*/``, and ``/^a.*$/`` are slower. ``/^a/``
 can stop scanning after matching the prefix.
 
-Case insensitive regular expression queries generally cannot use indexes
-effectively. The ``$regex`` implementation is not collation-aware
-and is unable to utilize case-insensitive indexes.
+Case-Insensitive Queries
+````````````````````````
+
+.. include:: /includes/indexes/case-insensitive-regex-queries.rst
 
 Examples
 --------