Docs Home → Develop Applications → MongoDB Drivers → Node.js
Replace a Document
Note
If you specify a callback method, replaceOne() returns nothing. If you
do not specify one, this method returns a Promise that resolves to the
result object when it completes. See our guide on Promises and
Callbacks for more information, or the
API documentation for
information on the result object.
You can replace a single document using the
collection.replaceOne() method.
replaceOne() accepts a query document and a replacement document. If
the query matches a document in the collection, it replaces the first
document that matches the query with the provided replacement document.
This operation removes all fields and values in the original document and
replaces them with the fields and values in the replacement document. The
value of the _id field 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. If you set the upsert option field to
true the method inserts a new document if no document matches the query.
The replaceOne() method throws 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()
method which has a similar interface to replaceOne().
You can configure findOneAndReplace() to return either the
original matched document or the replacement document.
Example
Note
This example connects to an instance of MongoDB and uses a sample data database. To learn more about connecting to your MongoDB instance and loading this database, see the Usage Examples guide.
1 const { MongoClient } = require("mongodb"); 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = 5 "mongodb+srv://<user>:<password>@<cluster-url>?writeConcern=majority"; 6 7 const client = new MongoClient(uri, { 8 useNewUrlParser: true, 9 useUnifiedTopology: true, 10 }); 11 12 async function run() { 13 try { 14 await client.connect(); 15 16 const database = client.db("sample_mflix"); 17 const movies = database.collection("movies"); 18 19 // create a query for a movie to update 20 const query = { title: "Blacksmith Scene" }; 21 const options = { 22 // create a document if no documents match the query 23 upsert: true, 24 }; 25 // create a new document that will be used to replace the existing document 26 const replacement = { 27 title: "Sandcastles in the Sand", 28 plot: 29 "Robin Sparkles mourns for a relationship with a mall rat at an idyllic beach.", 30 }; 31 32 const result = await movies.replaceOne(query, replacement, options); 33 34 if (result.modifiedCount === 0 && result.upsertedCount === 0) { 35 console.log("No changes made to the collection."); 36 } else { 37 if (result.matchedCount === 1) { 38 console.log("Matched " + result.matchedCount + " documents."); 39 } 40 if (result.modifiedCount === 1) { 41 console.log("Updated one document."); 42 } 43 if (result.upsertedCount === 1) { 44 console.log( 45 "Inserted one new document with an _id of " + result.upsertedId._id 46 ); 47 } 48 } 49 } finally { 50 await client.close(); 51 } 52 } 53 run().catch(console.dir);