DOCS-956 indexes that cover queries

Author: kay-kim

source/applications/indexes.txt

@@ -117,32 +117,52 @@ can support all the queries that search a "prefix" subset of those fields.
 Create Indexes that Support Covered Queries
 -------------------------------------------
 
-A covered query is a query in which all the queried fields and
-the returned fields are part of an index; i.e.
+A covered query is a query in which:
 
 - all the fields in the :ref:`query <read-operations-query-document>`
-  are part of that index, **and**
+  are part of an index, **and**
 
 - all the fields returned in the results are in the same index.
 
-Because the index "covers" the query, MongoDB can match the :ref:`query
-conditions <read-operations-query-document>` and return the results
-using only the index. MongoDB does not need to not look at documents
-outside of the index.
+Because the index "covers" the query, MongoDB can both match the
+:ref:`query conditions <read-operations-query-document>` **and** return
+the results using only the index; MongoDB does not need to look at
+documents outside of the index.
 
 Querying *only* the index can be much faster than querying documents
 outside of the index. Index keys are typically smaller than the
 documents they catalog, and indexes are typically available in RAM or
 located sequentially on disk.
 
-MongoDB automatically uses a covered query when possible. To ensure the
-use of a covered query, create an index that includes all the fields
-listed in the query result and the :ref:`query document
-<read-operations-query-document>`. This means that, if the index does
-**not** include the ``_id`` field, the :term:`projection` document
-given to a query (to specify which fields MongoDB returns from the
-result set) must explicitly exclude the ``_id`` field from the result
-set.
+MongoDB automatically uses an index that covers a query when possible.
+To ensure that a query is covered, create an index that includes all
+the fields listed in the query result and the :ref:`query document
+<read-operations-query-document>`. This means that if the index does
+**not** include the ``_id`` field, the :term:`projection` document,
+which specifies the fields MongoDB returns, must explicitly exclude the
+``_id`` field from the result set.
+
+Consider the following example where the collection ``user`` has
+an index on the fields ``user`` and ``status``:
+
+.. code-block:: javascript
+
+   { status: 1, user: 1 }
+
+Then, the following query which queries on the ``status`` field and
+returns only the ``user`` field is covered:
+
+.. code-block:: javascript
+
+   db.users.find( { status: "A" }, { user: 1, _id: 0 } )
+
+However, the following query that uses the index to match documents is
+**not** covered by the index because it returns both the ``user`` field
+**and** the ``_id`` field:
+
+.. code-block:: javascript
+
+   db.users.find( { status: "A" }, { user: 1 } )
 
 An index **cannot** cover a query if:
 
@@ -180,10 +200,16 @@ An index **cannot** cover a query if:
 
      db.users.find( { "user.login": "tester" }, { "user.login": 1, _id: 0 } )
 
-To determine whether a query is covered, use :method:`explain()
-<cursor.explain()>`. If the output displays ``true`` for the
-``indexOnly`` field, the query is covered and MongoDB queried only the
-index. For more information see :ref:`indexes-measuring-use`.
+  The query, however, does use the ``{ "user.login": 1 }`` index to
+  find matching documents.
+
+To determine whether a query is a covered query, use the
+:method:`~cursor.explain()` method. If the :method:`~cursor.explain()`
+output displays ``true`` for the :data:`indexOnly` field, the query is
+covered by an index, and MongoDB queries only that index to match the
+query **and** return the results.
+
+For more information see :ref:`indexes-measuring-use`.
 
 .. _index-sort:
 .. _sorting-with-indexes:

source/core/indexes.txt

@@ -46,11 +46,21 @@ MongoDB indexes have the following core features:
   with the best response time for each query type. You can override
   the query optimizer using the :method:`cursor.hint()` method.
 
-- An index "covers" a query if the index keys store all the data that
-  the query must return. When an index covers a query, the database
-  returns results more quickly than for queries that have to scan many
-  individual documents. See :ref:`indexes-covered-queries` for more
-  information.
+- An index "covers" a query if:
+
+  - all the fields in the :ref:`query <read-operations-query-document>`
+    are part of that index, **and**
+
+  - all the fields returned in the documents that match the query are
+    in the same index.
+
+  When an index covers a query, the database can both match the
+  :ref:`query conditions <read-operations-query-document>` **and**
+  return the results using only the index; MongoDB does not need to
+  look at documents outside of the index. Querying the index can be
+  faster than querying the documents outside of the index.
+
+  See :ref:`indexes-covered-queries` for more information.
 
 - Using queries with good index coverage reduces the number of full
   documents that MongoDB needs to store in memory, thus maximizing database

source/core/read-operations.txt

@@ -463,36 +463,48 @@ operation:
 Covering a Query
 ~~~~~~~~~~~~~~~~
 
