@@ -117,32 +117,99 @@ can support all the queries that search a "prefix" subset of those fields.
117117Create Indexes that Support Covered Queries
118118-------------------------------------------
119119
120- A covered index query is a query in which all the queried fields are
121- part of an index. They are "covered queries" because an index "covers" the query.
122- MongoDB can fulfill the query by using *only* the index. MongoDB need
123- not scan documents from the database.
124-
125- Querying *only* the index is much faster than querying documents. Index
126- keys are typically smaller than the documents they catalog, and indexes
127- are typically stored in RAM or located sequentially on disk.
128-
129- Mongod automatically uses a covered query when possible. To ensure use
130- of a covered query, create an index that includes all the fields listed
131- in the query result. This means that the :term:`projection` document
132- given to a query (to specify which fields MongoDB returns from
133- the result set) must
134- explicitly exclude the ``_id`` field from the result set, unless the
135- index includes ``_id``.
136-
137- MongoDB cannot use a covered query if any of the indexed fields in any
138- of the documents in the collection includes an array. If an indexed field
139- is an array, the index becomes a :ref:`multi-key index
140- <index-type-multikey>` index and cannot support a covered query.
141-
142- To test whether MongoDB used a covered query, use
143- :method:`explain() <cursor.explain()>`. If the output displays ``true``
144- for the ``indexOnly`` field, MongoDB used a covered query. For
145- more information see :ref:`indexes-measuring-use`.
120+ A covered query is a query in which:
121+
122+ - all the fields in the :ref:`query <read-operations-query-document>`
123+ are part of an index, **and**
124+
125+ - all the fields returned in the results are in the same index.
126+
127+ Because the index "covers" the query, MongoDB can both match the
128+ :ref:`query conditions <read-operations-query-document>` **and** return
129+ the results using only the index; MongoDB does not need to look at
130+ the documents, only the index, to fulfill the query.
131+
132+ Querying *only* the index can be much faster than querying documents
133+ outside of the index. Index keys are typically smaller than the
134+ documents they catalog, and indexes are typically available in RAM or
135+ located sequentially on disk.
136+
137+ MongoDB automatically uses an index that covers a query when possible.
138+ To ensure that a query is covered, create an index that includes all
139+ the fields listed in the query result and the :ref:`query document
140+ <read-operations-query-document>`. This means that if the index does
141+ **not** include the ``_id`` field, the :term:`projection` document,
142+ which specifies the fields MongoDB returns, must explicitly exclude the
143+ ``_id`` field from the result set.
144+
145+ Consider the following example where the collection ``user`` has
146+ an index on the fields ``user`` and ``status``:
147+
148+ .. code-block:: javascript
149+
150+ { status: 1, user: 1 }
151+
152+ Then, the following query which queries on the ``status`` field and
153+ returns only the ``user`` field is covered:
154+
155+ .. code-block:: javascript
156+
157+ db.users.find( { status: "A" }, { user: 1, _id: 0 } )
158+
159+ However, the following query that uses the index to match documents is
160+ **not** covered by the index because it returns both the ``user`` field
161+ **and** the ``_id`` field:
162+
163+ .. code-block:: javascript
164+
165+ db.users.find( { status: "A" }, { user: 1 } )
166+
167+ An index **cannot** cover a query if:
168+
169+ - any of the indexed fields in any of the documents in the collection
170+ includes an array. If an indexed field is an array, the index becomes
171+ a :ref:`multi-key index <index-type-multikey>` index and cannot
172+ support a covered query.
173+
174+ - any of the indexed fields are fields in subdocuments. To index fields
175+ in subdocuments, use :term:`dot notation`. For example, consider
176+ a collection ``users`` with documents of the following form:
177+
178+ .. code-block:: javascript
179+
180+ { _id: 1, user: { login: "tester" } }
181+
182+ The collection has the following indexes:
183+
184+ .. code-block:: none
185+
186+ { user: 1 }
187+
188+ { "user.login": 1 }
189+
190+ The ``{ user: 1 }`` index covers the following query:
191+
192+ .. code-block:: none
193+
194+ db.users.find( { user: { login: "tester" } }, { user: 1, _id: 0 } )
195+
196+ However, the ``{ "user.login": 1 }`` index does **not** cover the
197+ following query:
198+
199+ .. code-block:: none
200+
201+ db.users.find( { "user.login": "tester" }, { "user.login": 1, _id: 0 } )
202+
203+ The query, however, does use the ``{ "user.login": 1 }`` index to
204+ find matching documents.
205+
206+ To determine whether a query is a covered query, use the
207+ :method:`~cursor.explain()` method. If the :method:`~cursor.explain()`
208+ output displays ``true`` for the :data:`indexOnly` field, the query is
209+ covered by an index, and MongoDB queries only that index to match the
210+ query **and** return the results.
211+
212+ For more information see :ref:`indexes-measuring-use`.
146213
147214.. _index-sort:
148215.. _sorting-with-indexes:
0 commit comments