From b7398eb65d733eaad45bb07ac42cc343f01cc506 Mon Sep 17 00:00:00 2001 From: kay Date: Thu, 15 Nov 2012 11:58:23 -0500 Subject: [PATCH 1/2] DOCS-690 snapshot queries faq --- source/faq/developers.txt | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 0e8d3ce36f0..49f387b041d 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -465,3 +465,42 @@ driver <>`. .. code-block:: javascript db.getCollection("_foo").find() + +.. _faq-developers-snapshot-queries: + +How do I perform a snapshot query in MongoDB? +--------------------------------------------- + +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() ` 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. + +When applied to the cursor returned from :method:`find()`, +:method:`snapshot() ` assures that the cursor +returns a document no more than once. + +.. note:: + + - Even with :method:`snapshot() `, objects + inserted or deleted during the lifetime of the cursor may or may + not be returned. + + - The :method:`snapshot() ` method traverses the + index on the ``_id``. As such, :method:`snapshot() + ` **cannot** be used with :method:`sort() + ` or :method:`hint() `. No other + index can be used for the query. + + - Alternatively, instead of :method:`snapshot() + `, you can use a *unique* index on field(s) + that will not be modified and use :method:`hint() ` + to explicitly force that index during the query in order to + achieve the same :method:`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. From 3e25fc4335ce70d15ece8ad902e435b50ee87e7c Mon Sep 17 00:00:00 2001 From: kay Date: Fri, 7 Dec 2012 17:27:10 -0500 Subject: [PATCH 2/2] DOCS-690 snapshot query page --- source/faq/developers.txt | 61 ++++++++++----------- source/reference/method/cursor.snapshot.txt | 27 ++++++--- 2 files changed, 48 insertions(+), 40 deletions(-) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 49f387b041d..c8476baa0ae 100644 --- a/source/faq/developers.txt +++ b/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() ` 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() +` method. -When applied to the cursor returned from :method:`find()`, -:method:`snapshot() ` assures that the cursor -returns a document no more than once. +The :method:`snapshot() ` method traverses the index +on the ``_id`` field. As such, :method:`snapshot() ` +**cannot** be used with :method:`sort() ` or +:method:`hint() `. -.. note:: +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. - - Even with :method:`snapshot() `, objects - inserted or deleted during the lifetime of the cursor may or may - not be returned. - - - The :method:`snapshot() ` method traverses the - index on the ``_id``. As such, :method:`snapshot() - ` **cannot** be used with :method:`sort() - ` or :method:`hint() `. No other - index can be used for the query. - - - Alternatively, instead of :method:`snapshot() - `, you can use a *unique* index on field(s) - that will not be modified and use :method:`hint() ` - to explicitly force that index during the query in order to - achieve the same :method:`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. 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.