From d1bd0f18646d2be96653a44b459f92e18cb122c3 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 16 Dec 2024 15:22:23 -0500 Subject: [PATCH 1/4] DOCSP-45188: Replace --- source/includes/write/replace.rb | 0 source/write/replace.txt | 216 +++++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+) create mode 100644 source/includes/write/replace.rb create mode 100644 source/write/replace.txt diff --git a/source/includes/write/replace.rb b/source/includes/write/replace.rb new file mode 100644 index 000000000..e69de29bb diff --git a/source/write/replace.txt b/source/write/replace.txt new file mode 100644 index 000000000..61693fa55 --- /dev/null +++ b/source/write/replace.txt @@ -0,0 +1,216 @@ +.. _ruby-write-replace: + +================= +Replace Documents +================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: modify, change, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to perform a **replace +operation** on a document in a MongoDB collection. A replace operation +removes all fields and values from a specified document except the +``_id`` field, and adds new fields and values that you specify. This +operation differs from an update operation, which changes only +specified fields in one or more documents. + +To learn more about update operations, see the +:ref:`ruby-write-update` guide. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your {+language+} application, create a ``MongoClient`` object that connects to an Atlas cluster +and assign the following values to your ``database`` and ``collection`` variables: + +.. literalinclude:: /includes/write/replace.rb + :language: ruby + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Replace Operation +----------------- + +You can perform a replace operation in MongoDB by using the +``replace_one`` method. This method removes all fields except the +``_id`` field from the first document that matches the specified query filter. It +then adds the fields and values you specify to the empty document. + +Required Parameters +~~~~~~~~~~~~~~~~~~~ + +You must pass the following parameters to the ``replace_one`` method: + +- **Query filter**: Matches which documents to update. To learn + more about query filters, see the :ref:`ruby-specify-query` + guide. + +- **Replacement document**: Specifies the fields and values that + you want to replace the existing fields and values with. + +Replace One Document +-------------------- + +The following example uses the ``replace_one`` method to replace the +fields and values of a document in which the value of the ``name`` field +is ``"Primola Restaurant"``: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/write/replace.rb + :start-after: start-replace-one + :end-before: end-replace-one + :language: ruby + :dedent: + + .. output:: + :language: console + :visible: false + + Replaced document count: 1 + Completed + +.. important:: + + The value of the ``_id`` field is immutable. If your replacement + document specifies a value for the ``_id`` field, it must be the same + as the ``_id`` value of the existing document or the driver raises a + ``WriteError``. + +Customize the Replace Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can pass a ``Hash`` as a parameter to the ``replace_one`` method to set options to +configure the replace operation. If you don't specify any options, the driver performs the replace +operation with default settings. + +The following table describes the options that you can use to +configure the replace operation: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``upsert`` + - | Specifies whether the replace operation performs an upsert operation if no + documents match the query filter. For more information, see :manual:`upsert + behavior ` + in the {+mdb-server+} manual. + | Defaults to ``false``. + + * - ``bypass_document_validation`` + - | Specifies whether the update operation bypasses document validation. This lets you + update documents that don't meet the schema validation requirements, if any + exist. For more information about schema validation, see :manual:`Schema + Validation ` in the {+mdb-server+} manual. + | Defaults to ``false``. + + * - ``collation`` + - | Specifies the kind of language collation to use when sorting + results. For more information, see :manual:`Collation ` + in the {+mdb-server+} manual. + + * - ``session`` + - | Specifies the session to use for the operation. To learn more about sessions, see + :manual:`Client Sessions and Causal Consistency Guarantees ` + in the {+mdb-server+} manual. + + * - ``hint`` + - | Sets the index to use when matching documents. + For more information, see the :manual:`hint statement + ` + in the {+mdb-server+} manual. + + * - ``let()`` + - | Provides a map of parameter names and values to set top-level + variables for the operation. Values must be constant or closed + expressions that don't reference document fields. + + * - ``comment()`` + - | Sets a comment to attach to the operation. + +The following code sets the ``upsert`` option to ``true``, which instructs the +driver to insert a new document that has the fields and values specified +in the replacement document if the query filter doesn't match any +existing documents: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/write/replace.rb + :start-after: start-replace-options + :end-before: end-replace-options + :language: ruby + :dedent: + + .. output:: + :language: console + :visible: false + + Replaced document count: 1 + Completed + +Return Value +~~~~~~~~~~~~ + +The ``replace_one`` method returns an ``UpdateResult`` +object. You can use the following methods to access information from +an ``UpdateResult`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getMatchedCount()`` + - | Returns the number of documents that matched the query filter. + + * - ``getModifiedCount()`` + - | Returns the number of documents modified by the update operation. If an updated + document is identical to the original, it is not included in this + count. + + * - ``wasAcknowledged()`` + - | Returns ``true`` if the server acknowledged the result. + + * - ``getUpsertedId()`` + - | Returns the ``_id`` value of the document that the driver upserted + into the database, if any. + +Additional Information +---------------------- + +To view a runnable code example that demonstrates how to replace a +document, see :ref:`ruby-write`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + From 0cc2f1ace619ef694f05d03cd160211149eeeab6 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 17 Dec 2024 11:44:45 -0500 Subject: [PATCH 2/4] DOCSP-45188: Replace --- source/includes/write/replace.rb | 29 ++++++++++++++++++++++++++++ source/write/replace.txt | 33 +++++++++++++++----------------- 2 files changed, 44 insertions(+), 18 deletions(-) diff --git a/source/includes/write/replace.rb b/source/includes/write/replace.rb index e69de29bb..849e9253b 100644 --- a/source/includes/write/replace.rb +++ b/source/includes/write/replace.rb @@ -0,0 +1,29 @@ +require 'bundler/inline' +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = "" + +Mongo::Client.new(uri) do |client| + # start-db-coll + database = client.use('sample_restaurants') + collection = database[:restaurants] + # end-db-coll + + # Replaces a single document in the collection + # start-replace-one + filter = { name: 'Primola Restaurant' } + new_document = { name: 'Frutti Di Mare', cuisine: 'Seafood', borough: 'Queens' } + result = collection.replace_one(filter, new_document) + puts "Replaced #{result.modified_count} document(s)" + # end-replace-one + + # Uses the upsert option to replace a single document in the collection + # start-replace-options + options = { upsert: true } + result = collection.replace_one(filter, new_document, options) + puts "Upserted #{result.upserted_count} document(s)" + # end-replace-options +end \ No newline at end of file diff --git a/source/write/replace.txt b/source/write/replace.txt index 61693fa55..1dcd1d344 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -87,8 +87,7 @@ is ``"Primola Restaurant"``: :language: console :visible: false - Replaced document count: 1 - Completed + Replaced 1 document(s) .. important:: @@ -144,17 +143,14 @@ configure the replace operation: ` in the {+mdb-server+} manual. - * - ``let()`` + * - ``let`` - | Provides a map of parameter names and values to set top-level variables for the operation. Values must be constant or closed expressions that don't reference document fields. - * - ``comment()`` - - | Sets a comment to attach to the operation. - -The following code sets the ``upsert`` option to ``true``, which instructs the -driver to insert a new document that has the fields and values specified -in the replacement document if the query filter doesn't match any +The following code performs the same replace operation as above, but sets the ``upsert`` +option to ``true``. This instructs the driver to insert a new document that has the fields +and values specified in the replacement document if the query filter doesn't match any existing documents: .. io-code-block:: @@ -170,15 +166,14 @@ existing documents: :language: console :visible: false - Replaced document count: 1 - Completed + Replaced 1 document(s) Return Value ~~~~~~~~~~~~ -The ``replace_one`` method returns an ``UpdateResult`` +The ``replace_one`` method returns an ``Mongo::Operation::Update::Result`` object. You can use the following methods to access information from -an ``UpdateResult`` instance: +a ``Result`` instance: .. list-table:: :widths: 30 70 @@ -187,18 +182,18 @@ an ``UpdateResult`` instance: * - Method - Description - * - ``getMatchedCount()`` + * - ``matched_count`` - | Returns the number of documents that matched the query filter. - * - ``getModifiedCount()`` + * - ``modified_count`` - | Returns the number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count. - * - ``wasAcknowledged()`` - - | Returns ``true`` if the server acknowledged the result. + * - ``upserted_count`` + - | Returns the number of documents upserted. - * - ``getUpsertedId()`` + * - ``upserted_id`` - | Returns the ``_id`` value of the document that the driver upserted into the database, if any. @@ -214,3 +209,5 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: +- `replace_one <{+api-root+}/Mongo/Collection.html#replace_one-instance_method>`_ +- `Mongo::Operation::Update::Result <{+api-root+}/Mongo/Operation/Update/Result.html>`_ \ No newline at end of file From ed5e5326c5811f7509a61768545c6138b4f97aa9 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 17 Dec 2024 12:09:37 -0500 Subject: [PATCH 3/4] Fixes --- source/includes/write/replace.rb | 2 +- source/write/replace.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/write/replace.rb b/source/includes/write/replace.rb index 849e9253b..a5667c2d4 100644 --- a/source/includes/write/replace.rb +++ b/source/includes/write/replace.rb @@ -24,6 +24,6 @@ # start-replace-options options = { upsert: true } result = collection.replace_one(filter, new_document, options) - puts "Upserted #{result.upserted_count} document(s)" + puts "Replaced #{result.upserted_count} document(s)" # end-replace-options end \ No newline at end of file diff --git a/source/write/replace.txt b/source/write/replace.txt index 1dcd1d344..e61b8cd82 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -99,7 +99,7 @@ is ``"Primola Restaurant"``: Customize the Replace Operation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can pass a ``Hash`` as a parameter to the ``replace_one`` method to set options to +You can pass a ``Hash`` object as a parameter to the ``replace_one`` method to set options to configure the replace operation. If you don't specify any options, the driver performs the replace operation with default settings. @@ -171,7 +171,7 @@ existing documents: Return Value ~~~~~~~~~~~~ -The ``replace_one`` method returns an ``Mongo::Operation::Update::Result`` +The ``replace_one`` method returns a ``Mongo::Operation::Update::Result`` object. You can use the following methods to access information from a ``Result`` instance: From f5ccbd0398c3a897d7ba1589c1dd61515cab41e7 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 17 Dec 2024 14:12:36 -0500 Subject: [PATCH 4/4] JS feedback --- source/write/replace.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/write/replace.txt b/source/write/replace.txt index e61b8cd82..1119e154a 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -60,15 +60,15 @@ Required Parameters You must pass the following parameters to the ``replace_one`` method: -- **Query filter**: Matches which documents to update. To learn +- **Query filter**: Specifies which documents to update. To learn more about query filters, see the :ref:`ruby-specify-query` guide. - **Replacement document**: Specifies the fields and values that you want to replace the existing fields and values with. -Replace One Document --------------------- +Replace Example +~~~~~~~~~~~~~~~ The following example uses the ``replace_one`` method to replace the fields and values of a document in which the value of the ``name`` field @@ -148,7 +148,7 @@ configure the replace operation: variables for the operation. Values must be constant or closed expressions that don't reference document fields. -The following code performs the same replace operation as above, but sets the ``upsert`` +The following code performs the same replace operation as the preceding example, but sets the ``upsert`` option to ``true``. This instructs the driver to insert a new document that has the fields and values specified in the replacement document if the query filter doesn't match any existing documents: