(DOCSP-7605): replace a document (#20)

Author: nathan-contino-mongo

source/code-snippets/usage-examples/replaceOne.js

@@ -0,0 +1,51 @@
+// ignored first line
+const { MongoClient } = require("mongodb");
+
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
+  "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+const client = new MongoClient(uri);
+
+async function run() {
+  try {
+    await client.connect();
+
+    const database = client.db("sample_mflix");
+    const collection = database.collection("movies");
+
+    // create a query for a movie to update
+    const query = { title: "Blacksmith Scene" };
+    const options = {
+      // create a document if no documents match the query
+      upsert: true,
+    };
+    // create a new document that will be used to replace the existing document
+    const replacement = {
+      title: "Sandcastles in the Sand",
+      plot:
+        "Robin Sparkles mourns for a relationship with a mall rat at an idyllic beach.",
+    };
+
+    const result = await collection.replaceOne(query, replacement, options);
+
+    if (result.modifiedCount === 0 && result.upsertedCount === 0) {
+      console.log("No changes made to the collection.");
+    } else {
+      if (result.matchedCount === 1) {
+        console.log("Matched " + result.matchedCount + " documents.");
+      }
+      if (result.modifiedCount === 1) {
+        console.log("Updated one document.");
+      }
+      if (result.upsertedCount === 1) {
+        console.log(
+          "Inserted one new document with an _id of " + result.upsertedId._id,
+        );
+      }
+    }
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -13,6 +13,7 @@ Usage Examples
 :doc:`findOne </usage-examples/findOne>`
 :doc:`insertMany </usage-examples/insertMany>`
 :doc:`updateOne</usage-examples/updateOne>`
+:doc:`replaceOne</usage-examples/replaceOne>`
 :doc:`distinct</usage-examples/distinct>`
 
 .. toctree::
@@ -28,4 +29,5 @@ Usage Examples
    /usage-examples/findOneAndUpdate
    /usage-examples/insertMany
    /usage-examples/updateOne
+   /usage-examples/replaceOne
    /usage-examples/distinct

source/usage-examples/replaceOne.txt

@@ -0,0 +1,47 @@
+==================
+Replace a Document
+==================
+
+.. default-domain:: mongodb
+
+You can replace a single document using the `replaceOne()
+<https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#replaceOne>`_
+method. ``replaceOne()`` accepts a query document and a replacement
+document, and fully replaces the first document that matches the query
+with the provided replacement document. All fields and values in the
+original document are removed with the exception of the ``_id`` value,
+which remains the same unless you explicitly specify a new value for
+``_id`` in the replacement document.
+
+You can specify additional options, such as ``upsert``, using the
+optional ``options`` parameter. Configuring the ``upsert`` field to
+``true`` in the options object causes the operation to insert a new
+document if no document matches the query.
+
+The ``replaceOne()`` method returns a `Promise
+<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+that resolves to an `updateWriteOpResult
+<https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#~updateWriteOpResult>`_
+object. You can use the ``modifiedCount`` field of this
+object to determine whether or not a document was modified. If the
+operation was configured to upsert a document, the ``upsertedCount``
+field indicates the number of newly inserted documents. Use the
+``upsertedId._id`` field if you need a unique identifier for an upserted
+document.
+
+The ``replaceOne()`` method will throw an exception if an error occurs
+during execution. For example, if you specify a value that violates a
+unique index rule, ``replaceOne()`` throws a ``duplicate key error``.
+
+.. note::
+
+  If your application requires the document after updating,
+  use the `collection.findOneAndReplace()
+  <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#findOneAndReplace>`_
+  method which has a similar interface to ``replaceOne()``.
+  You can configure ``findOneAndReplace()`` to return either the
+  original matched document or the replacement document.
+
+.. literalinclude:: /code-snippets/usage-examples/replaceOne.js
+  :language: javascript
+  :linenos:

source/usage-examples/updateOne.txt

@@ -9,23 +9,24 @@ You can update a single document using the `updateOne()
 method. ``updateOne()`` accepts a filter document, and updates the first
 document that matches the filter using a provided update document. The
 update document requires an :manual:`Update
-Operator<reference/operator/update/#update-operators`_ to modify a field in a document.
+Operator</reference/operator/update/#update-operators>`
+to modify a field in a document.
 
 Create an `Object
 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_
-to specify additional options. Set the ``upsert`` option to ``true`` to create a new
-document if no documents match the filter.
+to specify additional options. Set the ``upsert`` option to ``true`` to
+create a new document if no documents match the filter.
 
 The ``updateOne()`` method returns a `Promise
 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
 that resolves to an object. The ``modifiedCount`` field of this object
-has a value of ``0`` if no documents were updated, and a value of ``1`` if a
-document was updated. 
+has a value of ``0`` if no documents were updated, and a value of ``1``
+if a document was updated.
 
-Specifying incorrect parameters for your ``updateOne()`` operation can cause
-problems. Attempting to modify the immutable field ``_id`` will result
-in an error. Additionally, trying to update a field to value that would
-violate unique index rules will throw a ``duplicate key error``.
+Specifying incorrect parameters for your ``updateOne()`` operation can
+cause problems. Attempting to modify the immutable field ``_id`` will
+result in an error. Additionally, trying to update a field to value that
+would violate unique index rules will throw a ``duplicate key error``.
 
 .. literalinclude:: /code-snippets/usage-examples/updateOne.js
   :language: javascript