Skip to content

DOCS-7000: no _id index scan for cursor.snapshot() #2535

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
20 changes: 7 additions & 13 deletions source/faq/developers.txt
Original file line number Diff line number Diff line change
Expand Up @@ -591,15 +591,13 @@ driver <>`.
How do I isolate cursors from intervening write operations?
-----------------------------------------------------------

With the :doc:`MMAPv1 storage engine </core/mmapv1>`, MongoDB cursors
can return the same document more than once in some situations.
[#duplicate-document-in-result-set]_ You can use the
:method:`~cursor.snapshot()` method on a cursor to isolate the
operation for a very specific case.
MongoDB cursors can return the same document more than once in some
situations. [#duplicate-document-in-result-set]_ You can use the
:method:`~cursor.snapshot()` method on a cursor to isolate the operation
for a very specific case.

:method:`~cursor.snapshot()` traverses the index on the ``_id`` field
and guarantees that the query will return each document (with respect to
the value of the ``_id`` field) no more than once. [#id-is-immutable]_
:method:`~cursor.snapshot()` guarantees that the query will return each
document no more than once.

The :method:`~cursor.snapshot()` does not guarantee that the data
returned by the query will reflect a single moment in time *nor* does it
Expand All @@ -610,7 +608,7 @@ provide isolation from insert or delete operations.
- You **cannot** use :method:`~cursor.snapshot()` with
:term:`sharded collections <sharding>`.

- You **cannot** use :method:`~cursor.snapshot()` with
- You **cannot** use :method:`~cursor.snapshot()` with the
:method:`~cursor.sort()` or :method:`~cursor.hint()` cursor methods.

As an alternative, if your collection has a field or fields that are
Expand All @@ -628,10 +626,6 @@ that index.
by the query; then the cursor will return the same document more
than once.

.. [#id-is-immutable] MongoDB does not permit changes to the value of the
``_id`` field; it is not possible for a cursor that transverses
this index to pass the same document more than once.

.. _faq-developers-embed-documents:

When should I embed documents within other documents?
Expand Down
45 changes: 0 additions & 45 deletions source/includes/extracts-concurrency-consistency-recency.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -147,51 +147,6 @@ content: |
:ref:`faq-developers-isolate-cursors`.

---
ref: isolate-cursor-snapshot-faq
content: |
MongoDB cursors can return the same document more than once in some
situations. [#duplicate-document-in-result-set]_ You can use the
:method:`~cursor.snapshot()` method on a cursor to isolate the
operation for a very specific case.

:method:`~cursor.snapshot()` traverses the index on the ``_id``
field and guarantees that the query will return each document (with
respect to the value of the ``_id`` field) no more than once.
[#id-is-immutable]_

The :method:`~cursor.snapshot()` does not guarantee that the data
returned by the query will reflect a single moment in time *nor*
does it provide isolation from insert or delete operations.

.. note::

- You **cannot** use :method:`~cursor.snapshot()` with
:term:`sharded collections <sharding>`.

- You **cannot** use :method:`~cursor.snapshot()` with
:method:`~cursor.sort()` or :method:`~cursor.hint()` cursor methods.

- Queries with results of less than 1 megabyte are effectively
snapshotted.

As an alternative, if your collection has a field or fields that are
never modified, you can use a *unique* index on this field or these
fields to achieve a similar result as the :method:`~cursor.snapshot()`.
Query with :method:`~cursor.hint()` to explicitly force the query to use
that index.

.. [#duplicate-document-in-result-set] As a cursor returns documents
other operations may interleave with the query: if some of these
operations are :doc:`updates </core/write-operations>` that cause
the document to move (in the case of a MMAPv1 collection scan,
caused by document growth) or that change the indexed field on
the index used by the query; then the cursor will return the same
document more than once.

.. [#id-is-immutable] MongoDB does not permit changes to the value
of the ``_id`` field; it is not possible for a cursor that
transverses this index to pass the same document more than once.
---
ref: lock-general
content: |
MongoDB uses multi-granularity locking [#mgl-ref]_ that allows
Expand Down
2 changes: 1 addition & 1 deletion source/includes/ref-toc-operator-meta.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ description: "Modifies the documents returned to include references to the on-di
---
name: ":operator:`$snapshot`"
file: /reference/operator/meta/snapshot
description: "Forces the query to use the index on the ``_id`` field. See :method:`~cursor.snapshot()`."
description: "Guarantees that a query returns each document no more than once. See :method:`~cursor.snapshot()`."
---
name: ":operator:`$query`"
file: /reference/operator/meta/query
Expand Down
5 changes: 2 additions & 3 deletions source/reference/method/cursor.snapshot.txt
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,5 @@ cursor.snapshot()
The :method:`~cursor.snapshot()` does not guarantee
isolation from insertion or deletions.

The :method:`~cursor.snapshot()` traverses the index on the ``_id``
field. As such, :method:`~cursor.snapshot()` **cannot**
be used with :method:`~cursor.sort()` or :method:`~cursor.hint()`.
The :method:`~cursor.snapshot()` **cannot** be used with
:method:`~cursor.sort()` or :method:`~cursor.hint()`.