Skip to content

Commit 0618694

Browse files
jeff-allen-mongojeff-allen-mongo
committed
Improvements to snapshot read documentation (#395)
* (DOCSP-20511-DOCSP-20512): Updates for snapshot reads * Add long-running queries page * WIP * Add section on snapshot window configuration * rename file * word tweak * shorten query output * Change ToC depth * Word tweak and formatting fix * Apply suggestions from code review * Updates per review * Word tweak
1 parent 526946b commit 0618694

File tree

3 files changed

+201
-11
lines changed

3 files changed

+201
-11
lines changed

‎source/reference/read-concern-snapshot.txt

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ Read Concern ``"snapshot"``
1111
.. meta::
1212
:description: read concern, snapshot read concern, read isolation, transactions, multi-document transactions
1313
:keywords: read concern, snapshot read concern, read isolation, transactions, multi-document transactions
14+
15+
.. contents:: On this page
16+
:local:
17+
:backlinks: none
18+
:depth: 1
19+
:class: singlecol
1420

1521
.. versionadded:: 4.0
1622
.. versionchanged:: 5.0
@@ -33,7 +39,7 @@ read operations outside of multi-document transactions.
3339

3440
Outside of multi-document transactions, read concern
3541
:readconcern:`"snapshot"` is available on primaries and secondaries for
36-
the following read operations :
42+
the following read operations:
3743

3844
- :dbcommand:`find`
3945
- :dbcommand:`aggregate`
@@ -67,7 +73,7 @@ Read Concern and ``atClusterTime``
6773

6874
.. versionadded:: 5.0
6975

70-
Outside of multi-document transaction, reads with read concern
76+
Outside of multi-document transactions, reads with read concern
7177
:readconcern:`"snapshot"` support the optional parameter
7278
``atClusterTime``. The parameter ``atClusterTime`` allows you to specify
7379
the timestamp for the read. To satisfy a read request with a specified
@@ -103,15 +109,25 @@ the client.
103109
Outside of transactions, :readconcern:`"snapshot"` reads are
104110
guaranteed to read from majority-committed data.
105111

106-
.. note:
107-
108-
- If you perform a read operation with :readconcern:`"snapshot"`
109-
against a delayed replica set member, the returned majority-committed
110-
data could be stale.
111-
112-
- It is not possible to specify ``atClusterTime`` for
113-
:readconcern:`"snapshot"` inside of :ref:`causally consistent
114-
sessions <sessions>`.
112+
``atClusterTime`` Considerations and Behavior
113+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114+
115+
- The allowed values for ``atClusterTime`` depend on the
116+
:parameter:`minSnapshotHistoryWindowInSeconds` parameter.
117+
``minSnapshotHistoryWindowInSeconds`` is the minimum time window in
118+
seconds for which the storage engine keeps the snapshot history. If
119+
you specify an :ref:`atClusterTime <atClusterTime>` value older than
120+
the oldest snapshot retained according to
121+
``minSnapshotHistoryWindowInSeconds``, :binary:`~bin.mongod` returns
122+
an error.
123+
124+
- If you perform a read operation with :readconcern:`"snapshot"`
125+
against a delayed replica set member, the returned majority-committed
126+
data could be stale.
127+
128+
- It is not possible to specify ``atClusterTime`` for
129+
:readconcern:`"snapshot"` inside of :ref:`causally consistent
130+
sessions <sessions>`.
115131

116132
Read Concern on Capped Collections
117133
----------------------------------

‎source/tutorial/long-running-queries.txt

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
.. _tutorial-long-running-queries:
2+
3+
============================
4+
Perform Long-Running Queries
5+
============================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
When MongoDB performs long-running queries using the default read
16+
concern of :readconcern:`"local"`, the snapshot time from which data is
17+
returned is subject to change. The snapshot time may move forward as the
18+
query runs, and the query may return unexpected or inconsistent results.
19+
20+
To guarantee the snapshot time and work from a single point in time
21+
across a cluster, use read concern :readconcern:`"snapshot"`. Read
22+
concern :readconcern:`"snapshot"` allows you to specify the
23+
:ref:`atClusterTime <atClusterTime>` parameter, indicating the exact
24+
point in time from which to return your data.
25+
26+
Example
27+
-------
28+
29+
Create a ``movies`` collection with these documents:
30+
31+
.. code-block:: javascript
32+
33+
db.movies.insertMany( [
34+
{
35+
title: 'Titanic',
36+
year: 1997,
37+
genres: [ 'Drama', 'Romance' ],
38+
rated: 'PG-13',
39+
languages: [ 'English', 'French', 'German', 'Swedish', 'Italian', 'Russian' ],
40+
released: ISODate("1997-12-19T00:00:00.000Z"),
41+
cast: [ 'Leonardo DiCaprio', 'Kate Winslet', 'Billy Zane', 'Kathy Bates' ],
42+
directors: [ 'James Cameron' ]
43+
},
44+
{
45+
title: 'The Dark Knight',
46+
year: 2008,
47+
genres: [ 'Action', 'Crime', 'Drama' ],
48+
rated: 'PG-13',
49+
languages: [ 'English', 'Mandarin' ],
50+
released: ISODate("2008-07-18T00:00:00.000Z"),
51+
cast: [ 'Christian Bale', 'Heath Ledger', 'Aaron Eckhart', 'Michael Caine' ],
52+
directors: [ 'Christopher Nolan' ]
53+
},
54+
{
55+
title: 'Spirited Away',
56+
year: 2001,
57+
genres: [ 'Animation', 'Adventure', 'Family' ],
58+
rated: 'PG',
59+
languages: [ 'Japanese' ],
60+
released: ISODate("2003-03-28T00:00:00.000Z"),
61+
cast: [ 'Rumi Hiiragi', 'Miyu Irino', 'Mari Natsuki', 'Takashi Naitè' ],
62+
directors: [ 'Hayao Miyazaki' ]
63+
},
64+
{
65+
title: 'Casablanca',
66+
genres: [ 'Drama', 'Romance', 'War' ],
67+
rated: 'PG',
68+
cast: [ 'Humphrey Bogart', 'Ingrid Bergman', 'Paul Henreid', 'Claude Rains' ],
69+
languages: [ 'English', 'French', 'German', 'Italian' ],
70+
released: ISODate("1943-01-23T00:00:00.000Z"),
71+
directors: [ 'Michael Curtiz' ],
72+
lastupdated: '2015-09-04 00:22:54.600000000',
73+
year: 1942
74+
}
75+
] )
76+
77+
The following command:
78+
79+
- Performs a :dbcommand:`find` operation on the ``movies`` collection
80+
with read concern :readconcern:`"snapshot"`.
81+
82+
- Specifies a filter to only return documents where the ``directors`` field
83+
contains ``Christopher Nolan``.
84+
85+
- Specifies that the operation should read data from the snapshot at
86+
cluster time ``Timestamp(1643066050, 1)``.
87+
88+
.. important::
89+
90+
To run this example, you must set the :ref:`atClusterTime
91+
<atClusterTime>` value to a timestamp that occurs after the time at
92+
which you inserted the data.
93+
94+
.. code-block:: javascript
95+
96+
db.runCommand( {
97+
find: "movies",
98+
filter: { directors: "Christopher Nolan" },
99+
readConcern: {
100+
level: "snapshot",
101+
atClusterTime: Timestamp(1643066050, 1)
102+
},
103+
} )
104+
105+
Example output:
106+
107+
.. code-block:: javascript
108+
109+
{
110+
cursor: {
111+
firstBatch: [
112+
{
113+
_id: ObjectId("61ef27ac707c25130e7611f8"),
114+
title: 'The Dark Knight',
115+
year: 2008,
116+
genres: [ 'Action', 'Crime', 'Drama' ],
117+
rated: 'PG-13',
118+
languages: [ 'English', 'Mandarin' ],
119+
released: ISODate("2008-07-18T00:00:00.000Z"),
120+
cast: [
121+
'Christian Bale',
122+
'Heath Ledger',
123+
'Aaron Eckhart',
124+
'Michael Caine'
125+
],
126+
directors: [ 'Christopher Nolan' ]
127+
}
128+
],
129+
id: Long("0"),
130+
ns: 'test.movies',
131+
atClusterTime: Timestamp({ t: 1643066050, i: 1 })
132+
},
133+
ok: 1,
134+
'$clusterTime': {
135+
clusterTime: Timestamp({ t: 1643066060, i: 1 }),
136+
signature: {
137+
hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
138+
keyId: Long("0")
139+
}
140+
},
141+
operationTime: Timestamp({ t: 1643066060, i: 1 })
142+
}
143+
144+
Consideration
145+
~~~~~~~~~~~~~
146+
147+
Due to the small size of the data set used in this example, there is not
148+
a large benefit to using read concern :readconcern:`"snapshot"`. The
149+
query should run fast enough such that all data is returned at the
150+
same cluster time without needing to specify read concern
151+
:readconcern:`"snapshot"`.
152+
153+
The purpose of the preceding example is to demonstrate the syntax and expected
154+
output for read concern :readconcern:`"snapshot"`.
155+
156+
Configure Snapshot Retention
157+
----------------------------
158+
159+
By default, the WiredTiger storage engine retains snapshot history for
160+
300 seconds. This means that you can specify an :ref:`atClusterTime
161+
<atClusterTime>` value for your query that is up to 300 seconds before
162+
the time at which you run the query.
163+
164+
If your query runs for longer than 300 seconds, you may wish to increase
165+
the snapshot retention period. To specify how long WiredTiger keeps the
166+
snapshot history, modify the
167+
:parameter:`minSnapshotHistoryWindowInSeconds` parameter.
168+
169+
Increasing the value of :parameter:`minSnapshotHistoryWindowInSeconds`
170+
increases disk usage because the server must maintain the history of
171+
older modified values within the specified time window. The amount of
172+
disk space used depends on your workload, with higher volume workloads
173+
requiring more disk space.

‎source/tutorial/query-documents.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -596,4 +596,5 @@ level of isolation for their reads. For more information, see
596596
/tutorial/query-array-of-documents
597597
/tutorial/project-fields-from-query-results
598598
/tutorial/query-for-null-fields
599+
/tutorial/long-running-queries
599600
/tutorial/iterate-a-cursor/

0 commit comments

Comments
 (0)