Read Concern¶

On this page

New in version 3.2.

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

Read Concern Levels¶

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

The following read concern levels are available:

level Description

"local"¶

Default. 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).

"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",

you must start the mongod instances with the --enableMajorityReadConcern command line option (or the replication.enableMajorityReadConcern set to true if using a configuration file).
replica sets must use WiredTiger storage engine and election protocol version 1.

"linearizable"¶

The query returns data that reflects all successful writes issued with a write concern of "majority" and acknowledged prior to the start of the read operation. For replica sets that run with writeConcernMajorityJournalDefault set to true, linearizable read concern returns data that will never be rolled back.

With writeConcernMajorityJournalDefault set to false, MongoDB will not wait for w: "majority" writes to be durable before acknowledging the writes. As such, "majority" write operations could possibly roll back in the event of a loss of a replica set member.

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.

Lineariable 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¶

Use the readConcern option to specify the read concern level.

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

The readConcern option is available for the following operations:

find command
aggregate command and the db.collection.aggregate() method
distinct command
count command
parallelCollectionScan command
geoNear command
geoSearch command

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

Considerations¶

Read Your Own Writes¶

If using "majority" or "linearizable" read concern for read operations, use { w: "majority" } write concern for write operations on the primary 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. [1] 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
} )

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

← SQL to MongoDB Mapping Chart Write Concern →