Skip to content

Commit ac2a2d8

Browse files
jason-price-mongodbjason-price-mongodb
jason-price-mongodb
and
jason-price-mongodb
authored
DOCS-15185 planner params (#1156)
* DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params * DOCS-15185-planner-params Co-authored-by: jason-price-mongodb <[email protected]>
1 parent 26ee1b9 commit ac2a2d8

File tree

8 files changed

+246
-194
lines changed

8 files changed

+246
-194
lines changed

‎source/core/query-plans.txt

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -257,9 +257,11 @@ Because index filters override the expected behavior of the optimizer
257257
as well as the :method:`~cursor.hint()` method, use index filters
258258
sparingly.
259259

260-
See :dbcommand:`planCacheListFilters`,
261-
:dbcommand:`planCacheClearFilters`, and :dbcommand:`planCacheSetFilter`.
260+
.. include:: /includes/index-filters-and-collations.rst
262261

263262
.. seealso::
264263

265-
:doc:`/applications/indexes`
264+
- :dbcommand:`planCacheListFilters`
265+
- :dbcommand:`planCacheClearFilters`
266+
- :dbcommand:`planCacheSetFilter`
267+
- :doc:`/applications/indexes`

‎source/includes/index-filters-and-collations.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Starting in MongoDB 6.0, an index filter uses the :ref:`collation
2+
<collation>` previously set using the :dbcommand:`planCacheSetFilter`
3+
command.

‎source/reference/command/distinct.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,11 @@ Replica Set Member State Restriction
150150

151151
.. |operations| replace:: :dbcommand:`distinct`
152152

153+
Index Filters and Collations
154+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155+
156+
.. include:: /includes/index-filters-and-collations.rst
157+
153158
Examples
154159
--------
155160

‎source/reference/command/find.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -557,6 +557,10 @@ When using :ref:`Stable API <stable-api>` V1, the following
557557
- ``showRecordId``
558558
- ``tailable``
559559

560+
Index Filters and Collations
561+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
562+
563+
.. include:: /includes/index-filters-and-collations.rst
560564

561565
Examples
562566
--------

‎source/reference/command/planCacheClearFilters.txt

Lines changed: 81 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -24,79 +24,72 @@ Definition
2424
Specify the :term:`query shape` to remove a specific index filter.
2525
Omit the query shape to clear all index filters on a collection.
2626

27-
The command has the following syntax:
27+
Syntax
28+
------
2829

29-
.. code-block:: javascript
30+
The command has the following syntax:
3031

31-
db.runCommand(
32-
{
33-
planCacheClearFilters: <collection>,
34-
query: <query pattern>,
35-
sort: <sort specification>,
36-
projection: <projection specification>,
37-
comment: <any>
38-
}
39-
)
32+
.. code-block:: javascript
4033

41-
The :dbcommand:`planCacheClearFilters` command has the following field:
34+
db.runCommand(
35+
{
36+
planCacheClearFilters: <collection>,
37+
query: <query pattern>,
38+
sort: <sort specification>,
39+
projection: <projection specification>,
40+
collation: { <collation> },
41+
comment: <any>
42+
}
43+
)
4244

45+
Command Fields
46+
--------------
4347

44-
.. list-table::
45-
:header-rows: 1
46-
:widths: 20 20 80
47-
48-
* - Field
49-
50-
- Type
51-
52-
- Description
53-
54-
* - ``planCacheClearFilters``
55-
56-
- string
57-
58-
- The name of the collection.
59-
60-
61-
62-
* - ``query``
63-
64-
- document
65-
66-
- Optional. The query predicate associated with the filter to remove. If
67-
omitted, clears all filters from the collection.
68-
69-
The values in the ``query`` predicate are insignificant in
70-
determining the :term:`query shape`, so the values used in the query
71-
need not match the values shown using
72-
:dbcommand:`planCacheListFilters`.
73-
74-
75-
76-
* - ``sort``
77-
78-
- document
79-
80-
- Optional. The sort associated with the filter to remove, if any.
81-
82-
48+
The command has the following fields:
49+
50+
.. list-table::
51+
:header-rows: 1
52+
:widths: 20 20 80
8353

84-
* - ``projection``
54+
* - Field
55+
- Type
56+
- Description
8557

86-
- document
58+
* - ``planCacheClearFilters``
59+
- string
60+
- The name of the collection to remove the index filters from.
8761

88-
- Optional. The projection associated with the filter to remove,
89-
if any.
90-
62+
* - ``query``
63+
- document
64+
- Optional. The query predicate for the index filter to
65+
remove. If omitted, the command clears all index filters from the
66+
collection.
9167

92-
* - ``comment``
68+
The values in the ``query`` predicate do not:
9369

94-
- any
70+
- Determine the :term:`query shape`.
71+
- Need to match the values returned by
72+
:dbcommand:`planCacheListFilters`.
9573

96-
- .. include:: /includes/extracts/comment-content.rst
97-
98-
.. versionadded:: 4.4
74+
* - ``sort``
75+
- document
76+
- Optional. The sort for the index filter to remove, if any.
77+
78+
* - ``projection``
79+
- document
80+
- Optional. The projection for the index filter to remove, if any.
81+
82+
* - ``collation``
83+
- document
84+
- .. include:: /includes/extracts/collation-option.rst
9985

86+
.. include:: /includes/index-filters-and-collations.rst
87+
88+
* - ``comment``
89+
- any
90+
- .. include:: /includes/extracts/comment-content.rst
91+
92+
.. versionadded:: 4.4
10093

10194
Required Access
10295
---------------
@@ -110,7 +103,7 @@ Examples
110103
Clear Specific Index Filter on Collection
111104
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112105

113-
The ``orders`` collection contains the following two filters:
106+
The ``orders`` collection contains the following index filters:
114107

115108
.. code-block:: javascript
116109

@@ -128,6 +121,16 @@ The ``orders`` collection contains the following two filters:
128121
"indexes" : [ { "status" : 1, "cust_id" : 1 } ]
129122
}
130123

