Skip to content

DOCS-1185 clarify _id and projection doc #770

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 27 additions & 18 deletions source/applications/indexes.txt
Original file line number Diff line number Diff line change
Expand Up @@ -136,33 +136,42 @@ located sequentially on disk.

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.
the fields listed in the :ref:`query document
<read-operations-query-document>` and in the query result. By default,
the ``_id`` field is included in the query result. So, if the index
does **not** include the ``_id`` field, then for the index to be able
to cover the query, specify the exclusion of the ``_id`` field (i.e.
``_id: 0``) in the :ref:`projection <projection>` document.

Consider the following example where the collection ``user`` has
an index on the fields ``user`` and ``status``:
.. example::

.. code-block:: javascript
A collection ``users`` has the following index on the fields
``user`` and ``status``:

{ status: 1, user: 1 }
.. code-block:: javascript

Then, the following query which queries on the ``status`` field and
returns only the ``user`` field is covered:
{ status: 1, user: 1 }

.. code-block:: javascript
Then, the following query which queries on the ``status`` field and
returns only the ``user`` field is covered:

db.users.find( { status: "A" }, { user: 1, _id: 0 } )
.. code-block:: javascript

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:
db.users.find( { status: "A" }, { user: 1, _id: 0 } )

.. code-block:: javascript
In the operation, the projection document explicitly specifies
``_id: 0`` to exclude the ``_id`` field from the result since the
index is only on the ``status`` and the ``user`` fields.

If the projection document does not specify the exclusion of the
``_id`` field, the query returns the ``_id`` field. The following
query is **not** covered by the index on the ``status`` and the
``user`` fields because with the projection document ``{ user: 1
}``, the query returns both the ``user`` field and the ``_id`` field:

.. code-block:: javascript

db.users.find( { status: "A" }, { user: 1 } )
db.users.find( { status: "A" }, { user: 1 } )

An index **cannot** cover a query if:

Expand Down
10 changes: 6 additions & 4 deletions source/core/read-operations.txt
Original file line number Diff line number Diff line change
Expand Up @@ -362,8 +362,10 @@ The second argument to the :method:`find() <db.collection.find()>`
method is a projection, and it takes the form of a :term:`document` with
a list of fields for inclusion or exclusion from the result set. You
can either specify the fields to include (e.g. ``{ field: 1 }``) or specify the
fields to exclude (e.g. ``{ field: 0 }``). The ``_id`` field is implicitly
included, unless explicitly excluded.
fields to exclude (e.g. ``{ field: 0 }``). The ``_id`` field is, by
default, included in the result set. To exclude the ``_id`` field from
the result set, you need to specify in the projection document the
exclusion of the ``_id`` field (i.e. ``{ _id: 0 }``).

.. note::

Expand Down Expand Up @@ -393,8 +395,8 @@ Consider the following projection specifications in :method:`find()

db.inventory.find( { type: 'food' }, { item: 1, qty: 1 } )

- You can remove the ``_id`` field by excluding it from the
projection, as in the following example:
- You can remove the ``_id`` field from the results by specifying its
exclusion in the projection, as in the following example:

.. code-block:: javascript

Expand Down