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 level for a transaction, it will override a read concern level 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.

val mongoClient = MongoClient(MongoClientSettings.builder()
    .applyConnectionString(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 MongoClient constructor:

val uriClient = MongoClient("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 configuring 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.

val clientSessionFuture = mongoClient.startSession().toFuture()
val clientSession = Await.result(clientSessionFuture, Duration(10, TimeUnit.SECONDS))
val tOptions: TransactionOptions = TransactionOptions.builder()
    .readPreference(ReadPreference.primary())
    .readConcern(ReadConcern.MAJORITY)
    .writeConcern(WriteConcern.W1)
    .build()
clientSession.startTransaction(tOptions)

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.

val 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.

val collection = database.getCollection("test_collection")
    .withReadPreference(ReadPreference.secondaryPreferred())
    .withReadConcern(ReadConcern.AVAILABLE)
    .withWriteConcern(WriteConcern.UNACKNOWLEDGED)

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 Scala driver ignores tags when choosing a member to read from. To instruct the Scala 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:

val tag1 = new TagSet(new Tag("dc", "ny"))
val tag2 = new TagSet(new Tag("dc", "sf"))
val tag3 = new TagSet()
val readPreference = ReadPreference.secondary(List(tag1, tag2, tag3).asJava)
val database = mongoClient.getDatabase("test_database")
                          .withReadPreference(readPreference)

Local Threshold

If multiple replica set members match the read preference and tag sets that you specify, the Scala driver reads from the nearest replica set members, chosen according to their ping time.

By default, the driver uses only members whose ping times are within 15 milliseconds of the nearest member for queries. To distribute reads among members with higher latencies, set the localThreshold option in a MongoClientSettings instance or the localThresholdMS option in your connection URI.

The following example specifies a local threshold of 35 milliseconds. Select the MongoClientSettings or Connection URI tab to see corresponding code for each approach:

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

val connectionString = "mongodb://localhost:27017/?replicaSet=repl0&localThresholdMS=35"
val client = MongoClient(connectionString)

In the preceding example, the Scala driver distributes reads among matching members within 35 milliseconds of the closest member's ping time.