Update Documents

On this page

Overview

Sample Data
Update Operations
Update One Document
Update Many Documents
Customize the Update Operation
Return Value
Additional Information
API Documentation

Overview

In this guide, you can learn how to use PyMongo to update documents in a MongoDB collection by using the update_one() or update_many() methods.

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with PyMongo tutorial.

Update Operations

You can perform update operations in MongoDB by using the following methods:

update_one(), which updates the first document that matches the search criteria
update_many(), which updates all documents that match the search criteria

Each update method requires the following parameters:

A query filter document, which determines which documents to update. For more information about query filters, see the Query Filter Documents section in the MongoDB Server manual.
An update document, which specifies the update operator (the kind of update to perform) and the fields and values that should change. For a list of update operators and their usage, see the Field Update Operators guide page in the MongoDB Server manual.

Update One Document

The following example uses the update_one() method to update the name value of a document named "Bagels N Buns" in the restaurants collection:

restaurants = database["restaurants"]
query_filter = {'name' : 'Bagels N Buns'}
update_operation = { '$set' : 
    { 'name' : '2 Bagels 2 Buns' }
}
result = restaurants.update_one(query_filter, update_operation)

Update Many Documents

The following example uses the update_many() method to update all documents with a cuisine value of "Pizza". After the update, the documents have a cuisine value of "Pasta".

restaurants = database["restaurants"]
query_filter = {'cuisine' : 'Pizza'}
update_operation = { '$set' : 
    { 'cuisine' : 'Pasta' }
}
result = restaurants.update_many(query_filter, update_operation)

Customize the Update Operation

The update_one() and update_many() methods optionally accept additional parameters, which represent options you can use to configure the update operation. If you don't specify any additional options, the driver does not customize the update operation.

Property	Description
`upsert`	Specifies whether the update operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB 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 Schema Validation in the MongoDB Server manual. Defaults to `False`.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`array_filters`	A list of filters that specifies which array elements an update applies to.
`hint`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
`session`	An instance of `ClientSession`.
`let`	A Map of parameter names and values. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`comment`	A comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual for more information.

The following code uses the update_many() method to find all documents where the borough field has the value "Manhattan". It then updates the borough value in these documents to "Manhattan (north)". Because the upsert option is set to True, PyMongo inserts a new document if the query filter doesn't match any existing documents.

restaurants = database["restaurants"]
query_filter = {'borough' : 'Manhattan'}
update_operation = { '$set' : 
    { 'borough' : 'Manhattan (north)' }
}
result = restaurants.update_many(query_filter, update_operation, upsert = True)

Return Value

The update_one() and update_many() methods each return an UpdateResult object. The UpdateResult type contains the following properties:

Property	Description
`matched_count`	The number of documents that matched the query filter, regardless of how many were updated.
`modified_count`	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.
`raw_result`	The raw result document returned by the server.
`upserted_id`	The ID of the document that was upserted in the database, if the driver performed an upsert. Otherwise `None`.

Additional Information

To learn more about creating query filters, see the Specify a Query guide.

API Documentation

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

Back

Insert

Replace