• Reference >
• mongo Shell Methods >
• Collection Methods >
• db.collection.updateOne()

db.collection.updateOne()

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:

copy

db.collection.updateOne(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <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, updateOne() either: Creates a new document if no documents match the filter. For more details see upsert behavior. Updates a single document that matches the filter. To avoid multiple upserts, ensure that the filter fields are uniquely indexed. Defaults to false.
writeConcern	document	Optional. A document expressing the write concern. Omit to use the default 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: copy collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document. If the collation is unspecified but the collection has a default collation (see db.createCollection()), the operation uses the collation specified for the collection. 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. New in version 3.4.

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

If an update operation changes the document size, the operation will fail.

Explainability

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

Use update() instead.

Examples

Update

The restaurant collection contains the following documents:

copy

{ "_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:

copy

try {
   db.restaurant.updateOne(
      { "name" : "Central Perk Cafe" },
      { $set: { "violations" : 3 } }
   );
} catch (e) {
   print(e);
}

The operation returns:

copy

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

If no matches were found, the operation instead returns:

copy

{ "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:

copy

{ "_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 :

copy

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:

copy

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4
}

The collection now contains the following documents:

copy

{ "_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:

copy

try {
   db.restaurant.updateOne(
      { "violations" : { $gt: 10} },
      { $set: { "Closed" : true } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

The operation returns:

copy

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : ObjectId("56310c3c0c5cbb6031cafaea")
}

The collection now contains the following documents:

copy

{ "_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:

copy

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:

copy

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

If the acknowledgement takes longer than the wtimeout limit, the following exception is thrown:

copy

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

Specify Collation

New in version 3.4.

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:

copy

{ _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:

copy

db.myColl.updateOne(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

See also

To update multiple documents, see db.collection.updateMany().

←   db.collection.update() db.collection.updateMany()  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.