Navigation

Read Concern

New in version 3.2.

Changed in version 3.4: Adds support for "linearizable" read concern level.

Changed in version 3.6: Adds support for:

The readConcern query option for replica sets and replica set shards determines which data to return from a query.

readConcern: { level: <"majority"|"local"|"linearizable"|"available"> }
readConcern: { level: <"majority"|"local"> , afterClusterTime: <Timestamp> }

Read Concern Levels

The following read concern levels are available:

level Description
"local"

Default for reads against primary if level is unspecified and for reads against secondaries if level is unspecified but afterClusterTime is specified.

The query returns the instance’s most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).

"available"

Default for reads against secondaries when afterClusterTime and level are unspecified.

The query returns the instance’s most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).

For unsharded collections (including collections in a standalone deployment or a replica set deployment), "local" and "available" read concerns behave identically.

For a sharded cluster, "available" read concern provides greater tolerance for partitions since it does not wait to ensure consistency guarantees. However, a query with "available" read concern may return orphan documents if the shard is undergoing chunk migrations since the "available" read concern, unlike "local" read concern, does not contact the shard’s primary nor the config servers for updated metadata.

New in version 3.6.

"majority"

The query returns the instance’s most recent data acknowledged as having been written to a majority of members in the replica set.

To use read concern level of "majority", replica sets must use WiredTiger storage engine and election protocol version 1.

"linearizable"

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 writeConcernMajorityJournalDefault is set to the default state of true.

With writeConcernMajorityJournalDefault set to false, MongoDB does not wait for w: "majority" writes to be written to the on-disk journal before acknowledging the writes. As such, majority write operations could possibly roll back in the event of a transient loss (e.g. crash and restart) of a majority of nodes in a given replica set.

You can specify linearizable read concern for read operations on the primary only.

Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document.

Tip

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.

Linearizable read concern is available for both MMAPv1 and WiredTiger. See Storage Engine and Drivers Support.

New in version 3.4.

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.

Storage Engine and Drivers Support

Read Concern WiredTiger MMAPv1
"local"
"majority"  
"linearizable"

Tip

The serverStatus command returns the storageEngine.supportsCommittedReads field which indicates whether the storage engine supports "majority" read concern.

MongoDB drivers updated for 3.2 and later versions support specifying a read concern option.

readConcern Option

Changed in version 3.6.

Use the readConcern option to specify the read concern level [1] :

readConcern: { level: <"majority"|"local"|"linearizable"> }

The readConcern option is available for the following operations:

To specify the read concern level for the mongo shell method db.collection.find(), use the cursor.readConcern() method.

[1]For causally consistent sessions, MongoDB drivers automatically specifies the afterClusterTime value in the read concern.

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, you must have issued your write operation with { w: "majority" } write concern and then use either "majority" or "linearizable" read concern for the read operations to ensure that a single thread can read its own writes.

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. [2] 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
} )

afterClusterTime

New in version 3.6.

MongoDB 3.6 introduces the afterClusterTime option that can be set by the drivers. 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.

Important

Do not manually set afterClusterTime. MongoDB drivers set this value automatically for operations associated with causally consistent sessions.

Causally consistent sessions use the afterClusterTime value to provide causal consistency.

afterClusterTime is available for "local" (default) and "majority" read concern levels:

readConcern: { level: <"majority"|"local"> , afterClusterTime: <Timestamp> }

For read operations not associated with causally consistent sessions, i.e. where afterClusterTime is unset, reads against secondary members have the default read concern level "available", meaning that queries will return the instance’s most recent data. "available" provides no guarantee that data has been written to a majority of the replica set members. It might be rolled back.

[2]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.