Read Concern

The readConcern option allows you to control the consistency andisolation properties of the data read from replica sets and replica setshards.

Through the effective use of write concerns and read concerns, you can adjust the levelof consistency and availability guarantees as appropriate, such aswaiting for stronger consistency guarantees, or loosening consistencyrequirements to provide higher availability.

MongoDB drivers updated for MongoDB 3.2 or later support specifyingread concern.

Read Concern Levels

The following read concern levels are available:

Regardless of the read concern level, the most recent data on anode may not reflect the most recent version of the data in the system.

For more information on each read concern level, see:

• Read Concern "local"
• Read Concern "available"
• Read Concern "majority"
• Read Concern "linearizable"
• Read Concern "snapshot"

readConcern Support

Read Concern Option

For operations not in multi-document transactions, you can specify a readConcern level as anoption to commands and methods that support read concern:

readConcern: { level: <level> }

To specify the read concern level for the mongo shellmethod db.collection.find(), use thecursor.readConcern() method:

db.collection.find().readConcern(<level>)

Transactions and Available Read Concerns

For multi-document transactions, you setthe read concern at the transaction level, not at the individualoperation level. The operations in the transaction will use thetransaction-level read concern. Any read concern set at the collectionand database level is ignored inside the transaction. If thetransaction-level read concern is explicitly specified, the clientlevel read concern is also ignored inside the transaction.

Important

Do not explicitly set the read concern for the individualoperations. To set the read concern for transactions, seeRead Concern/Write Concern/Read Preference.

You can set the read concern at the transaction start:

• For multi-document transaction, read concern levels"snapshot", "local" and"majority" are available.
• Write commands that are part of a multi-document transactions can support the transaction-level read concern.

If unspecified at the transaction start, transactions use thesession-level read concern or, if that is unset, the client-level readconcern.

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 guaranteecausal consistency, you must use "majority". Fordetails, see Causal Consistency.

If a multi-document transaction is associated with a causallyconsistent session, "snapshot" is also available for thethe transaction.

Operations That Support Read Concern

The following operations support read concern:

Important

To set read concern for operations in a transaction, you set theread concern at the transaction level, not at the individualoperation level. Do not explicitly set the read concern for theindividual operations in a transaction. For more information, seeTransactions and Read Concern.

The following write operations can also accept a read concern if partof a multi-document transaction:

Important

To set read concern for operations in a transaction, you set theread concern at the transaction level, not at the individualoperation level.

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 requestacknowledgement.

Prior to MongoDB 3.6, you must have issued your write operation with{ w: "majority" } write concern and thenuse either "majority" or "linearizable"read concern for the read operations to ensure that a single thread canread its own writes.

Real Time Order

Combined with "majority" write concern,"linearizable" read concern enables multiple threads toperform reads and writes on a single document as if a single threadperformed these operations in real time; that is, the correspondingschedule for these reads and writes is considered linearizable.

Performance Comparisons

Unlike "majority", "linearizable" readconcern confirms with secondary members that the read operation isreading from a primary that is capable of confirming writes with{ w: "majority" } write concern.[4] As such, reads with linearizable readconcern may be significantly slower than reads with"majority" or "local" read concerns.

Always use maxTimeMS with linearizable read concern in case amajority of data bearing members are unavailable. maxTimeMS ensuresthat the operation does not block indefinitely and instead ensures thatthe 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
} )

Read Operations and afterClusterTime

New in version 3.6.

MongoDB 3.6 introduces support for causally consistent sessions. For read operations associated with causally consistentsession, MongoDB 3.6 introduces the afterClusterTime read concernoption to be set automatically by the drivers for operations associatedwith causally consistent sessions.

Important

Do not manually set afterClusterTime for a read operation.MongoDB drivers set this value automatically for operationsassociated with causally consistent sessions. However, you canadvance the operation time and the cluster time for the session,such as to be consistent with the operations of another clientsession. For an example, see Examples.

To satisfy a read request with an afterClusterTime value of T,a mongod must perform the request after its oplogreaches time T. If its oplog has not reached time T, themongod must wait to service the request.

Read operations with a specified afterClusterTime return data thatmeet both the read concern levelrequirement and the specified afterClusterTime requirement.

For read operations not associated with causally consistent sessions,afterClusterTime is unset.