Read Concern (original) (raw)

The readConcern option allows you to control the consistency and isolation properties of the data read from replica setsand sharded clusters.

Through the effective use of write concernsand 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.

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.

The following read concern levels are available:

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:

• Read Concern "local"
• Read Concern "available"
• Read Concern "majority"
• Read Concern "linearizable"
• Read Concern "snapshot"
• Default MongoDB Read Concerns/Write Concerns

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 mongoshmethod db.collection.find(), use thecursor.readConcern() method:

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

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

You can set the read concern at the transaction start:

• For multi-document transaction, the following read concern levels are available:
  • "local"
  • "majority"
  • "snapshot"
• 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. Ifexplicitly 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.

For operations in a causally consistent session, "local","majority", and "snapshot" levels are available. However, to guarantee causal consistency, you must use"majority". For details, see Causal Consistency.

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, seeTransactions and Read Concern.

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.

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.

You can use causally consistent sessions to read your own writes, if the writes request acknowledgment.

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.

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

} )

MongoDB includes support for causally consistent sessions. For read operations associated with causally consistent session, MongoDB supports 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.

Note

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, themongod must wait to service the request.

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

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

MongoDB tracks read concern provenance, which indicates the source of a particular read concern. You may see provenance shown in thegetLastError metrics, read concern error objects, and MongoDB logs.

The following table shows the possible read concern provenancevalues and their significance: