DOCS-690 snapshot query page

Author: kay-kim

source/faq/developers.txt

@@ -466,41 +466,36 @@ driver <>`.
 
       db.getCollection("_foo").find()
 
-.. _faq-developers-snapshot-queries:
+.. _faq-developers-isolate-cursors:
 
-How do I perform a snapshot query in MongoDB?
----------------------------------------------
+How do I isolate cursors from intervening write operations?
+-----------------------------------------------------------
 
-MongoDB does not support full point-in-time snapshot where the cursor
-returned from a query points to the records at the time of the
-query execution, regardless of additional write operations that may
-have occurred during the lifetime of the cursor. However, MongoDB does
-provides a :method:`snapshot() <cursor.snapshot()>` method to prevent
-the case where a cursor could return a document more than once because
-an intervening write operation results in a move of the document due to
-the growth in document size.
+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.
 
-When applied to the cursor returned from :method:`find()`,
-:method:`snapshot() <cursor.snapshot()>` assures that the cursor
-returns a document no more than once.
+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()>`. 
 
-.. note::
+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.
 
-   - Even with :method:`snapshot() <cursor.snapshot()>`, objects
-     inserted or deleted during the lifetime of the cursor may or may
-     not be returned.
-
-   - The :method:`snapshot() <cursor.snapshot()>` method traverses the
-     index on the ``_id``. As such, :method:`snapshot()
-     <cursor.snapshot()>` **cannot** be used with :method:`sort()
-     <cursor.sort()>` or :method:`hint() <cursor.hint()>`. No other
-     index can be used for the query.
-
-   - Alternatively, instead of :method:`snapshot()
-     <cursor.snapshot()>`, you can use a *unique* index on field(s)
-     that will not be modified and use :method:`hint() <cursor.hint()>`
-     to explicitly force that index during the query in order to
-     achieve the same :method:`snapshot() <cursor.snapshot()>` mode.
-     Additionally, 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.
+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.