DOCSP-45184-ruby-replica-sets

source/includes/usage-examples/read-write-pref.rb

@@ -0,0 +1,80 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'mongo'
+end
+
+uri = '<connection string>'
+
+Mongo::Client.new(uri) do |client|
+    # Access the database and collection
+
+    # start-write-concern
+    client = Mongo::Client.new(['IP_ADDRESS_001:27017'], database: 'myDB')
+    myDB = client.database
+    myCollection = myDB[:myCollection]
+
+    myCollection.insert_one(
+      { name: "anotherDocumentName" },
+      write: {
+        w: 2,
+        wtimeout: 5000
+      }
+    )
+    # end-write-concern
+
+    # start-write-concern-2
+    myDoc = { name: "New Document" }
+    new_write_concern = Mongo::WriteConcern.get(myDB.write_concern)
+    myDB[:myCollection].with(write: new_write_concern).insert_one(myDoc)
+    # end-write-concern-2
+
+    # start-read-concern
+    pipeline = [
+    { "$match" => { category: "KITCHENWARE" } },
+    { "$unset" => ["_id", "category"] }
+    ]
+    result = myCollection.aggregate(pipeline,
+    read: { read_concern: { level: :available } })
+    # end-read-concern
+
+    # start-change-read-concern
+    client = Mongo::Client.new(['IP_ADDRESS_001:27017'], 
+    database: 'mydb', 
+    read_concern: { level: :local })
+    myDB = client.database
+    # end-change-read-concern
+
+    # start-read-preference
+    transaction_options = {
+      read: { mode: :primary },
+      read_concern: { level: :local },
+      write_concern: { w: :majority }
+    }
+    session = client.start_session
+    session.start_transaction(transaction_options)
+    session.commit_transaction
+    # ...
+    rescue => e
+        session.abort_transaction
+        puts "Transaction aborted due to an error: #{e.message}"
+      ensure
+        session.end_session
+      end
+    # end-read-preference
+
+    # start-read-preference-cluster
+    uri = 'mongodb+srv://<user>:<password>@<cluster-url>'
+    options = {
+      read: {
+        mode: :secondary,
+        max_staleness: 120
+      }
+    }
+    client = Mongo::Client.new(uri, options)
+    myDB = client.database
+    # end-read-preference-cluster
+
+
+

source/read-write-pref.txt

