Read Concern
The readConcern
option allows you to control the consistency and
isolation properties of the data read from replica sets
and sharded clusters.
Through the effective use of write concerns and read concerns, you can adjust the level of consistency and availability guarantees as appropriate, such as waiting for stronger consistency guarantees, or loosening consistency requirements to provide higher availability.
MongoDB drivers updated for MongoDB 3.2 or later support specifying read concern.
Starting in MongoDB 4.4, replica sets and sharded clusters support
setting a global default read concern. Operations which do not
specify an explicit read concern inherit the global default
read concern settings. See setDefaultRWConcern
for
more information.
Read Concern Levels
The following read concern levels are available:
level | Description |
---|---|
The query returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
Availability: Read concern For more information, see the | |
The query returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back). Default for: reads against secondaries if the reads are not associated with causally consistent sessions. Availability: Read concern For sharded clusters, For more information, see the New in version 3.6. | |
The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure. To fulfill read concern "majority", the replica set member
returns data from its in-memory view of the data at the
majority-commit point. As such, read concern
Requirements: To use read concern level of
NoteFor operations in multi-document transactions, read concern For more information, see the | |
The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results. If a majority of your replica set members crash and restart after
the read operation, documents returned by the read operation are
durable if With
You cannot use the Requirements: Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document. TipAlways use For more information, see the | |
A snapshot is a complete copy of the data in a If the transaction is not part of a causally consistent
session, upon transaction commit with write
concern "majority" , the transaction operations
are guaranteed to have read from a snapshot of
majority-committed data.If the transaction is part of a causally consistent
session, upon transaction commit with write
concern "majority" , the transaction operations
are guaranteed to have read from a snapshot of
majority-committed data that provides causal consistency with
the operation immediately preceding the transaction start.
|
Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.
For more information on each read concern level, see:
readConcern
Support
Read Concern Option
For operations not in multi-document transactions, you can specify a readConcern
level as an
option to commands and methods that support read concern:
readConcern: { level: <level> }
To specify the read concern level for the mongo
shell
method db.collection.find()
, use the
cursor.readConcern()
method:
db.collection.find().readConcern(<level>)
Transactions and Available Read Concerns
For multi-document transactions, you set the read concern at the transaction level, not at the individual operation level. The operations in the transaction will use the transaction-level read concern. Any read concern set at the collection and database level is ignored inside the transaction. If the transaction-level read concern is explicitly specified, the client level read concern is also ignored inside the transaction.
Important
Do not explicitly set the read concern for the individual operations. To set the read concern for transactions, see Read Concern/Write Concern/Read Preference.
You can set the read concern at the transaction start:
For multi-document transaction, the following read concern levels are available:
Write commands that are part of a multi-document transactions can support the transaction-level read concern.
You can create collections and indexes inside a transaction. If explicitly creating a collection or an index, the transaction must use read concern
"local"
. If you implicitly create a collection, you can use any of the read concerns available for transactions.
If unspecified at the transaction start, transactions use the session-level read concern or, if that is unset, the client-level read concern.
For more information, see Transaction Read Concern.
Causally Consistent Sessions and Available Read Concerns
For operations in a causally consistent session, "local"
and
"majority"
levels are available. However, to guarantee
causal consistency, you must use "majority"
. For
details, see Causal Consistency.
If a multi-document transaction is associated with a causally
consistent session, "snapshot"
is also available for the
the transaction.
Operations That Support Read Concern
The following operations support read concern:
Important
To set read concern for operations in a transaction, you set the read concern at the transaction level, not at the individual operation level. Do not explicitly set the read concern for the individual operations in a transaction. For more information, see Transactions and Read Concern.
[1] | You cannot use the $out or the $merge stage
in conjunction with read concern "linearizable" . That
is, if you specify "linearizable" read concern for
db.collection.aggregate() , you cannot include either
stages in the pipeline. |
[2] | Read concern "snapshot" is available only for
multi-document transactions. In a transaction, you cannot use the
distinct command or its helpers on a sharded collection. |
The following write operations can also accept a read concern if part of a multi-document transaction:
Important
To set read concern for operations in a transaction, you set the read concern at the transaction level, not at the individual operation level.
Command | |||||
---|---|---|---|---|---|
✓ | ✓ | ||||
✓ | ✓ | ||||
✓ | ✓ | ||||
✓ | ✓ | ||||
✓ | |||||
✓ |
[3] | (1, 2) Read concern "snapshot" is available only for
multi-document transactions, and for transactions, you set the read
concern at the transaction level. The operations that support
"snapshot" correspond to the CRUD operations
available in transactions. For more information, see
Transactions and Read Concern. |
Read Concern not Supported on local
Database
The local database does not support read concerns. MongoDB silently ignores any configured read concern for an operation on a collection in the local database.
Considerations
Read Your Own Writes
Changed in version 3.6.
Starting in MongoDB 3.6, you can use causally consistent sessions to read your own writes, if the writes request acknowledgement.
Prior to MongoDB 3.6, in order to read your own writes you must issue
your write operation with { w: "majority" }
write concern, and then issue your read operation with
primary
read preference, and either
"majority"
or "linearizable"
read concern.
Real Time Order
Combined with "majority"
write concern,
"linearizable"
read concern enables multiple threads to
perform reads and writes on a single document as if a single thread
performed these operations in real time; that is, the corresponding
schedule for these reads and writes is considered linearizable.
Performance Comparisons
Unlike "majority"
, "linearizable"
read
concern confirms with secondary members that the read operation is
reading from a primary that is capable of confirming writes with
{ w: "majority" }
write concern.
[4] As such, reads with linearizable read
concern may be significantly slower than reads with
"majority"
or "local"
read concerns.
Always use maxTimeMS
with linearizable read concern in case a
majority of data bearing members are unavailable. maxTimeMS
ensures
that the operation does not block indefinitely and instead ensures that
the operation returns an error if the read concern cannot be fulfilled.
For example:
db.restaurants.find( { _id: 5 } ).readConcern("linearizable").maxTimeMS(10000) db.runCommand( { find: "restaurants", filter: { _id: 5 }, readConcern: { level: "linearizable" }, maxTimeMS: 10000 } )
[4] | In some circumstances, two nodes in a replica set
may transiently believe that they are the primary, but at most, one
of them will be able to complete writes with { w:
"majority" } write concern. The node that can complete
{ w: "majority" } writes is the current
primary, and the other node is a former primary that has not yet
recognized its demotion, typically due to a network partition.
When this occurs, clients that connect to the former primary may
observe stale data despite having requested read preference
primary , and new writes to the former primary will
eventually roll back. |
Read Operations and afterClusterTime
New in version 3.6.
MongoDB 3.6 introduces support for causally consistent sessions. For read operations associated with causally consistent
session, MongoDB 3.6 introduces the afterClusterTime
read concern
option to be set automatically by the drivers for operations associated
with causally consistent sessions.
Important
Do not manually set afterClusterTime
for a read operation.
MongoDB drivers set this value automatically for operations
associated with causally consistent sessions. However, you can
advance the operation time and the cluster time for the session,
such as to be consistent with the operations of another client
session. For an example, see Examples.
To satisfy a read request with an afterClusterTime
value of T
,
a mongod
must perform the request after its oplog
reaches time T
. If its oplog has not reached time T
, the
mongod
must wait to service the request.
Read operations with a specified afterClusterTime
return data that
meet both the read concern level
requirement and the specified afterClusterTime
requirement.
For read operations not associated with causally consistent sessions,
afterClusterTime
is unset.
Read Concern Provenance
Starting in version 4.4, MongoDB tracks read concern provenance
,
which indicates the source of a particular read concern. You may see
provenance
shown in the
getLastError
metrics, read
concern error objects, and MongoDB logs.
The following table shows the possible read concern provenance
values and their significance:
Provenance | Description |
---|---|
clientSupplied | The read concern was specified in the application. |
customDefault | The read concern originated from a custom defined
default value. See setDefaultRWConcern . |
implicitDefault | The read concern originated from the server in absence
of all other read concern specifications. |