db.collection.updateOne()
Definition
db.collection.updateOne(filter, update, options)
Important
mongosh Method
This page documents a
mongosh
method. This is not the documentation for database commands or language-specific drivers, such as Node.js.For the database command, see the
update
command.For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
Updates a single document within the collection based on the filter.
Compatibility
You can use db.collection.updateOne()
for deployments hosted in the following
environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
The updateOne()
method has the following syntax:
db.collection.updateOne( <filter>, <update>, { upsert: <boolean>, writeConcern: <document>, collation: <document>, arrayFilters: [ <filterdocument1>, ... ], hint: <document|string>, let: <document>, sort: <document> } )
Parameters
The db.collection.updateOne()
method takes the following
parameters:
Parameter | Type | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
document | The selection criteria for the update. The same query
selectors as in the Specify an empty document | |||||||||||||||||||
document or pipeline | The modifications to apply. Can be one of the following:
To update with a replacement document, see
| |||||||||||||||||||
upsert | boolean | Optional. When
To avoid multiple upserts, ensure that the
Defaults to | ||||||||||||||||||
writeConcern | document | Optional. A document expressing the write concern. Omit to use the default write concern. Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern. | ||||||||||||||||||
collation | document | Optional. Specifies the collation to use for the operation. Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. The collation option has the following syntax:
When specifying collation, the If the collation is unspecified but the collection has a
default collation (see If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons. You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort. | ||||||||||||||||||
arrayFilters | array | Optional. An array of filter documents that determine which array elements to modify for an update operation on an array field. In the update document, use the NoteThe You can include the same identifier multiple times in the update
document; however, for each distinct identifier (
However, you can specify compound conditions on the same identifier in a single filter document, such as in the following examples:
For examples, see Specify | ||||||||||||||||||
Document or string | Optional. A document or string that specifies the index to use to support the query predicate. The option can take an index specification document or the index name string. If you specify an index that does not exist, the operation errors. For an example, see Specify | |||||||||||||||||||
let | Document | Optional. Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text. The document syntax is:
The variable is set to the value returned by the expression, and cannot be changed afterwards. To access the value of a variable in the command, use the double
dollar sign prefix ( NoteTo use a variable to filter results, you must access the variable
within the For a complete example using | ||||||||||||||||||
sort | Document | Optional. Determines which document the operation updates if the query
selects multiple documents. If the sort argument is not a document, the operation errors. MongoDB does not store documents in a collection in a particular order. When sorting on a field which contains duplicate values, documents containing those values may be returned in any order. If consistent sort order is desired, include at least one field in your
sort that contains unique values. The easiest way to guarantee this is
to include the See Sort Consistency for more information. New in version 8.0. |
Returns
The method returns a document that contains:
matchedCount
containing the number of matched documentsmodifiedCount
containing the number of modified documentsupsertedId
containing the_id
for the upserted documentupsertedCount
containing the number of upserted documentsA boolean
acknowledged
astrue
if the operation ran with write concern orfalse
if write concern was disabled
Access Control
On deployments running with authorization
, the
user must have access that includes the following privileges:
update
action on the specified collection(s).find
action on the specified collection(s).insert
action on the specified collection(s) if the operation results in an upsert.
The built-in role readWrite
provides the required
privileges.
Behavior
Updates a Single Document
db.collection.updateOne()
finds the first document that
matches the filter and applies the specified
update modifications.
Update with an Update Operator Expressions Document
For the update specifications, the
db.collection.updateOne()
method can accept a document that
only contains update operator expressions.
For example:
db.collection.updateOne( <query>, { $set: { status: "D" }, $inc: { quantity: 2 } }, ... )
Update with an Aggregation Pipeline
The db.collection.updateOne()
method can accept an
aggregation pipeline
[ <stage1>, <stage2>, ... ]
that specifies the modifications to perform.
The pipeline can consist of the following stages:
$addFields
and its alias$set
$replaceRoot
and its alias$replaceWith
.
Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).
For example:
db.collection.updateOne( <query>, [ { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } }, { $unset: [ "misc1", "misc2" ] } ] ... )
Note
For examples, see Update with Aggregation Pipeline.
Upsert
Starting in MongoDB 7.1, if you specify
upsert: true
on a sharded collection, you do not need to include the full shard key in the filter.If
upsert: true
and no documents match thefilter
,db.collection.updateOne()
creates a new document based on thefilter
criteria andupdate
modifications. See Update with Upsert.For additional
db.collection.updateOne()
behavior on a sharded collection, see Sharded Collections.
Capped Collection
If an update operation changes the document size, the operation will fail.
Sharded Collections
upsert
on a Sharded Collection
To use db.collection.updateOne()
on a sharded collection:
Starting in MongoDB 7.1, if you specify
upsert: true
on a sharded collection, you do not need to include the full shard key in the filter.If you don't specify
upsert: true
, you must include an exact match on the_id
field or target a single shard (such as by including the shard key in the filter).
However, documents in a sharded collection can be
missing the shard key fields. To target a
document that is missing the shard key, you can use the null
equality match in conjunction with another filter condition
(such as on the _id
field). For example:
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
Shard Key Modification
You can update a document's shard key value unless the shard key field is the
immutable _id
field.
Warning
Documents in sharded collections can be missing the shard key fields. Take precaution to avoid accidentally removing the shard key when changing a document's shard key value.
To modify the existing shard key value with
db.collection.updateOne()
:
You must run on a
mongos
. Do not issue the operation directly on the shard.You must run either in a transaction or as a retryable write.
You must include an equality filter on the full shard key.
See also upsert
on a Sharded Collection.
Missing Shard Key
Starting in version 7.1, you do not need to provide the shard key or
_id
field in the query specification.Documents in a sharded collection can be missing the shard key fields. To use
db.collection.updateOne()
to set a missing shard key, you must run on amongos
. Do not issue the operation directly on the shard.In addition, the following requirements also apply:
TaskRequirementsTo set tonull
Requires equality filter on the full shard key ifupsert: true
.To set to a non-null
valueMust be performed either inside a transaction or as a retryable write.
Requires equality filter on the full shard key if
upsert: true
.Tip
Since a missing key value is returned as part of a null equality match, to avoid updating a null-valued key, include additional query conditions (such as on the
_id
field) as appropriate.
See also:
Explainability
updateOne()
is not compatible with
db.collection.explain()
.
Transactions
db.collection.updateOne()
can be used inside distributed transactions.
Important
In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for distributed transactions.
For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.
Upsert within Transactions
You can create collections and indexes inside a distributed transaction if the transaction is not a cross-shard write transaction.
db.collection.updateOne()
with upsert: true
can be run on an existing
collection or a non-existing collection. If run on a non-existing
collection, the operation creates the collection.
Write Concerns and Transactions
Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.
Oplog Entries
If a db.collection.updateOne()
operation successfully updates a
document, the operation adds an entry on the oplog (operations
log). If the operation fails or does not find a document to update, the
operation does not add an entry on the oplog.
Examples
Update using Update Operator Expressions
The restaurant
collection contains the following documents:
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }
The following operation updates a single document where
name: "Central Perk Cafe"
with the violations
field:
try { db.restaurant.updateOne( { "name" : "Central Perk Cafe" }, { $set: { "violations" : 3 } } ); } catch (e) { print(e); }
The operation returns:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
If no matches were found, the operation instead returns:
{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }
Setting upsert: true
would insert the document if no match was found. See
Update with Upsert
Update with Aggregation Pipeline
The db.collection.updateOne()
can use an aggregation pipeline for the
update. The pipeline can consist of the following stages:
$addFields
and its alias$set
$replaceRoot
and its alias$replaceWith
.
Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).
Example 1
The following examples uses the aggregation pipeline to modify a field using the values of the other fields in the document.
Create a students
collection with the following documents:
db.students.insertMany( [ { "_id" : 1, "student" : "Skye", "points" : 75, "commentsSemester1" : "great at math", "commentsSemester2" : "loses temper", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, { "_id" : 2, "student" : "Elizabeth", "points" : 60, "commentsSemester1" : "well behaved", "commentsSemester2" : "needs improvement", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") } ] )
Assume that instead of separate commentsSemester1
and commentsSemester2
fields in the first document, you want to gather these into a comments
field,
like the second document. The following update operation uses an
aggregation pipeline to:
add the new
comments
field and set thelastUpdate
field.remove the
commentsSemester1
andcommentsSemester2
fields for all documents in the collection.
Make sure that the filter in the update command targets a unique document. The
field id
in the code below is an example of such a filter:
db.students.updateOne( { _id: 1 }, [ { $set: { status: "Modified", comments: [ "$commentsSemester1", "$commentsSemester2" ], lastUpdate: "$$NOW" } }, { $unset: [ "commentsSemester1", "commentsSemester2" ] } ] )
Note
- First Stage
The
$set
stage:creates a new array field
comments
whose elements are the current content of themisc1
andmisc2
fields andsets the field
lastUpdate
to the value of the aggregation variableNOW
. The aggregation variableNOW
resolves to the current datetime value and remains the same throughout the pipeline. To access aggregation variables, prefix the variable with double dollar signs$$
and enclose in quotes.
- Second Stage
- The
$unset
stage removes thecommentsSemester1
andcommentsSemester2
fields.
After the command, the collection contains the following documents:
{ "_id" : 2, "student" : "Elizabeth", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "well behaved", "needs improvement" ] } { _id: 1, student: 'Skye', points: 75, commentsSemester1: 'great at math', commentsSemester2: 'loses temper', lastUpdate: ISODate("2019-01-01T00:00:00.000Z") }
Note that after introducing a sort, only the first document encountered in the sort order is modified and the remaining documents are left untouched.
Example 2
The aggregation pipeline allows the update to perform conditional updates based on the current field values as well as use current field values to calculate a separate field value.
For example, create a students3
collection with the following documents:
db.students3.insertMany( [ { "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }, { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }, { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") } ] )
The third document _id: 3
is missing the average
and grade
fields. Using an aggregation pipeline, you can update the document with
the calculated grade average and letter grade.
db.students3.updateOne( { _id: 3 }, [ { $set: { average: { $trunc: [ { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } }, { $set: { grade: { $switch: { branches: [ { case: { $gte: [ "$average", 90 ] }, then: "A" }, { case: { $gte: [ "$average", 80 ] }, then: "B" }, { case: { $gte: [ "$average", 70 ] }, then: "C" }, { case: { $gte: [ "$average", 60 ] }, then: "D" } ], default: "F" } } } } ] )
Note
- First Stage
The
$set
stage:calculates a new field
average
based on the average of thetests
field. See$avg
for more information on the$avg
aggregation operator and$trunc
for more information on the$trunc
truncate aggregation operator.sets the field
lastUpdate
to the value of the aggregation variableNOW
. The aggregation variableNOW
resolves to the current datetime value and remains the same throughout the pipeline. To access aggregation variables, prefix the variable with double dollar signs$$
and enclose in quotes.
- Second Stage
- The
$set
stage calculates a new fieldgrade
based on theaverage
field calculated in the previous stage. See$switch
for more information on the$switch
aggregation operator.
After the command, the collection contains the following documents:
{ "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") } { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") } { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:33:30.674Z"), "average" : 75, "grade" : "C" }
Update with Upsert
The restaurant
collection contains the following documents:
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : "0" }
The following operation attempts to update the document with
name : "Pizza Rat's Pizzaria"
, while upsert: true
:
try { db.restaurant.updateOne( { "name" : "Pizza Rat's Pizzaria" }, { $set: {"_id" : 4, "violations" : 7, "borough" : "Manhattan" } }, { upsert: true } ); } catch (e) { print(e); }
Since upsert:true
the document is inserted
based on the filter
and
update
criteria. The operation returns:
{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0, "upsertedId" : 4, "upsertedCount": 1 }
The collection now contains the following documents:
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 }, { "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 7 }
The name
field was filled in using the filter
criteria, while the
update
operators were used to create the rest of the document.
The following operation updates the first document with violations
that
are greater than 10
:
try { db.restaurant.updateOne( { "violations" : { $gt: 10} }, { $set: { "Closed" : true } }, { upsert: true } ); } catch (e) { print(e); }
The operation returns:
{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0, "upsertedId" : ObjectId("56310c3c0c5cbb6031cafaea") }
The collection now contains the following documents:
{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 }, { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 }, { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 }, { "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "grade" : 7 } { "_id" : ObjectId("56310c3c0c5cbb6031cafaea"), "Closed" : true }
Since no documents matched the filter, and upsert
was true
,
updateOne()
inserted the document with a generated
_id
and the update
criteria only.
Update with Write Concern
Given a three member replica set, the following operation specifies a
w
of majority
, wtimeout
of 100
:
try { db.restaurant.updateOne( { "name" : "Pizza Rat's Pizzaria" }, { $inc: { "violations" : 3}, $set: { "Closed" : true } }, { w: "majority", wtimeout: 100 } ); } catch (e) { print(e); }
If the primary and at least one secondary acknowledge each write operation within 100 milliseconds, it returns:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
If the acknowledgment takes longer than the wtimeout
limit, the following
exception is thrown:
WriteConcernError({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } } })
The following table explains the possible values of
errInfo.writeConcern.provenance
:
Provenance | Description |
---|---|
clientSupplied | The write concern was specified in the application. |
customDefault | The write concern originated from a custom defined
default value. See setDefaultRWConcern . |
getLastErrorDefaults | The write concern originated from the replica set's
settings.getLastErrorDefaults field. |
implicitDefault | The write concern originated from the server in absence
of all other write concern specifications. |
Update with Sort
New in version 8.0.
The following example deactivates the lowest rated active user:
db.people.updateOne( { state: "active" }, { $set: { state: "inactive" } }, { sort: { rating: 1 } )
Specify Collation
Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.
A collection myColl
has the following documents:
{ _id: 1, category: "café", status: "A" } { _id: 2, category: "cafe", status: "a" } { _id: 3, category: "cafE", status: "a" }
The following operation includes the collation option:
db.myColl.updateOne( { category: "cafe" }, { $set: { status: "Updated" } }, { collation: { locale: "fr", strength: 1 } } );
Specify arrayFilters
for an Array Update Operations
When updating an array field, you can specify arrayFilters
that
determine which array elements to update.
Update Elements Match arrayFilters
Criteria
Create a collection students
with the following documents:
db.students.insertMany( [ { "_id" : 1, "grades" : [ 95, 92, 90 ] }, { "_id" : 2, "grades" : [ 98, 100, 102 ] }, { "_id" : 3, "grades" : [ 95, 110, 100 ] } ] )
To modify all elements that are greater than or equal to 100
in the
grades
array, use the filtered positional operator
$[<identifier>]
with the arrayFilters
option in the
db.collection.updateOne()
method:
db.students.updateOne( { grades: { $gte: 100 } }, { $set: { "grades.$[element]" : 100 } }, { arrayFilters: [ { "element": { $gte: 100 } } ] } )
The operation updates the grades
field of a single document, and
after the operation, the collection has the following documents:
{ "_id" : 1, "grades" : [ 95, 92, 90 ] } { "_id" : 2, "grades" : [ 98, 100, 100 ] } { "_id" : 3, "grades" : [ 95, 110, 100 ] }
Update Specific Elements of an Array of Documents
Create a collection students2
with the following documents:
db.students2.insertMany( [ { "_id" : 1, "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 90, "std" : 4 }, { "grade" : 85, "mean" : 85, "std" : 6 } ] }, { "_id" : 2, "grades" : [ { "grade" : 90, "mean" : 75, "std" : 6 }, { "grade" : 87, "mean" : 90, "std" : 3 }, { "grade" : 85, "mean" : 85, "std" : 4 } ] } ] )
To modify the value of the mean
field for all elements in the
grades
array where the grade is greater than or equal to 85
,
use the filtered positional operator $[<identifier>]
with
the arrayFilters
in the db.collection.updateOne()
method:
db.students2.updateOne( { }, { $set: { "grades.$[elem].mean" : 100 } }, { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] } )
The operation updates the array of a single document, and after the operation, the collection has the following documents:
{ "_id" : 1, "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 100, "std" : 4 }, { "grade" : 85, "mean" : 100, "std" : 6 } ] } { "_id" : 2, "grades" : [ { "grade" : 90, "mean" : 75, "std" : 6 }, { "grade" : 87, "mean" : 90, "std" : 3 }, { "grade" : 85, "mean" : 85, "std" : 4 } ] }
Specify hint
for Update Operations
Create a sample students
collection with the following documents:
db.students.insertMany( [ { "_id" : 1, "student" : "Richard", "grade" : "F", "points" : 0, "comments1" : null, "comments2" : null }, { "_id" : 2, "student" : "Jane", "grade" : "A", "points" : 60, "comments1" : "well behaved", "comments2" : "fantastic student" }, { "_id" : 3, "student" : "Ronan", "grade" : "F", "points" : 0, "comments1" : null, "comments2" : null }, { "_id" : 4, "student" : "Noah", "grade" : "D", "points" : 20, "comments1" : "needs improvement", "comments2" : null }, { "_id" : 5, "student" : "Adam", "grade" : "F", "points" : 0, "comments1" : null, "comments2" : null }, { "_id" : 6, "student" : "Henry", "grade" : "A", "points" : 86, "comments1" : "fantastic student", "comments2" : "well behaved" } ] )
Create the following indexes on the collection:
db.students.createIndex( { grade: 1 } ) db.students.createIndex( { points: 1 } )
The following update operation explicitly hints to use the index {
grade: 1 }
:
Note
If you specify an index that does not exist, the operation errors.
db.students.updateOne( { "points": { $lte: 20 }, "grade": "F" }, { $set: { "comments1": "failed class" } }, { hint: { grade: 1 } } )
The update command returns the following:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
Note
Even though 3 documents match the criteria of the update, updateOne
only
modifies the first document it finds. Therefore, even though the students
Richard, Ronan, and Adam all meet the criteria, only Richard will be updated.
To see the index used, run explain
on the operation:
db.students.explain().update( { "points": { $lte: 20 }, "grade": "F" }, { $set: { "comments1": "failed class" } }, { multi: true, hint: { grade: 1 } } )
User Roles and Document Updates
Starting in MongoDB 7.0, you can use the new USER_ROLES
system variable to return user roles.
The example in this section shows updates to fields in a collection
containing medical information. The example reads the current user roles
from the USER_ROLES
system variable and only performs the updates if
the user has a specific role.
To use a system variable, add $$
to the start of the variable name.
Specify the USER_ROLES
system variable as $$USER_ROLES
.
The example creates these users:
James
with aBilling
role.Michelle
with aProvider
role.
Perform the following steps to create the roles, users, and collection:
Create the roles
Create roles named Billing
and Provider
with the required
privileges and resources.
Run:
db.createRole( { role: "Billing", privileges: [ { resource: { db: "test", collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } ) db.createRole( { role: "Provider", privileges: [ { resource: { db: "test", collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
Log in as as Michelle
, who has the Provider
role, and perform an
update:
The previous example uses $setIntersection
to return
documents where the intersection between the "Provider"
string and
the user roles from $$USER_ROLES.role
is not empty. Michelle
has
the Provider
role, so the update is performed.
Next, log in as as James
, who does not have the Provider
role,
and attempt to perform the same update:
The previous example does not update any documents.