/ /

Configure Client-level CRUD Settings

Overview

In this guide, you can learn about how to use the Java driver to configure CRUD operations for MongoClient instances.

Read preferences, read concerns, and write concerns control how the driver routes read operations and waits for acknowledgment for read and write operations when connected to a MongoDB replica set. Read preferences and read concerns apply to all read operations; write concerns apply to all write operations.

For more information, see the server documentation on read preferences, read concerns, and write concerns.

MongoDatabase and MongoCollection instances inherit their preferences and concerns from the MongoClient that accesses them. However, you can apply custom settings to your databases and collections. For more information, see the Configure Custom CRUD Settings page.

You can specify client-level CRUD settings by using either a connection string or by passing a MongoClientSettings object to the MongoClients constructor. Select the Connection String or MongoClientSettings tab to see the options available:

Include the following parameters in your connection string to modify the driver's read or write behavior:

Option Name	Type	Description
`journal`	boolean	Specifies that the driver must wait for the connected MongoDB instance to group commit to the journal file on disk for all writes. Default: `false`
`w`	string or integer	Specifies the write concern. For more information about values, see the MongoDB Server documentation for the w option. Default: `1`
`wtimeoutMS`	integer	Specifies a time limit, in milliseconds, for the write concern. For more information, see the MongoDB Server documentation for the wtimeoutMS option. A value of `0` instructs the driver to never time out write operations. Default: `0`
`readPreference`	string	Specifies the read preference. For more information about values, see the MongoDB Server documentation for the readPreference option. Default: `primary`
`readPreferenceTags`	string	Specifies the read preference tags. For more information about values, see the MongoDB Server documentation for the readPreferenceTags option. Default: `null`
`maxStalenessSeconds`	integer	Specifies, in seconds, how stale a secondary can be before the driver stops communicating with that secondary. The minimum value is either 90 seconds or the heartbeat frequency plus 10 seconds, whichever is greater. For more information, see the MongoDB Server documentation for the maxStalenessSeconds option. Not providing a parameter or explicitly specifying `-1` indicates that there must be no staleness check for secondaries. Default: `-1`
`uuidRepresentation`	string	Specifies the UUID representation to use for read and write operations. For more information, see the driver documentation for the MongoClientSettings.getUuidRepresentation() method. Default: `unspecified`
`retryWrites`	boolean	Specifies that the driver must retry supported write operations if they are unable to complete due to a network error. Default: `true`
`retryReads`	boolean	Specifies that the driver must retry supported read operations if they are unable to complete due to a network error. Default: `true`
`maxAdaptiveRetries`	integer	Sets the maximum number of times the driver retries a command that fails with a retryable overload error (that is, an error that carries both the `SystemOverloadedError` and `RetryableError` labels). This option applies to write commands only when `retryWrites` is set to `true` and read commands only when `retryReads` is set to `true`. Setting the value to `0` disables retry attempts for retryable overload errors. Default: `null`. When this option is not set, the driver typically applies the value `2`.
`enableOverloadRetargeting`	boolean	Sets whether the driver may deprioritize servers during server selection for subsequent retry attempts if they previously returned overload errors. This option applies to reads when `retryReads` is set to `true` and to writes when `retryWrites` is set to `true`. This option does not apply to sharded clusters. Default: `false`

The following example sets the read preference to read from the nearest replica set member:

ConnectionString connectionString = "mongodb://<host>:<port>/?readPreference=nearest"
MongoClient mongoClient = MongoClients.create(connectionString)

For more information about these parameters, see the ConnectionString API documentation.

Chain the following methods to your MongoClientSettings constructor to modify the driver's read/write behavior:

`enableOverloadRetargeting()`	Sets whether the driver may deprioritize servers during server selection for subsequent retry attempts if they previously returned overload errors. Applies to reads when `retryReads()` is set to `true` and to writes when `retryWrites()` is set to `true`. Does not apply to sharded clusters. Default: `false`
`maxAdaptiveRetries()`	Sets the maximum number of times the driver retries a command that fails with a retryable overload error (that is, an error that carries both the `SystemOverloadedError` and `RetryableError` labels). Applies to write commands only when `retryWrites()` is set to `true` and read commands only when `retryReads()` is set to `true`. Setting the value to `0` disables retry attempts for retryable overload errors. Default: `null`. When this option is not set, the driver typically applies the value `2`.
`readConcern()`	Sets the read concern. Server manual page API documentation
`readPreference()`	Sets the read preference Default: `primary`
`retryReads()`	Whether the driver performs retry reads if a network error occurs. Default: `true`
`retryWrites()`	Whether the driver performs retry writes if a network error occurs. Default: `true`
`uuidRepresentation()`	Sets the UUID representation to use when encoding instances of UUID and decoding BSON binary values with subtype of 3.
`writeConcern()`	Sets the write concern. Default: `WriteConcern#ACKNOWLEDGED`. \| For more information about the default value, see Implicit Default Write Concern.

The following example sets the read preference to read from the nearest replica set member:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
                .readPreference(ReadPreference.nearest())
                .build());

For more information about these methods, see the MongoClientSettings.Builder API documentation.

Note

Load Shedding in Intelligent Workload Management (IWM)

If errors with SystemOverloadedError or RetryableError labels are causing failures in your application or appearing in your application logs, Load Shedding may be active on your cluster and your driver may not be upgraded to a version that supports it. We recommend upgrading your MongoDB Java Driver to version 5.8 or later. If you continue to see these errors after upgrading, you can address them through server-side changes, such as reviewing your Load Shedding configuration, or through application-side changes, such as implementing custom error handling or client-side request throttling. Depending on your situation, application-side changes may be preferable or necessary.

Load Shedding is a feature of IWM, and helps manage server load by rejecting excess operations during sustained overload. This feature is available on MongoDB 9.0 and later.

For more information about IWM or handling overload errors, see the Intelligent Workload Management page or Overload Errors page in the Atlas documentation.

Back

Socket Settings

Network Compression