Update Documents

Overview

In this guide, you can learn how to update documents in MongoDB by using update operations.

Update operations change the fields that you specify while leaving other fields and values unchanged.

In MongoDB, all methods to modify documents follow the same pattern:

Note

Placeholder

changeX is a placeholder and not a real method.

The pattern expects you to:

Specify a query filter to match one or more documents to modify.
Specify the field and value changes.
Specify options, if you must modify the method behavior.

The driver provides the following methods to update documents:

UpdateByID(): Updates a single document based on its _id.
UpdateOne(): Updates a single document.
UpdateMany(): Updates multiple documents.

A Note About _id

Each document in a MongoDB collection has a unique and immutable _id field. You cannot use update operations to change the _id field. If you attempt to change this field, the update methods return a WriteError.

Sample Data

Parameters

Each method takes an update document that includes at least one update operator. The update operator specifies the type of update to perform. The update document also includes the fields and values that describe the change. Update documents use the following format:

bson.D{{"<update operator>", bson.D{{"<field>", <value>},
                                    {"<field>", <value>}, ... }},
       {"<update operator>", ... }, ... }

See the MongoDB server manual for a complete list of update operators and descriptions.

Tip

UpdateOne() updates the first document that matches the query filter you provide. To ensure that you update the correct document, you can use the sort option to specify the order in which the operation finds documents. To learn more, see the UpdateOneOptions API documentation.

Note

Aggregation Pipelines in Update Operations

You can use aggregation pipelines made up of a subset of aggregation stages in update operations. To learn more about the aggregation stages MongoDB supports in aggregation pipelines, see our tutorial on performing updates with aggregation pipelines.

Return Values

UpdateOne(), UpdateByID(), and UpdateMany() return an UpdateResult type that contains information about the update operation if the operation is successful. The UpdateResult type contains the following properties:

Property	Description
`MatchedCount`	The number of documents matched by the filter
`ModifiedCount`	The number of documents modified by the operation
`UpsertedCount`	The number of documents upserted by the operation
`UpsertedID`	The `_id` of the upserted document, or `nil` if there is none

If multiple documents match the query filter passed to UpdateOne(), the method selects and updates the first matched document. If no documents match the query filter, the update operation makes no changes.

See our upsert guide to learn how to insert a new document if no documents match the query filter.

UpdateOne() Example

The following example uses the listingsAndReviews collection in the sample_airbnb dataset from the Atlas sample datasets. The following document describes an airbnb listing:

{
    "_id": "10006546",
   "listing_url": "https://www.airbnb.com/rooms/10006546",
   "name": "Ribeira Charming Duplex",
   "summary": "Fantastic duplex apartment with three bedrooms, located in the historic area of Porto, Ribeira (Cube)...",
   ...
   "minimum_nights": "2",
   "maximum_nights": "30",
   ...
    "accommodates": 8,
   ...
}

The following example uses the UpdateOne() method to:

Match the document where the _id value is "10006546".
Set the name field to "Ribiera River View Duplex".
Increment the value of the accommodates field by 1.

filter := bson.D{{"_id", "10006546"}}
update := bson.D{{"$set", bson.D{{"name", "Ribiera River View Duplex"}}},
   {"$inc", bson.D{{"accomodates", 1}}}}
result, err := collection.UpdateOne(context.TODO(), filter, update)
fmt.Printf("Documents matched: %v\n", result.MatchedCount)
fmt.Printf("Documents updated: %v\n", result.ModifiedCount)

Documents matched: 1
Documents updated: 1

The following shows the updated document resulting from the preceding update operation:

{
    "_id": "10006546",
   "listing_url": "https://www.airbnb.com/rooms/10006546",
   "name": "Ribeira River View Duplex",
   "summary": "Fantastic duplex apartment with three bedrooms, located in the historic area of Porto, Ribeira (Cube)...",
   ...
   "minimum_nights": "2",
   "maximum_nights": "30",
   ...
    "accommodates": 9,
   ...
}

UpdateMany() Example

The following example uses the listingsAndReviews collection in the sample_airbnb dataset from the Atlas sample datasets.

The following example uses the UpdateMany() method to:

Match documents in which the value of the address.market field is "Sydney".
Multiply the price value in the matched documents by 1.15

coll := client.Database("sample_airbnb").Collection("listingsAndReviews")
filter := bson.D{{"address.market", "Sydney"}}
// Creates instructions to update the values of the "price" field
update := bson.D{{"$mul", bson.D{{"price", 1.15}}}}
// Updates documents in which the value of the "address.market"
// field is "Sydney"
result, err := coll.UpdateMany(context.TODO(), filter, update)
if err != nil {
	panic(err)
}
// Prints the number of updated documents
fmt.Printf("Documents updated: %v\n", result.ModifiedCount)

The update operation updates 609 documents.

To learn more about how to retrieve multiple documents, see Find All Documents.

Additional Information

To learn more about the operations mentioned, see the following guides:

To learn more about updating array elements, see Update Arrays in a Document.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API Documentation:

Back

Geospatial Queries

Replace Documents