Skip to content

Commit c5ae350

Browse files
(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
1 parent d557b72 commit c5ae350

File tree

3 files changed

+66
-39
lines changed

3 files changed

+66
-39
lines changed

source/core/index-case-insensitive.txt

Lines changed: 49 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _index-feature-case-insensitive:
22

33
========================
4-
Case Insensitive Indexes
4+
Case-Insensitive Indexes
55
========================
66

77
.. default-domain:: mongodb
@@ -12,44 +12,59 @@ Case Insensitive Indexes
1212
:depth: 2
1313
:class: singlecol
1414

15-
.. versionadded:: 3.4
15+
Case-insensitive indexes support queries that perform string comparisons
16+
without regard for case. Case insensitivity is derived from
17+
:ref:`collation <collation>`.
1618

17-
Case insensitive indexes support queries that perform string
18-
comparisons without regard for case.
19+
.. important::
1920

20-
You can create a case insensitive index with
21-
:method:`db.collection.createIndex()` by specifying the ``collation``
22-
parameter as an option. For example:
23-
24-
.. code-block:: javascript
21+
.. include:: /includes/indexes/case-insensitive-regex-queries.rst
2522

26-
db.collection.createIndex( { "key" : 1 },
27-
{ collation: {
28-
locale : <locale>,
29-
strength : <strength>
30-
}
31-
} )
23+
Command Syntax
24+
--------------
3225

33-
To specify a collation for a case sensitive index, include:
26+
You can create a case-insensitive index with
27+
:method:`db.collection.createIndex()` by specifying the ``collation``
28+
option:
3429

35-
- ``locale``: specifies language rules. See
36-
:ref:`Collation Locales<collation-languages-locales>` for a list of
37-
available locales.
30+
.. code-block:: javascript
3831

39-
- ``strength``: determines comparison rules. A value of
40-
``1`` or ``2`` indicates a case insensitive collation.
32+
db.collection.createIndex(
33+
{
34+
<field>: <sortOrder>
35+
},
36+
{
37+
collation:
38+
{
39+
locale : <locale>,
40+
strength : < 1 | 2 >
41+
}
42+
}
43+
)
44+
45+
To specify a collation for a case-insensitive index, include the
46+
following fields in the ``collation`` object:
47+
48+
.. list-table::
49+
:header-rows: 1
50+
:widths: 10 20
51+
52+
* - Field
53+
- Description
54+
55+
* - ``locale``
56+
- Specifies language rules. For a list of available locales, see
57+
:ref:`collation-languages-locales`.
58+
* - ``strength``
59+
- Determines comparison rules. A ``strength`` value of 1 or 2
60+
indicates case-insensitive collation.
4161

4262
For additional collation fields, see
4363
:ref:`Collation<collation-document-fields>`.
4464

4565
Behavior
4666
--------
4767

48-
Using a case insensitive index does not affect
49-
the results of a query, but it can increase performance; see
50-
:doc:`Indexes</indexes>` for a detailed discussion of the costs and
51-
benefits of indexes.
52-
5368
To use an index that specifies a collation, query and sort operations
5469
must specify the same collation as the index. If a collection has
5570
defined a collation, all queries and indexes inherit that collation
@@ -60,26 +75,28 @@ Examples
6075

6176
.. _no-default-collation-example:
6277

63-
Create a Case Insensitive Index
78+
Create a Case-Insensitive Index
6479
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6580

66-
To use a case insensitive index on a collection with no default
81+
To use a case-insensitive index on a collection with no default
6782
collation, create an index with a collation and set the ``strength``
6883
parameter to ``1`` or ``2`` (see
6984
:ref:`Collation<collation-document-fields>` for a detailed
7085
description of the ``strength`` parameter). You must specify the same
7186
collation at the query level in order to use the index-level collation.
7287

7388
The following example creates a collection with no default collation,
74-
then adds an index on the ``type`` field with a case insensitive
89+
then adds an index on the ``type`` field with a case-insensitive
7590
collation.
7691

7792
.. code-block:: javascript
7893

7994
db.createCollection("fruit")
8095

81-
db.fruit.createIndex( { type: 1},
82-
{ collation: { locale: 'en', strength: 2 } } )
96+
db.fruit.createIndex(
97+
{ type: 1 },
98+
{ collation: { locale: 'en', strength: 2 } }
99+
)
83100

84101
To use the index, queries must specify the same collation.
85102

@@ -99,7 +116,7 @@ To use the index, queries must specify the same collation.
99116

100117
.. _default-collation-example:
101118

102-
Case Insensitive Indexes on Collections with a Default Collation
119+
Case-Insensitive Indexes on Collections with a Default Collation
103120
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104121

105122
When you create a collection with a default collation, all the indexes
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Case-insensitive indexes typically do not improve performance for
2+
:query:`$regex` queries. The ``$regex`` implementation is not
3+
collation-aware and cannot utilize case-insensitive indexes efficiently.

source/reference/operator/query/regex.txt

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,8 @@ expression.
9191
- Syntax Restrictions
9292

9393
* - ``i``
94-
- Case insensitivity to match upper and lower cases.
95-
For an example, see :ref:`regex-case-insensitive`.
94+
- Case insensitivity to match upper and lower cases. For an
95+
example, see :ref:`regex-case-insensitive`.
9696
-
9797

9898
* - ``m``
@@ -249,10 +249,16 @@ operator expressions.
249249
Index Use
250250
~~~~~~~~~~
251251

252+
Index use and performance for ``$regex`` queries varies depending on
253+
whether the query is case-sensitive or case-insensitive.
254+
255+
Case-Sensitive Queries
256+
``````````````````````
257+
252258
.. TODO Probably should clean up a bit of the writing here
253259

254-
For case sensitive regular expression queries, if an index exists for
255-
the field, then MongoDB matches the regular expression against the
260+
For case sensitive regular expression queries, if an index exists
261+
for the field, then MongoDB matches the regular expression against the
256262
values in the index, which can be faster than a collection scan.
257263

258264
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
272278
exists; however, ``/^a.*/``, and ``/^a.*$/`` are slower. ``/^a/``
273279
can stop scanning after matching the prefix.
274280

275-
Case insensitive regular expression queries generally cannot use indexes
276-
effectively. The ``$regex`` implementation is not collation-aware
277-
and is unable to utilize case-insensitive indexes.
281+
Case-Insensitive Queries
282+
````````````````````````
283+
284+
.. include:: /includes/indexes/case-insensitive-regex-queries.rst
278285

279286
Examples
280287
--------

0 commit comments

Comments
 (0)