@@ -0,0 +1,233 @@
+.. _ruby-crud-write-read-pref:
+
+===============================
+CRUD Operations on Replica Sets
+===============================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta:: 
+   :keywords: ruby, 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 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 write concern, read concern, and read preference options at the following
+levels:
+
+- Client, which sets the *default for all operation executions* unless overridden
+- Session
+- Transaction
+- Database
+- Collection
+
+The preceding 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 set for the client.
+
+These options allow you to customize the causal consistency and availability of the data
+in your replica sets.
+
+Write Concern
+-------------
+
+The write concern specifies the level of acknowledgement requested from MongoDB for 
+write operations, such as an insert or update, before the operation successfully returns.
+Operations that do not specify an explicit write concern inherit the global default write
+concern settings.
+
+For more information, see :manual:`Write Concern </reference/write-concern/>` in the
+{+mdb-server+} manual. For detailed API documentation, see the `Write Concern API documentation
+<https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Client.html#write_concern-instance_method>`__.
+
+The following table describes the ``write_concern`` parameters:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 25 50
+
+   * - Parameter
+     - Type
+     - Description
+
+   * - ``w`` *(optional)*
+     - integer or string
+     - Requests acknowledgment that the write operation has propagated to a specified
+       number of ``mongod`` instances or to ``mongod`` instances that are labelled
+       with specified tags.
+
+   * - ``wtimeoutMS`` *(optional)*
+     - integer
+     - Specifies a time limit to prevent write operations from blocking indefinitely.
+
+   * - ``journal`` *(optional)*
+     - boolean
+     - Requests acknowledgment that the write operation has been written to the 
+       on-disk journal.
+
+Example: Set the Write Concern for a Single Write Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code creates a new document and specifies the ``w`` and ``wtimeout``
+write concern settings:
+
+.. literalinclude:: /includes/usage-examples/read-write-pref.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-write-concern
+   :end-before: end-write-concern
+
+Example: Retrieve and Apply an Existing Write Concern
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This code uses the ``new_write_concern`` method to construct a ``write_concern`` from
+the options of an existing database reference, ``myDB``.  
+Then the new write concern is applied to an inserted document.
+
+.. literalinclude:: /includes/usage-examples/read-write-pref.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-write-concern-2
+   :end-before: end-write-concern-2
+
+.. note::
+
+    ``myDB`` can be replaced with a reference to any entity that accepts a write concern option.
+
+Read Concern
+------------
+
+The read concern specifies the following behaviors:
+
+- Level of :manual:`causal consistency </core/causal-consistency-read-write-concerns/>`
+  across replica sets
+
+- `Isolation guarantees <https://www.mongodb.com/docs/current/core/read-isolation-consistency-recency/>`__ 
+  maintained during a query
+
+You can specify the read concern setting by using the ``level`` parameter. The default
+read concern level is ``local``. This means that the client returns the data from the
+replica set member that the client is connected to, with no guarantee that the data has
+been written to all replica set members.
+
+.. note::
+    Lower read concern level requirements may reduce latency. 
+
+For more information about read concerns or read concern levels, see 
+:manual:`Read Concern </reference/read-concern/>` in the {+mdb-server+}  manual. For more
+detail on the ``read_concern`` type and definitions of the read concern levels, see
+`Read Concern <https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Client.html#read_concern-instance_method>`__ 
+in the API documentation.
+
+Example: Set the Read Concern Level of an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code sets the read concern level of an aggregation to `"available"`:
+
+.. literalinclude:: /includes/usage-examples/read-write-pref.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-read-concern
+   :end-before: end-read-concern
+
+For more information about aggregates, see the `ruby-aggregation <https://www.mongodb.com/docs/ruby-driver/upcoming/reference/aggregation/>`_ 
+page.
+
+Example: Change the Read Concern of a Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code changes the read concern level of a database to ``"local"``:
+
+.. literalinclude:: /includes/usage-examples/read-write-pref.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-change-read-concern
+   :end-before: end-change-read-concern
+
+Read Preference
+---------------
+
+The read preference determines which member of a replica set MongoDB reads when running a
+query.
+
+For more detailed API documentation, see the `Read Preference API
+documentation <https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection/View/Readable.html#read_preference-instance_method>`__.
+
+The following table shows how to customize how the server evaluates members:
+
+.. list-table::
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+
+   * - ``mode``
+     - ``Symbol``
+     - Specifies a requirement or preference for which replica set
+       member the server reads from. The default mode, ``:primary``, specifies that
+       operations read from the primary member of the replica set.
+
+   * - ``tags`` *(optional)*
+     - ``Array<Hash>``
+     - Assigns tags to secondary replica set members to customize how the server evaluates
+       them. Tags cannot be used with the ``:primary`` read preference mode setting.
+
+   * - ``options`` *(optional)*
+     - ``Hash``
+     - Sets various options, including :manual:`hedge </core/read-preference-hedge-option/>`
+       and :manual:`maxStalenessSeconds </core/read-preference-staleness/>` that can be
+       applied to your read preference.
+
+Example: Set Read Preference and Concerns for a Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code sets the read preference, read concern, and write concern for
+the operations in a transaction:
+
+.. literalinclude:: /includes/usage-examples/read-write-pref.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-read-preference
+   :end-before: end-read-preference
+
+For more information about transactions, see :ref:`ruby-transactions`_.
+
+Example: Set the Read Preference of a Cluster in the Connection String
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This code example creates a ``MongoClient`` that uses the ``secondary`` read 
+preference mode when performing queries on a cluster:
+
+.. literalinclude:: /includes/usage-examples/read-write-pref.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-read-preference-cluster
+   :end-before: end-read-preference-cluster
+
+The preceding example also sets the ``maxStalenessSeconds`` option to ``120``. 
+For more information about connection string options, see the :manual:`Connection String Options </reference/connection-string/#connection-string-options>`
+section in the {+mdb-server+} manual.
+
+API Documentation
+-----------------
+
+To learn more about the methods and types mentioned in this guide, see the following API
+documentation:
+
+- `Write Concern <https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Client.html#write_concern-instance_method>`__
+- `Read Concern <{+api+}/Mongo/Client.html#read_concern-instance_method>`__
+- `Read Preference <https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection/View/Readable.html#read_preference-instance_method>`__