Configure Operations on Replica Sets

Read and Write Settings Precedence

You can set write concern, read concern, and read preference options at the following levels:

• Client, which sets the default for all operation executions unless overridden

• Transaction

• Database

• Collection

This list also indicates the increasing order of precedence of the option settings. For example, if you set a read concern for a transaction, it will override the read concern settings inherited from the client.

Write concern, read concern, and read preference options allow you to customize the causal consistency and availability of the data in your replica sets. To see a full list of these options, see the following guides in the MongoDB Server manual:

• Read Preference

• Read Concern

• Write Concern

Client Configuration

This example shows how to set the read preference, read concern, and write concern of a MongoClient instance by passing a MongoClientSettings instance to the constructor. The code configures the following settings:

• secondary read preference: Read operations retrieve data from secondary replica set members.

• LOCAL read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members.

• W2 write concern: The primary replica set member and one secondary member must acknowledge the write operation.

MongoClient mongoClient = MongoClients.create(MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("mongodb://localhost:27017/"))
        .readPreference(ReadPreference.secondary())
        .readConcern(ReadConcern.LOCAL)
        .writeConcern(WriteConcern.W2)
        .build());

Alternatively, you can specify the read and write settings in the connection URI, which is passed as a parameter to the MongoClients constructor:

MongoClient uriClient = MongoClients.create("mongodb://localhost:27017/?readPreference=secondary&w=2&readConcernLevel=local");

Transaction Configuration

This example shows how to set the read preference, read concern, and write concern of a transaction by passing a TransactionOptions instance to the startTransaction() method. Transactions run within sessions, which are groupings of related read or write operations that you intend to run sequentially. Before applying the transaction options, create a ClientSession instance to start a session.

The example configures the following settings:

• primary read preference: Read operations retrieve data from the primary replica set member.

• MAJORITY read concern: Read operations return the instance's most recent data that has been written to a majority of replica set members.

• W1 write concern: The primary replica set member must acknowledge the write operation.

TransactionOptions tOptions = TransactionOptions.builder()
        .readPreference(ReadPreference.primary())
        .readConcern(ReadConcern.MAJORITY)
        .writeConcern(WriteConcern.W1)
        .build();
        
try (ClientSession clientSession = client.startSession()) {
    clientSession.startTransaction(tOptions);
    // Specify transaction operations here
}

Database Configuration

This example shows how to set the read preference, read concern, and write concern of a database called test_database by chaining setter methods to the getDatabase() method. The code configures the following settings:

• primaryPreferred read preference: Read operations retrieve data from the primary replica set member, or secondary members if the primary is unavailable.

• AVAILABLE read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members.

• MAJORITY write concern: The majority of all replica set members must acknowledge the write operation.

MongoDatabase database = mongoClient.getDatabase("test_database")
        .withReadPreference(ReadPreference.primaryPreferred())
        .withReadConcern(ReadConcern.AVAILABLE)
        .withWriteConcern(WriteConcern.MAJORITY);

Collection Configuration

This example shows how to set the read preference, read concern, and write concern of a collection called test_collection by chaining setter methods to the getCollection() method. The code configures the following settings:

• secondaryPreferred read preference: Read operations retrieve data from secondary replica set members, or the primary members if no secondary members are available.

• AVAILABLE read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members.

• UNACKNOWLEDGED write concern: Replica set members do not need to acknowledge the write operation.

MongoCollection<Document> collection = database.getCollection("test_collection")
        .withReadPreference(ReadPreference.secondaryPreferred())
        .withReadConcern(ReadConcern.AVAILABLE)
        .withWriteConcern(WriteConcern.UNACKNOWLEDGED);

Sharded Clusters

You can specify a read preference when connecting to a sharded cluster. MongoDB uses sharding to divide datasets by key ranges and distribute data across multiple database instances. A sharded cluster, or the set of nodes in a sharded deployment, includes the following components:

• Shard: A replica set that contains a subset of the sharded data.

• Mongos: A query router that provides an interface between your application and the sharded cluster.

• Config servers: Servers that store the cluster's configuration settings and metadata.

When reading from the replica set shards, mongos applies your specified read preference. The read preference is re-evaluated for each operation.

The following example shows how to connect to a sharded cluster and specify a secondary read preference in your connection string:

MongoClient uriClient = MongoClients.create("mongodb://user:password@mongos1.example.com,mongos2.example.com/?readPreference=secondary");

Tag Sets

In MongoDB Server, you can apply key-value tags to replica set members according to any criteria you choose. You can then use those tags to target one or more members for a read operation.

By default, the Java driver ignores tags when choosing a member to read from. To instruct the Java driver to prefer certain tags, pass the tags as a list to your read preference setter method.

Suppose you are connected to a replica set that contains members hosted at multiple data centers across the United States. You want the driver to prefer reads from secondary replica set members in the following order:

1. Members from the New York data center, tagged with ("dc", "ny")

2. Members from the San Francisco data center, tagged with ("dc", "sf")

3. Any secondary members

This code example passes a list of tags representing the preceding replica set members to the ReadPreference.secondary() setter method. Then, the code passes the read preference information to the withReadPreference() method to set the read order on the database:

TagSet tag1 = new TagSet(new Tag("dc", "ny"));
TagSet tag2 = new TagSet(new Tag("dc", "sf"));
TagSet tag3 = new TagSet();
ReadPreference readPref= ReadPreference.secondary(Arrays.asList(tag1, tag2, tag3));
MongoDatabase database = mongoClient.getDatabase("test_database")
                      .withReadPreference(readPref);

Load Balancing

When connecting to a sharded cluster or a replica set, the Java driver uses load balancing to handle read and write requests. Load balancing allows the driver to distribute these requests across multiple servers, which avoids overwhelming any one server and ensures optimal performance.

When connecting to a sharded cluster, the Java driver determines the closest mongos instance by calculating which one has the lowest network round-trip time. Then, the driver determines the latency window by adding this mongos's average round-trip time to the localThresholdMS value. The driver load balances requests across up to two random mongos instances that fall within the latency window. For each request, the driver chooses the server with the lower operation load by determining its operationCount value.

When connecting to a replica set, the Java driver first selects replica set members according to your read preference. Then, the driver follows the same process as described in the preceding paragraph. After calculating the latency window, the driver selects up to two random replica set members that fall within the window and chooses the member with the lower operationCount value to receive the request.

MongoClient client = MongoClients.create(MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("mongodb://localhost:27017/"))
        .applyToClusterSettings(builder -> builder.localThreshold(35, TimeUnit.MILLISECONDS))
        .build());

String connectionString = "mongodb://localhost:27017/?replicaSet=repl0&localThresholdMS=35";
MongoClient client = MongoClients.create(connectionString);