124+
{
125+
"query": { "item": "Movie" },
126+
"collation": { locale: "en_US" },
127+
"indexes": [ { "item": 1, "order_date": 1 , "quantity": 1 } ]
128+
}
129+
130+
.. note::
131+
132+
.. include:: /includes/index-filters-and-collations.rst
133+
131134
The following command removes the second index filter only:
132135

133136
.. code-block:: javascript
@@ -166,6 +169,22 @@ collection:
166169
}
167170
)
168171

172+
Clear Index Filter Containing a Query and a Collation
173+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
174+
175+
The following example clears the index filter containing the query on
176+
``Movie`` and the collation ``en_US`` for the ``orders`` collection:
177+
178+
.. code-block:: javascript
179+
180+
db.runCommand(
181+
{
182+
planCacheClearFilters: "orders",
183+
query: { item: "Movie" },
184+
collation: { locale: "en_US" }
185+
}
186+
)
187+
169188
.. seealso::
170189

171190
- :dbcommand:`planCacheListFilters`

‎source/reference/command/planCacheListFilters.txt

Lines changed: 41 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -18,44 +18,42 @@ Definition
1818
Lists the :ref:`index filters <index-filters>` associated with
1919
:term:`query shapes <query shape>` for a collection.
2020

21-
The command has the following syntax:
21+
:returns:
2222

23-
.. code-block:: javascript
24-
25-
db.runCommand( { planCacheListFilters: <collection> } )
23+
Document listing the index filters. See
24+
:ref:`planCacheListFilters-output`.
2625

27-
The :dbcommand:`planCacheListFilters` command has the following field:
26+
Syntax
27+
------
2828

29+
The command has the following syntax:
2930

30-
.. list-table::
31-
:header-rows: 1
32-
:widths: 20 20 80
33-
34-
* - Field
35-
36-
- Type
37-
38-
- Description
39-
40-
* - ``planCacheListFilters``
41-
42-
- string
43-
44-
- The name of the collection.
31+
.. code-block:: javascript
4532

33+
db.runCommand( { planCacheListFilters: <collection> } )
4634

47-
* - ``comment``
35+
Command Fields
36+
--------------
4837

49-
- any
38+
The command has the following fields:
5039

51-
- .. include:: /includes/extracts/comment-content.rst
52-
53-
.. versionadded:: 4.4
40+
.. list-table::
41+
:header-rows: 1
42+
:widths: 20 20 80
5443

44+
* - Field
45+
- Type
46+
- Description
47+
48+
* - ``planCacheListFilters``
49+
- string
50+
- The name of the collection.
5551

56-
57-
:returns: Document listing the index filters. See
58-
:ref:`planCacheListFilters-output`.
52+
* - ``comment``
53+
- any
54+
- .. include:: /includes/extracts/comment-content.rst
55+
56+
.. versionadded:: 4.4
5957

6058
Required Access
6159
---------------
@@ -79,6 +77,7 @@ the following form:
7977
"query" : <query>
8078
"sort" : <sort>,
8179
"projection" : <projection>,
80+
"collation" : <collation>,
8281
"indexes" : [
8382
<index1>,
8483
...
@@ -112,34 +111,32 @@ the following form:
112111
{ type: "food", status: "A" }
113112
{ type: "utensil", status: "D" }
114113

115-
Together with the :data:`~planCacheListFilters.filters.sort` and
116-
the :data:`~planCacheListFilters.filters.projection`, the
117-
:data:`~planCacheListFilters.filters.query` make up the
118-
:term:`query shape` for the specified index filter.
119-
120114
.. data:: planCacheListFilters.filters.sort
121115

122116
The sort associated with this filter. Can be an empty document.
123117

124-
Together with the :data:`~planCacheListFilters.filters.query` and
125-
the :data:`~planCacheListFilters.filters.projection`, the
126-
:data:`~planCacheListFilters.filters.sort` make up the
127-
:term:`query shape` for the specified index filter.
128-
129118
.. data:: planCacheListFilters.filters.projection
130119

131120
The projection associated with this filter. Can be an empty
132121
document.
133122

134-
Together with the :data:`~planCacheListFilters.filters.query` and
135-
the :data:`~planCacheListFilters.filters.sort`, the
136-
:data:`~planCacheListFilters.filters.projection` make up the
137-
:term:`query shape` for the specified index filter.
123+
.. data:: planCacheListFilters.filters.collation
124+
125+
The :ref:`collation <collation>` associated with this filter. Can
126+
be an empty document.
138127

139128
.. data:: planCacheListFilters.filters.indexes
140129

141-
The array of indexes for this :term:`query shape`. To choose the
142-
optimal query plan, the query optimizer evaluates only the listed
130+
The array of indexes for the :term:`query shape`.
131+
132+
The query shape is the combination of these fields:
133+
134+
- :data:`~planCacheListFilters.filters.query`
135+
- :data:`~planCacheListFilters.filters.sort`
136+
- :data:`~planCacheListFilters.filters.projection`
137+
- :data:`~planCacheListFilters.filters.collation`
138+
139+
To choose the best query plan, the query optimizer evaluates the
143140
:data:`~planCacheListFilters.filters.indexes` *and* the collection
144141
scan.
145142

0 commit comments

Comments
 (0)