Configure Operations on Replica Sets

On this page

Overview

Write Concern
Read Concern
Read Preference
API Documentation

Overview

In this guide, you can learn how to use the write concern, read concern, and read preference configurations to modify the way that MongoDB runs create, read, update, and delete (CRUD) operations on replica sets.

You can set these configurations at the following levels:

Client, which sets the default for all operation executions unless overridden
Transaction
Database
Collection

The preceding list is in increasing order of precedence. For example, if you set read concerns at both the client and the database levels, the read concern specified at the database level overrides the read concern at the client level.

Write Concern

Write concern specifies the level of acknowledgement requested from MongoDB for write operations before the operation successfully returns. Operations that don't specify an explicit write concern inherit the global default write concern setting.

You can set the write concern by using the writeConcern() method on a client or transaction, or by using the withWriteConcern() method on a database or collection.

The writeConcern() and withWriteConcern() methods accept a WriteConcern instance as a parameter. You can specify the write concern by using one of the following values:

WriteConcern.ACKNOWLEDGED: The write operation returns after the operation is written to memory.
WriteConcern.W1: The write operation returns after only the primary node acknowledges the write operation, without waiting for acknowledgement from secondary nodes.
WriteConcern.W2: The write operation returns after the primary node and at least one secondary node acknowledge the write operation.
WriteConcern.W3: The write operation returns after the primary node and at least two secondary nodes acknowledge the write operation.
WriteConcern.MAJORITY: The write operation returns after a majority of the replica set members acknowledge the write operation.
WriteConcern.UNACKNOWLEDGED: The write operation returns after the primary node processes the write operation.
WriteConcern.JOURNALED: The write operation returns after the primary node writes the data to the on-disk journal.

The following example sets the write concern to "majority" for an instance of MongoClient:

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("<your connection string>"))
        .writeConcern(WriteConcern.MAJORITY)
        .build();
MongoClient client = MongoClients.create(settings);

The following example sets the write concern to "majority" for a collection:

MongoCollection<Document> collection = database.getCollection("<collection name>");
collection = collection.withWriteConcern(WriteConcern.MAJORITY);

Note

Collections and Databases are Immutable

MongoDatabase and MongoCollection instances are immutable. When you set the write concern on a database or collection, the method returns a new instance and does not affect the original instance.

For more information about write concern, see Write Concern in the MongoDB Server manual.

Read Concern

Read concern specifies the following behaviors:

Level of causal consistency across replica sets
Isolation guarantees maintained during a query

You can specify the read concern by using the readConcern() method on a client or transaction, or by using the withReadConcern() method on a database or collection. The readConcern() and withReadConcern() methods accept a single parameter that specifies the read concern level.

You can set the following read concern levels:

ReadConcern.LOCAL: 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.
ReadConern.AVAILABLE: 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. ReadConcern.AVAILABLE is not available for use with causally consistent sessions and transactions.
ReadConcern.MAJORITY: The query returns data that has been acknowledged by a majority of the replica set members.
ReadConcern.LINEARIZABLE: The query returns data that reflects all successful writes that completed prior to the start of the read operation. ReadConcern.LINEARIZABLE is not available for use with causally consistent sessions and transactions.
ReadConcern.SNAPSHOT: The query returns majority-committed data as it appears across shards, from a specific single point in the recent past.

For more information about the read concern levels, see Read Concern Levels in the MongoDB Server manual.

The following example sets the read concern to ReadConcern.MAJORITY for an instance of MongoClient:

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("<your connection string>"))
        .readConcern(ReadConcern.MAJORITY)
        .build();
MongoClient client = MongoClients.create(settings);

The following example sets the read concern to ReadConcern.MAJORITY for a collection:

MongoCollection<Document> collection = database.getCollection("<collection name>");
collection = collection.withReadConcern(ReadConcern.MAJORITY);

To learn more about read concern, see Read Concern in the MongoDB Server manual.

Read Preference

Read preference determines which member of a replica set MongoDB reads when running a query. You can set the read preference by using the readPreference() method on a client or transaction, or by using the withReadPreference() method on a database or collection.

The readPreference() and withReadPreference() methods accept a read preference mode as a parameter. You can set the read preference mode to one of the following values:

ReadPreference.primary(): The query returns data from the primary node.
ReadPreference.primaryPreferred(): The query returns data from the primary node if available. Otherwise, the query returns data from a secondary node.
ReadPreference.secondary(): The query returns data from a secondary node.
ReadPreference.secondaryPreferred(): The query returns data from a secondary node if available, Otherwise, the query returns data from the primary node.
ReadPreference.nearest(): The query returns data from the node with the lowest network latency.

The following example sets the read preference to ReadPreference.secondary() for an instance of MongoClient:

MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("<your connection string>"))
        .readPreference(ReadPreference.secondary())
        .build();

The following example sets the read preference to ReadPreference.secondary() for a collection:

MongoCollection<Document> collection = database.getCollection("<collection name>");
collection = collection.withReadPreference(ReadPreference.secondary());

For more information about read preference, see Read Preference in the MongoDB Server manual.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

In-Use Encryption

Specialized Data Formats