diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 0e8d3ce36f0..c8476baa0ae 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -465,3 +465,37 @@ driver <>`. .. code-block:: javascript db.getCollection("_foo").find() + +.. _faq-developers-isolate-cursors: + +How do I isolate cursors from intervening write operations? +----------------------------------------------------------- + +During the lifetime of the cursor, an intervening write operation can +result in a move of the document due to the growth in document size. +This may cause the cursor to return the document more than once. To +prevent this from happening, you can use the :method:`snapshot() +` method. + +The :method:`snapshot() ` method traverses the index +on the ``_id`` field. As such, :method:`snapshot() ` +**cannot** be used with :method:`sort() ` or +:method:`hint() `. + +The :method:`snapshot() ` does not guarantee +isolation from insertion or deletions. + +.. warning:: + + You can only use :method:`snapshot() ` with + **unsharded** collections. + +Alternatively, if there are field or fields that are never modified, +you can use a *unique* index on this field or these fields to achieve +the same effect as the :method:`snapshot() `. Query +with :method:`hint() ` to explicitly force the use of +that index. + +If you want to use a non-unique index on field(s) that will not be +modified, you can create a unique index by including the ``_id`` field +to the index fields. diff --git a/source/reference/method/cursor.snapshot.txt b/source/reference/method/cursor.snapshot.txt index 974a68831c0..7ca002327e0 100644 --- a/source/reference/method/cursor.snapshot.txt +++ b/source/reference/method/cursor.snapshot.txt @@ -6,15 +6,28 @@ cursor.snapshot() .. method:: cursor.snapshot() - Append the :method:`cursor.snapshot()` method to a cursor to toggle the - "snapshot" mode. This ensures that the query will not miss any - documents and return no duplicates, even if other operations modify - objects while the query runs. + Append the :method:`cursor.snapshot()` method to a cursor to toggle + the "snapshot" mode. This ensures that the query will not return a + document multiple times, even if intervening write operations result + in a move of the document due to the growth in document size. - .. note:: + .. warning:: - You must apply :method:`cursor.snapshot()` to the cursor before - retrieving any documents from the database. + - You must apply :method:`cursor.snapshot()` to the cursor before + retrieving any documents from the database. + - You can only use :method:`snapshot() ` with + **unsharded** collections. + + The :method:`snapshot() ` does not guarantee + isolation from insertion or deletions. + + The :method:`cursor.snapshot()` traverses the index on the ``_id`` + field. As such, :method:`snapshot() ` **cannot** + be used with :method:`sort() ` or :method:`hint() + `. + + + Queries with results of less than 1 megabyte are effectively implicitly snapshotted.