- MongoDB CRUD Operations >
- Read Concern
Read Concern¶
On this page
The readConcern
option allows you to control the recency,
consistency, and isolation properties of the data read from replica
sets and replica set shards.
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.
Read Concern Levels¶
The following read concern levels are available:
level |
Description |
---|---|
"local" |
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).
Read concern For more information, see the |
"available" |
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. For sharded collections, Read concern For more information, see the New in version 3.6. |
"majority" |
The query returns 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 use read concern level of Starting in MongoDB 3.6, support for read concern
Read concern For more information, see the |
"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 With You can specify linearizable read concern for read operations on
the Read concern Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document. Tip Always use For more information, see the |
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
Syntax¶
You can specify a readConcern
level [1] as an
option:
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.
Operations That Support Read Concern¶
The following operations support the readConcern
option:
find
commandaggregate
command and thedb.collection.aggregate()
methoddistinct
commandcount
commandparallelCollectionScan
commandgeoNear
commandgeoSearch
commandgroup
command
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, 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.
[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:
[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. |
Read Operations and Causally Consistent Sessions¶
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.
The afterClusterTime
read concern option is available for
"local"
and "majority"
read
concern levels:
Important
Do not manually set afterClusterTime
. MongoDB drivers set
this value automatically for operations associated with
causally consistent sessions.
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.