Modify Documents

On this page

Overview

Update Documents
Replace a Document

Overview

You can modify documents in a MongoDB collection by using update and replace operations. Update operations modify the fields and values of a document while keeping other fields and values unchanged. Replace operations substitute all fields and values in an existing document with specified fields and values while keeping the _id field value unchanged.

The Node.js driver provides the following methods to change documents:

updateOne()
updateMany()
replaceOne()

Tip

Interactive Lab

This page includes a short interactive lab that demonstrates how to modify data by using the updateMany() method. You can complete this lab directly in your browser window without installing MongoDB or a code editor.

To start the lab, click the Open Interactive Tutorial button at the top of the page. To expand the lab to a full-screen format, click the full-screen button (⛶) in the top-right corner of the lab pane.

Update Documents

To perform an update to one or more documents, create an update document that specifies the update operator (the type of update to perform) and the fields and values that describe the change. Update documents use the following format:

{
   <update operator>: {
      <field> : {
         ...
      },
      <field> : {
      }
   },
   <update operator>: {
      ...
   }
}

The top level of an update document contains one or more of the following update operators:

$set: replaces the value of a field with a specified one
$inc: increments or decrements field values
$rename: renames fields
$unset: removes fields
$mul: multiplies a field value by a specified number

See the MongoDB Server manual for a complete list of update operators and their usage.

The update operators apply only to the fields associated with them in your update document.

Note

Aggregation Pipelines in Update Operations

If you are using MongoDB Version 4.2 or later, you can use aggregation pipelines made up of a subset of aggregation stages in update operations. For more information on the aggregation stages MongoDB supports in aggregation pipelines used in update operations, see our tutorial on building updates with aggregation pipelines.

Example

Consider a document in the myDB.items collection with fields describing an item for sale, its price, and the quantity available:

{
   _id: 465,
   item: "Hand-thrown ceramic plate",
   price: 32.50,
   quantity: 7,
}

If you apply the $set update operator with a new value for quantity, you can use the following update document:

const myDB = client.db("myDB");
const myColl = myDB.collection("items");
const filter = { _id: 465 };
// update the value of the 'quantity' field to 5
const updateDocument = {
   $set: {
      quantity: 5,
   },
};
const result = await myColl.updateOne(filter, updateDocument);

The updated document resembles the following, with an updated value in the quantity field and all other values unchanged:

{
   _id: 465,
   item: "Hand-thrown ceramic plate",
   price: 32.50,
   quantity: 5,
}

If an update operation fails to match any documents in a collection, it does not make any changes. Update operations can be configured to perform an upsert which attempts to perform an update, but if no documents are matched, inserts a new document with the specified fields and values.

You cannot modify the _id field of a document nor change a field to a value that violates a unique index constraint. See the MongoDB Server manual for more information on unique indexes.

Replace a Document

To perform a replacement operation, create a replacement document that consists of the fields and values that you want to use in your replace operation. Replacement documents use the following format:

{
   <field>: {
      <value>
   },
   <field>: {
      ...
   }
}

Replacement documents are the documents that you want to take the place of existing documents that match the query filters.

Example

Consider a document in the myDB.items collection with fields describing an item for sale, its price, and the quantity available:

{
   _id: 501,
   item: "3-wick beeswax candle",
   price: 18.99,
   quantity: 10,
}

Suppose you wanted to replace this document with one that contains a description for an entirely different item. Your replacement operation might resemble the following:

const myDB = client.db("myDB");
const myColl = myDB.collection("items");
const filter = { _id: 501 };
// replace the matched document with the replacement document
const replacementDocument = {
   item: "Vintage silver flatware set",
   price: 79.15,
   quantity: 1,
};
const result = await myColl.replaceOne(filter, replacementDocument);

The replaced document contains the contents of the replacement document and the immutable _id field as follows:

{
   _id: 501,
   item: "Vintage silver flatware set",
   price: 79.15,
   quantity: 1,
}

If a replace operation fails to match any documents in a collection, it does not make any changes. Replace operations can be configured to perform an upsert which attempts to perform the replacement, but if no documents are matched, it inserts a new document with the specified fields and values.

You cannot modify the _id field of a document nor change a field to a value that violates a unique index constraint. See the MongoDB Server manual for more information on unique indexes.

Back

Delete Documents

Update Arrays in a Document