-An index :ref:`covers <indexes-covered-queries>` a query when:
+An index :ref:`covers <indexes-covered-queries>` a query, or a query is
+a "covered" query, when:
 
 - all the fields in the :ref:`query <read-operations-query-document>`
   are part of that index, **and**
 
 - all the fields returned in the documents that match the query are in
   the same index.
 
+When an index "covers" the query, MongoDB can both match the
+:ref:`query conditions <read-operations-query-document>` **and** return
+the results using only the index; MongoDB does not need to look at
+documents outside of the index. Querying the index can be faster than
+querying the documents outside of the index.
+
 Consider the following example where the collection ``inventory`` has
 an index on the fields ``type`` and ``item``.
 
 .. code-block:: sh
 
    { type: 1, item: 1 }
 
-Then a query on the ``inventory`` collection that queries on the
-``type`` field and returns only the ``item`` field is covered by the
-index:
+Then the following query that queries on the ``type`` and ``item``
+fields and returns only the ``item`` field is covered by the ``{type:
+1, item: 1}`` index:
 
 .. code-block:: javascript
 
-   db.inventory.find( { type: "food" },
+   db.inventory.find( { type: "food", item:/^c/ },
                       { item: 1, _id: 0 } )
 
-Because the index "covers" the query, MongoDB can match the :ref:`query
-conditions <read-operations-query-document>` and return the results
-using only the index. MongoDB does not need to look at documents
-outside of the index. Querying the index can be faster than querying
-the documents outside of the index. See :ref:`indexes-covered-queries`
-for more information, including when indexes cannot cover a query.
+However, the following query that uses the ``{ type: 1, item: 1 }`` index
+to match documents is **not** covered by the index because the query
+returns the ``item`` field **and** the ``_id`` field:
+
+.. code-block:: javascript
+
+   db.inventory.find( { type: "food", item:/^c/ },
+                      { item: 1 } )
+
+See :ref:`indexes-covered-queries` for more information, including when
+indexes cannot cover a query.
 
 Measuring Index Use
 ~~~~~~~~~~~~~~~~~~~
@@ -588,11 +600,13 @@ the query used an index. This query:
 - then read 5 full documents from the collection, as indicated by
   the :data:`nscannedObjects` field.
 
-  Although the query used an index, the ``indexOnly: false`` indicates
-  that the index did not :ref:`cover <read-operations-covered-query>`
-  the query; i.e. MongoDB could not match the :ref:`query conditions
-  <read-operations-query-document>` and return the results using only
-  that index. See :ref:`indexes-covered-queries` for more information.
+  Although the query uses an index to find the matching documents, the
+  :data:`indexOnly:false <indexOnly>` indicates that this index did
+  not :ref:`cover <read-operations-covered-query>` the query; i.e.
+  MongoDB could not both match the :ref:`query conditions
+  <read-operations-query-document>` **and** return the results using
+  only this index. See :ref:`indexes-covered-queries` for more
+  information.
 
 .. index:: query optimizer
 .. _read-operations-query-optimization:

source/reference/explain.txt

@@ -155,16 +155,17 @@ Core Explain Output
 
    Specifies the total number of documents scanned during the query.
    The :data:`nscannedObjects` may be lower than :data:`nscanned`, such
-   as if the index is a covered index.
+   as if the index :ref:`covers <indexes-covered-queries>` a query. See
+   :data:`indexOnly`.
 
 .. data:: nscanned
 
    Specifies the total number of documents or index entries scanned
    during the database operation. You want :data:`n` and
    :data:`nscanned` to be close in value as possible. The
    :data:`nscanned` value may be higher than the
-   :data:`nscannedObjects` value, such as if the index is a covered
-   index.
+   :data:`nscannedObjects` value, such as if the index :ref:`covers
+   <indexes-covered-queries>` a query. See :data:`indexOnly`.
 
 .. data:: nscannedObjectsAllPlans
 
@@ -194,9 +195,16 @@ Core Explain Output
 .. data:: indexOnly
 
    :data:`indexOnly` is a boolean value that returns ``true`` when the
-   query is :ref:`covered <indexes-covered-queries>` by the index. In
-   *covered* queries, the index contains all data that MongoDB needs
-   to fulfill the query.
+   the query is :ref:`covered <indexes-covered-queries>` by the index
+   indicated in the :data:`cursor` field. When an index covers a query,
+   MongoDB can both match the :ref:`query conditions
+   <read-operations-query-document>` **and** return the results using
+   only the index because:
+
+   - all the fields in the :ref:`query
+     <read-operations-query-document>` are part of that index, **and**
+
+   - all the fields returned in the results set are in the same index.
 
 .. data:: nYields