db.collection.updateOne()¶

On this page

Definition
Behavior
Examples

Definition¶

db.collection.updateOne(filter, update, options)¶

New in version 3.2.

Updates a single document within the collection based on the filter.

The updateOne() method has the following form:

db.collection.updateOne(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>
   }
)

The updateOne() method takes the following parameters:

Parameter	Type	Description
`filter`	document	The selection criteria for the update. The same query selectors as in the `find()` method are available. Specify an empty document `{ }` to update the first document returned in the collection.
`update`	document	The modifications to apply. Use Update Operators such as `$set`, `$unset`, or `$rename`. Using the update() pattern of `field: value` for the `update` parameter throws an error.
`upsert`	boolean	Optional. When `true`, if no documents match the `filter`, a new document is created using the equality comparisons in `filter` with the modifications from `update`. Comparison operations from the `filter` will not be included in the new document. If the `filter` only has comparison operations, then only the modifications from the `update` will be applied to the new document. See Update with Upsert
`writeConcern`	document	Optional. A document expressing the write concern. Omit to use the default write concern.

Returns:	A document containing: A boolean `acknowledged` as `true` if the operation ran with write concern or `false` if write concern was disabled `matchedCount` containing the number of matched documents `modifiedCount` containing the number of modified documents `upsertedId` containing the `_id` for the upserted document

Behavior¶

updateOne() updates the first matching document in the collection that matches the filter, using the update instructions to apply modifications.

If upsert: true and no documents match the filter, updateOne() creates a new document based on the filter criteria and update modifications. See Update with Upsert.

Capped Collection¶

updateOne() throws a WriteError exception if the update criteria increases the size of the first matching document in a capped collection.

Explainability¶

updateOne() is not compatible with db.collection.explain().

Use update() instead.

Examples¶

Update¶

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.inventory.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 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
}

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 {
   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 {
   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 acknowledgement takes longer than the wtimeout limit, the following exception is thrown:

WriteConcernError({
   "code" : 64,
   "errInfo" : {
      "wtimeout" : true
   },
   "errmsg" : "waiting for replication timed out"
}) :