Navigation

Distributed Queries

Read Operations to Replica Sets

By default, clients reads from a replica set’s primary; however, clients can specify a read preference to direct read operations to other members. For example, clients can configure read preferences to read from secondaries or from nearest member to:

  • reduce latency in multi-data-center deployments,
  • improve read throughput by distributing high read-volumes (relative to write volume),
  • perform backup operations, and/or
  • allow reads until a new primary is elected.
Read operations to a replica set. Default read preference routes the read to the primary. Read preference of ``nearest`` routes the read to the nearest member.

Read operations from secondary members of replica sets may not reflect the current state of the primary. Read preferences that direct read operations to different servers may result in non-monotonic reads.

Changed in version 3.6: Starting in MongoDB 3.6, clients can use causally consistent sessions, which provides various guarantees, including monotonic reads.

You can configure the read preference on a per-connection or per-operation basis. For more information on read preference or on the read preference modes, see Read Preference and Read Preference Modes.

Write Operations on Replica Sets

In replica sets, all write operations go to the set’s primary. The primary applies the write operation and records the operations on the primary’s operation log or oplog. The oplog is a reproducible sequence of operations to the data set. Secondary members of the set continuously replicate the oplog and apply the operations to themselves in an asynchronous process.

Diagram of default routing of reads and writes to the primary.

For more information on replica sets and write operations, see Replication and Write Concern.

Read Operations to Sharded Clusters

Sharded clusters allow you to partition a data set among a cluster of mongod instances in a way that is nearly transparent to the application. For an overview of sharded clusters, see the Sharding section of this manual.

For a sharded cluster, applications issue operations to one of the mongos instances associated with the cluster.

Diagram of a sharded cluster.

Read operations on sharded clusters are most efficient when directed to a specific shard. Queries to sharded collections should include the collection’s shard key. When a query includes a shard key, the mongos can use cluster metadata from the config database to route the queries to shards.

Read operations to a sharded cluster. Query criteria includes the shard key. The query router ``mongos`` can target the query to the appropriate shard or shards.

If a query does not include the shard key, the mongos must direct the query to all shards in the cluster. These scatter gather queries can be inefficient. On larger clusters, scatter gather queries are unfeasible for routine operations.

Read operations to a sharded cluster. Query criteria does not include the shard key. The query router ``mongos`` must broadcast query to all shards for the collection.

For replica set shards, read operations from secondary members of replica sets may not reflect the current state of the primary. Read preferences that direct read operations to different servers may result in non-monotonic reads.

Changed in version 3.6: Starting in MongoDB 3.6, clients can use causally consistent sessions, which provides various guarantees, including monotonic reads.

For more information on read operations in sharded clusters, see the mongos and Shard Keys sections.

Write Operations on Sharded Clusters

For sharded collections in a sharded cluster, the mongos directs write operations from applications to the shards that are responsible for the specific portion of the data set. The mongos uses the cluster metadata from the config database to route the write operation to the appropriate shards.

Diagram of a sharded cluster.

MongoDB partitions data in a sharded collection into ranges based on the values of the shard key. Then, MongoDB distributes these chunks to shards. The shard key determines the distribution of chunks to shards. This can affect the performance of write operations in the cluster.

Diagram of the shard key value space segmented into smaller ranges or chunks.

Important

Update operations that affect a single document must include the shard key or the _id field. Updates that affect multiple documents are more efficient in some situations if they have the shard key, but can be broadcast to all shards.

If the value of the shard key increases or decreases with every insert, all insert operations target a single shard. As a result, the capacity of a single shard becomes the limit for the insert capacity of the sharded cluster.

For more information, see Sharding and Bulk Write Operations.

Retryable Writes

New in version 3.6.

Starting in MongoDB 3.6 for the WiredTiger and in-memory storage engines, certain write operations on replica sets and sharded clusters are “retryable” to provide handling of transient network errors or replica set elections.

With retryable writes, MongoDB drivers automatically retry these operations upon encountering network errors or encountering a replica set failover during which time the replica set has no primary. Upon encountering a failover, the drivers first waits for serverSelectionTimeoutMS to determine the new primary before retrying.

Note

The writes are retried once.

Retryable Write Operations

The following write operations are retryable when issued with acknowledged write concern; e.g., Write Concern cannot be {w: 0}.

Methods Descriptions
Insert operations.
Single-document update operations.
Single document delete operations.
findAndModify operations. All findAndModify operations are single document operations.

db.collection.bulkWrite() with the following write operations:

Bulk write operations that only consist of the single-document write operations. A retryable bulk operation can include any combination of the specified write operations but cannot include any multi-document write operations, such as updateMany.

Bulk operations for:

Bulk write operations that only consist of the single-document write operations. A retryable bulk operation can include any combination of the specified write operations but cannot include any multi-document write operations, such as update which specifies true for the multi option.

Limitations

Supported Deployment Topologies
Available on replica sets and sharded clusters only.
Supported Storage Engine

Available for the WiredTiger storage engine and in-memory storage engine.

Retryable writes are not available on storage engines that don’t support doc level locking; e.g. MMAPv1.

3.6 MongoDB Drivers

Clients require MongoDB drivers updated for MongoDB 3.6:

  • Java 3.6,
  • Python 3.6
  • C 1.9
  • Node 3.0
  • C# 2.5

To enable retryable writes for the 3.6 drivers, see retryWrites.

Feature Compabitiliby Version
featureCompatibilityVersion must be at least “3.6”. For more information, see setFeatureCompatibilityVersion.
Request Write Acknowledgement
Write Concern must be an acknowledge write concern. For example, write operations issued with {w: 0} are not retryable.
Persistent Network Errors
As the retry attempt is made only once, the retryable feature can help address transient network errors but not persistent network errors.
Failover Period Exceeds serverSelectionTimeoutMS
Upon encountering a failover and receiving the not master error, the drivers wait serverSelectionTimeoutMS seconds to determine the new primary before retrying. The retryable feature does not addresss instance where the failover period exceeds serverSelectionTimeoutMS.

Warning

If the client application becomes temporarily unresponsive for more than the localLogicalSessionTimeoutMinutes after issuing a write operation, there is a chance that when the client applications starts responding (without a restart), the write operation may be retried and applied again.