Snapshot 1

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()
+<cursor.snapshot()>` method.
+
+The :method:`snapshot() <cursor.snapshot()>` method traverses the index
+on the ``_id`` field. As such, :method:`snapshot() <cursor.snapshot()>`
+**cannot** be used with :method:`sort() <cursor.sort()>` or
+:method:`hint() <cursor.hint()>`. 
+
+The :method:`snapshot() <cursor.snapshot()>` does not guarantee
+isolation from insertion or deletions.
+
+.. warning::
+
+   You can only use :method:`snapshot() <cursor.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() <cursor.snapshot()>`. Query
+with :method:`hint() <cursor.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.

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() <cursor.snapshot()>` with
+        **unsharded** collections.
+
+   The :method:`snapshot() <cursor.snapshot()>` does not guarantee
+   isolation from insertion or deletions.
+
+   The :method:`cursor.snapshot()` traverses the index on the ``_id``
+   field. As such, :method:`snapshot() <cursor.snapshot()>` **cannot**
+   be used with :method:`sort() <cursor.sort()>` or :method:`hint()
+   <cursor.hint()>`.
+
+
+
    Queries with results of less than 1 megabyte are effectively
    implicitly snapshotted.