DOCSP-45184-ruby-replica-sets

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

@@ -0,0 +1,81 @@
+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
+end
+
+
+

source/index.txt

@@ -16,6 +16,7 @@
    Connect </connect>
    Write Data </write>
    Read Data </read>
+   Operations on Replica Sets </read-write-pref> 
    Indexes </indexes>
    View the Source <https://github.com/mongodb/mongo-ruby-driver>
    API Documentation <{+api-root+}>
@@ -25,7 +26,6 @@
 .. TODO:
  Databases & Collections </databases-collections>
  Write Data </write>
- Operations on Replica Sets </read-write-pref>
  Monitor Your Application </monitoring>
  Data Aggregation </aggregation>
  Security </security>
@@ -66,11 +66,11 @@ working with data in the :ref:`ruby-get-started` tutorial.
 
 .. Learn how you can write data to MongoDB in the :ref:`ruby-write` section.
 
-.. Configure Operations on Replica Sets
-.. ------------------------------------
+Configure Operations on Replica Sets
+------------------------------------
 
-.. Learn how to configure read and write operations on a replica set in the
-.. :ref:`ruby-read-write-pref` section.
+Learn how to configure read and write operations on a replica set in the
+:ref:`ruby-crud-write-read-pref` section.
 
 .. Optimize Queries by Using Indexes
 .. ---------------------------------

source/read-write-pref.txt

@@ -0,0 +1,236 @@
+.. _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
+<{+api-root+}/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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following 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
+
+- :manual:`Isolation guarantees </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 <{+api-root+}/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
+
+.. TODO: insert :ref:`Aggregation <ruby-aggregation>` link here
+.. For more information about aggregation, see the 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 <{+api-root+}/Mongo/Collection/View/Readable.html#read_preference-instance_method>`__.
+
+The following table shows options you can use 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
+
+.. TODO: insert :ref:`Transactions <ruby-transactions>` link
+.. For more information about transactions, see the Transactions guide.
+
+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 <{+api-root+}/Mongo/Client.html#write_concern-instance_method>`__
+- `Read Concern <{+api-root+}/Mongo/Client.html#read_concern-instance_method>`__
+- `Read Preference <{+api-root+}/Mongo/Collection/View/Readable.html#read_preference-instance_method>`__