From 590e6f0e98a98982a66ba303ca9e6ab9e0387c8b Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 4 Mar 2025 12:02:17 -0500 Subject: [PATCH 1/9] DOCSP-47048: Configure replica set operations --- source/connection.txt | 1 + source/connection/read-write-config.txt | 330 +++++++++++++++++++++++ source/includes/connect/ReplicaSets.java | 107 ++++++++ 3 files changed, 438 insertions(+) create mode 100644 source/connection/read-write-config.txt create mode 100644 source/includes/connect/ReplicaSets.java diff --git a/source/connection.txt b/source/connection.txt index c2b4dd595..bb2e28b96 100644 --- a/source/connection.txt +++ b/source/connection.txt @@ -11,6 +11,7 @@ Connection Guide MongoClient Settings Stable API Network Compression + Operations on Replica Sets JNDI Datasource Connection Troubleshooting AWS Lambda diff --git a/source/connection/read-write-config.txt b/source/connection/read-write-config.txt new file mode 100644 index 000000000..fa0d8c0c3 --- /dev/null +++ b/source/connection/read-write-config.txt @@ -0,0 +1,330 @@ +.. _java-configure-replica-sets: + +==================================== +Configure Operations on Replica Sets +==================================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: customize, preferences, replica set, consistency + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to configure **write concern**, **read concern**, +and **read preference** options to modify the way that the {+driver-short+} runs +read and write 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 {+mdb-server+} manual: + +- :manual:`Read Preference ` +- :manual:`Read Concern ` +- :manual:`Write Concern ` + +.. _java-read-write-config: + +Configure Read and Write Operations +----------------------------------- + +You can control how the driver routes read operations among replica set members +by setting a read preference. You can also control how the driver waits for +acknowledgment of read and write operations on a replica set by setting read and +write concerns. + +The following sections show how to configure these read and write settings +at various levels. + +.. _java-read-write-client: + +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. + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-client-settings + :end-before: end-client-settings + +Alternatively, you can specify the read and write settings in the connection +URI, which is passed as a parameter to the ``MongoClient`` constructor: + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-client-settings-uri + :end-before: end-client-settings-uri + +.. _java-read-write-transaction: + +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. + +.. tip:: + + To learn more about sessions, see :manual:`Server Sessions ` + in the {+mdb-server+} manual. + +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. + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-transaction-settings + :end-before: end-transaction-settings + +.. _java-read-write-database: + +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. + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-database-settings + :end-before: end-database-settings + +.. _java-read-write-collection: + +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. + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-collection-settings + :end-before: end-collection-settings + +.. _java-read-write-advanced: + +Advanced Read Configurations +---------------------------- + +The following sections describe ways to further customize how the {+driver-short+} +routes read operations. + +.. _java-sharded-clusters: + +Sharded Clusters +~~~~~~~~~~~~~~~~ + +You can specify a read preference when connecting to a sharded cluster. +MongoDB uses sharding to distribute large amounts of data across +multiple servers. 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. + +.. tip:: + + To learn more about sharded clusters, see :manual:`Sharding ` + in the {+mdb-server+} manual. + +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: + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-sharded-cluster-uri + :end-before: end-sharded-cluster-uri + +Load Balancing +`````````````` + +If there is more than one mongos instance in the connection seed list, the +{+driver-short+} uses **load balancing**. Load balancing allows the driver to +distribute read and write requests across multiple servers, which avoids overwhelming +one server in the sharded cluster and ensures optimal performance. + +To distribute database requests, the {+driver-short+} determines the closest mongos +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 data randomly across the mongos +instances that fall within the latency window. + +.. tip:: + + To learn more about load balancing, see :manual:`Sharded Cluster Balancer ` + in the {+mdb-server+} manual. + +.. _java-tag-sets: + +Tag Sets +~~~~~~~~ + +In {+mdb-server+}, you can apply key-value :manual:`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 {+driver-short+} ignores tags when choosing a member +to read from. To instruct the {+driver-short+} 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")`` +#. Members from the San Francisco data center, tagged with ``("dc", "sf")`` +#. 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: + +.. literalinclude:: /includes/connect/ReplicaSets.java + :language: java + :dedent: + :start-after: start-tag-set + :end-before: end-tag-set + +.. _java-local-threshold: + +Local Threshold +~~~~~~~~~~~~~~~ + +If multiple replica set members match the read preference and tag sets that you specify, +the {+driver-short+} 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 :guilabel:`MongoClientSettings` or :guilabel:`Connection URI` tab to see +corresponding code for each approach: + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: settings + + .. literalinclude:: /includes/connect/ReplicaSets.java + :language: rust + :dedent: + :start-after: start-local-threshold-settings + :end-before: end-local-threshold-settings + + + .. tab:: Connection URI + :tabid: uri + + .. literalinclude:: /includes/connect/ReplicaSets.java + :language: rust + :dedent: + :start-after: start-local-threshold-uri + :end-before: end-local-threshold-uri + +In the preceding example, the {+driver-short+} distributes reads among matching members +within 35 milliseconds of the closest member's ping time. + +.. note:: + + The {+driver-short+} ignores the ``localThresholdMS`` option when communicating with a + replica set through a ``mongos`` instance. In this case, use the + :manual:`localThreshold ` + command-line option. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ +- `TransactionOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/TransactionOptions.html>`_ +- `startTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#startTransaction()>`_ +- `MongoDatabase <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html>`__ +- `MongoCollection <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html>`__ +- `TagSet <{+api+}/apidocs/mongodb-driver-core/com/mongodb/TagSet.html>`_ \ No newline at end of file diff --git a/source/includes/connect/ReplicaSets.java b/source/includes/connect/ReplicaSets.java new file mode 100644 index 000000000..ab32f3f97 --- /dev/null +++ b/source/includes/connect/ReplicaSets.java @@ -0,0 +1,107 @@ +import com.mongodb.ConnectionString; +import com.mongodb.MongoClientSettings; +import com.mongodb.ReadConcern; +import com.mongodb.ReadPreference; +import com.mongodb.Tag; +import com.mongodb.TagSet; +import com.mongodb.TransactionOptions; +import com.mongodb.WriteConcern; +import com.mongodb.client.MongoClient; +import com.mongodb.client.MongoClients; +import com.mongodb.client.MongoCollection; +import com.mongodb.client.MongoDatabase; + +import com.mongodb.client.ClientSession; + +import java.util.Arrays; +import java.util.concurrent.TimeUnit; + +public class ReplicaSets { + + public static void main(String[] args) throws InterruptedException { + + // Uses the settings builder methods to set read and write settings for the client + // start-client-settings + MongoClient mongoClient = MongoClients.create(MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("mongodb://localhost:27017/")) + .readPreference(ReadPreference.secondary()) + .readConcern(ReadConcern.LOCAL) + .writeConcern(WriteConcern.W2) + .build()); + // end-client-settings + + // Uses connection URI parameters to set read and write settings for the client + // start-client-settings-uri + MongoClient uriClient = MongoClients.create("mongodb://localhost:27017/?readPreference=secondary&w=2&readConcernLevel=local"); + // end-client-settings-uri + + // Sets read and write settings for the transaction + // start-transaction-settings + 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 + } + // end-transaction-settings + + // Sets read and write settings for the "test_database" database + // start-database-settings + MongoDatabase database = mongoClient.getDatabase("test_database") + .withReadPreference(ReadPreference.primaryPreferred()) + .withReadConcern(ReadConcern.AVAILABLE) + .withWriteConcern(WriteConcern.MAJORITY); + // end-database-settings + + // Sets read and write settings for the "test_collection" collection + // start-collection-settings + MongoCollection collection = database.getCollection("test_collection") + .withReadPreference(ReadPreference.secondaryPreferred()) + .withReadConcern(ReadConcern.AVAILABLE) + .withWriteConcern(WriteConcern.UNACKNOWLEDGED); + // end-collection-settings + + // Uses connection URI parameters to set a sharded cluster read preference + // start-sharded-cluster-uri + MongoClient uriClient = MongoClients.create("mongodb://user:password@mongos1.example.com,mongos2.example.com/?readPreference=secondary"); + // end-sharded-cluster-uri + + // Instructs the driver to prefer reads from secondary replica set members + // located in New York, followed by a secondary in San Francisco, and + // lastly fall back to any secondary. + // start-tag-set + 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)); + + database = mongoClient.getDatabase("test_database") + .withReadPreference(readPref); + // end-tag-set + + // Instructs the library to distribute reads between members within 35 milliseconds + // of the closest member's ping time using client settings + // start-local-threshold-uri + String connectionString = "mongodb://localhost:27017/?replicaSet=repl0&localThresholdMS=35"; + MongoClient client = MongoClients.create(connectionString); + // end-local-threshold-uri + + // Instructs the library to distribute reads between members within 35 milliseconds + // of the closest member's ping time using a URI option + // start-local-threshold-settings + MongoClient timedClient = MongoClients.create(MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("mongodb://localhost:27017/")) + .applyToClusterSettings(builder -> builder.localThreshold(35, TimeUnit.MILLISECONDS)) + .build()); + // end-local-threshold-settings + + // Close the MongoClient connection + mongoClient.close(); + } +} \ No newline at end of file From bf85faaa312451ffda6f5b50469083f1b9022c6b Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 4 Mar 2025 13:18:33 -0500 Subject: [PATCH 2/9] move drawers --- source/connection.txt | 1 - source/crud.txt | 1 + .../{connection => crud}/read-write-config.txt | 18 +++++++++--------- .../code-snippets}/ReplicaSets.java | 0 4 files changed, 10 insertions(+), 10 deletions(-) rename source/{connection => crud}/read-write-config.txt (94%) rename source/includes/{connect => fundamentals/code-snippets}/ReplicaSets.java (100%) diff --git a/source/connection.txt b/source/connection.txt index bb2e28b96..c2b4dd595 100644 --- a/source/connection.txt +++ b/source/connection.txt @@ -11,7 +11,6 @@ Connection Guide MongoClient Settings Stable API Network Compression - Operations on Replica Sets JNDI Datasource Connection Troubleshooting AWS Lambda diff --git a/source/crud.txt b/source/crud.txt index 3fc0b0fde..409349176 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -12,6 +12,7 @@ CRUD Operations Query Compound Operations Transactions + Operations on Replica Sets Builders Aggregation Aggregation Expressions diff --git a/source/connection/read-write-config.txt b/source/crud/read-write-config.txt similarity index 94% rename from source/connection/read-write-config.txt rename to source/crud/read-write-config.txt index fa0d8c0c3..b395d82bb 100644 --- a/source/connection/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -77,7 +77,7 @@ instance to the constructor. The code configures the following settings: - ``W2`` write concern: The primary replica set member and one secondary member must acknowledge the write operation. -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-client-settings @@ -86,7 +86,7 @@ instance to the constructor. The code configures the following settings: Alternatively, you can specify the read and write settings in the connection URI, which is passed as a parameter to the ``MongoClient`` constructor: -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-client-settings-uri @@ -118,7 +118,7 @@ The example configures the following settings: - ``W1`` write concern: The primary replica set member must acknowledge the write operation. -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-transaction-settings @@ -142,7 +142,7 @@ settings: - ``MAJORITY`` write concern: The majority of all replica set members must acknowledge the write operation. -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-database-settings @@ -167,7 +167,7 @@ settings: - ``UNACKNOWLEDGED`` write concern: Replica set members do not need to acknowledge the write operation. -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-collection-settings @@ -208,7 +208,7 @@ 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: -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-sharded-cluster-uri @@ -260,7 +260,7 @@ 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: -.. literalinclude:: /includes/connect/ReplicaSets.java +.. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java :dedent: :start-after: start-tag-set @@ -289,7 +289,7 @@ corresponding code for each approach: .. tab:: MongoClientSettings :tabid: settings - .. literalinclude:: /includes/connect/ReplicaSets.java + .. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: rust :dedent: :start-after: start-local-threshold-settings @@ -299,7 +299,7 @@ corresponding code for each approach: .. tab:: Connection URI :tabid: uri - .. literalinclude:: /includes/connect/ReplicaSets.java + .. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: rust :dedent: :start-after: start-local-threshold-uri diff --git a/source/includes/connect/ReplicaSets.java b/source/includes/fundamentals/code-snippets/ReplicaSets.java similarity index 100% rename from source/includes/connect/ReplicaSets.java rename to source/includes/fundamentals/code-snippets/ReplicaSets.java From 4e591ed8a001133fd0fb5e6aed42f20de28652d5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 4 Mar 2025 13:29:39 -0500 Subject: [PATCH 3/9] code edits --- source/includes/fundamentals/code-snippets/ReplicaSets.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/fundamentals/code-snippets/ReplicaSets.java b/source/includes/fundamentals/code-snippets/ReplicaSets.java index ab32f3f97..b7b9e866d 100644 --- a/source/includes/fundamentals/code-snippets/ReplicaSets.java +++ b/source/includes/fundamentals/code-snippets/ReplicaSets.java @@ -18,7 +18,7 @@ public class ReplicaSets { - public static void main(String[] args) throws InterruptedException { + public static void main(String[] args) { // Uses the settings builder methods to set read and write settings for the client // start-client-settings @@ -81,7 +81,7 @@ public static void main(String[] args) throws InterruptedException { ReadPreference readPref= ReadPreference.secondary(Arrays.asList(tag1, tag2, tag3)); - database = mongoClient.getDatabase("test_database") + MongoDatabase database = mongoClient.getDatabase("test_database") .withReadPreference(readPref); // end-tag-set @@ -95,7 +95,7 @@ public static void main(String[] args) throws InterruptedException { // Instructs the library to distribute reads between members within 35 milliseconds // of the closest member's ping time using a URI option // start-local-threshold-settings - MongoClient timedClient = MongoClients.create(MongoClientSettings.builder() + MongoClient client = MongoClients.create(MongoClientSettings.builder() .applyConnectionString(new ConnectionString("mongodb://localhost:27017/")) .applyToClusterSettings(builder -> builder.localThreshold(35, TimeUnit.MILLISECONDS)) .build()); From f2cbe21a4ac41bf0d0f373d8e90f0c76ffc02582 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 4 Mar 2025 13:39:38 -0500 Subject: [PATCH 4/9] edits --- source/crud.txt | 2 +- source/crud/read-write-config.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud.txt b/source/crud.txt index 409349176..b69799d1d 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -12,7 +12,7 @@ CRUD Operations Query Compound Operations Transactions - Operations on Replica Sets + Operations on Replica Sets Builders Aggregation Aggregation Expressions diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index b395d82bb..2c039933d 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -84,7 +84,7 @@ instance to the constructor. The code configures the following settings: :end-before: end-client-settings Alternatively, you can specify the read and write settings in the connection -URI, which is passed as a parameter to the ``MongoClient`` constructor: +URI, which is passed as a parameter to the ``MongoClients`` constructor: .. literalinclude:: /includes/fundamentals/code-snippets/ReplicaSets.java :language: java From 0d8a139d5aa1891193512b59fa9c2492380911f4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 4 Mar 2025 16:45:08 -0500 Subject: [PATCH 5/9] SA feedback --- source/crud/read-write-config.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index 2c039933d..5fc244aae 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -36,8 +36,8 @@ levels: - 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. +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 From ed26f8e6c4e957384bcec14642bcdaaf59436b52 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 4 Mar 2025 16:49:31 -0500 Subject: [PATCH 6/9] wording --- source/crud/read-write-config.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index 5fc244aae..0b0d43e50 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -187,8 +187,8 @@ Sharded Clusters ~~~~~~~~~~~~~~~~ You can specify a read preference when connecting to a sharded cluster. -MongoDB uses sharding to distribute large amounts of data across -multiple servers. A sharded cluster, or the set of nodes in a sharded deployment, +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. From f7a237a6b01ec0ef86960a515ffa7ad23670b967 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Mar 2025 11:52:03 -0400 Subject: [PATCH 7/9] tech feedback --- source/crud/read-write-config.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index 0b0d43e50..b92ece555 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -225,13 +225,18 @@ one server in the sharded cluster and ensures optimal performance. To distribute database requests, the {+driver-short+} determines the closest mongos 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 data randomly across the mongos -instances that fall within the latency window. +:ref:`localThresholdMS value `. The driver load balances requests +across up to two 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. .. tip:: - To learn more about load balancing, see :manual:`Sharded Cluster Balancer ` - in the {+mdb-server+} manual. + To learn more about load balancing, see :manual:`Sharded Cluster Balancer + ` in the {+mdb-server+} manual. + + To learn how to customize the driver's server selection behavior, see + :ref:`mcs-cluster-settings` in the Specify MongoClient Settings guide. .. _java-tag-sets: From bd9be88f7d55aeaa0bf03f4ff686f5da7e319da6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 26 Mar 2025 10:49:19 -0400 Subject: [PATCH 8/9] tech review 2 --- source/crud/read-write-config.txt | 91 +++++++++++++++++-------------- 1 file changed, 49 insertions(+), 42 deletions(-) diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index b92ece555..a0b1fec4d 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -214,30 +214,6 @@ The following example shows how to connect to a sharded cluster and specify a :start-after: start-sharded-cluster-uri :end-before: end-sharded-cluster-uri -Load Balancing -`````````````` - -If there is more than one mongos instance in the connection seed list, the -{+driver-short+} uses **load balancing**. Load balancing allows the driver to -distribute read and write requests across multiple servers, which avoids overwhelming -one server in the sharded cluster and ensures optimal performance. - -To distribute database requests, the {+driver-short+} determines the closest mongos -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 -:ref:`localThresholdMS value `. The driver load balances requests -across up to two 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. - -.. tip:: - - To learn more about load balancing, see :manual:`Sharded Cluster Balancer - ` in the {+mdb-server+} manual. - - To learn how to customize the driver's server selection behavior, see - :ref:`mcs-cluster-settings` in the Specify MongoClient Settings guide. - .. _java-tag-sets: Tag Sets @@ -271,23 +247,61 @@ to set the read order on the database: :start-after: start-tag-set :end-before: end-tag-set +Load Balancing +~~~~~~~~~~~~~~ + +When connecting to a sharded cluster or a replica set, the {+driver-short+} 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 {+driver-short+} 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 +:ref:`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 {+driver-short+} 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. + +.. tip:: + + To learn more about load balancing, see :manual:`Sharded Cluster Balancer + ` in the {+mdb-server+} manual. + + To learn how to customize the driver's server selection behavior, see + :ref:`mcs-cluster-settings` in the Specify MongoClient Settings guide. + .. _java-local-threshold: Local Threshold -~~~~~~~~~~~~~~~ +``````````````` -If multiple replica set members match the read preference and tag sets that you specify, -the {+driver-short+} reads from the nearest replica set members, chosen according to -their ping time. +The {+driver-short+} uses the local threshold value to calculate the +latency window for server selection. This value determines the servers +that are eligible to receive read and write requests. -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. +By default, the driver uses only mongos instances or replica set members whose +ping times are within 15 milliseconds of the nearest server. To +distribute reads among servers 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 :guilabel:`MongoClientSettings` or :guilabel:`Connection URI` tab to see -corresponding code for each approach: +.. note:: + + When communicating with a mongos instance, the {+driver-short+} ignores the + ``localThresholdMS`` URI option. In this case, use the + :manual:`localThreshold ` + command-line option. + +The following example connects to a replica set and specifies a local threshold +of 35 milliseconds. Select the :guilabel:`MongoClientSettings` or :guilabel:`Connection URI` +tab to see corresponding code for each approach: .. tabs:: @@ -313,13 +327,6 @@ corresponding code for each approach: In the preceding example, the {+driver-short+} distributes reads among matching members within 35 milliseconds of the closest member's ping time. -.. note:: - - The {+driver-short+} ignores the ``localThresholdMS`` option when communicating with a - replica set through a ``mongos`` instance. In this case, use the - :manual:`localThreshold ` - command-line option. - API Documentation ----------------- From 00d5ea3b9f83780ee0ccddb284f869e16492b519 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 26 Mar 2025 16:11:33 -0400 Subject: [PATCH 9/9] tech review 3 --- source/crud/read-write-config.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index a0b1fec4d..b4172ed9c 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -294,8 +294,8 @@ in your connection URI. .. note:: - When communicating with a mongos instance, the {+driver-short+} ignores the - ``localThresholdMS`` URI option. In this case, use the + When selecting replica set members from a single mongos instance, the + {+driver-short+} ignores the ``localThresholdMS`` option. In this case, use the :manual:`localThreshold ` command-line option.