db.collection.replaceOne()¶

On this page

Definition
Behavior
Examples

Definition¶

db.collection.replaceOne(filter, replacement, options)¶

New in version 3.2.

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

The replaceOne() method has the following form:

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

The replaceOne() 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 replace the first document returned in the collection.
`replacement`	document	The replacement document. Cannot contain update operators.
`writeConcern`	document	Optional. A document expressing the write concern. Omit to use the default write concern.
`upsert`	boolean	Optional. When `true`, if no documents match the `filter`, a new document is inserted based on the `replacement` document.

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¶

replaceOne() replaces the first matching document in the collection that matches the filter, using the replacement document.

If upsert: true and no documents match the filter, replaceOne() creates a new document based on the replacement document. See Replace with Upsert.

Capped Collections¶

replaceOne() throws a WriteError if the replacement document has a larger size in bytes than the original document.

Examples¶

Replace¶

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 replaces a single document where name: "Central Perk Cafe":

try {
   db.inventory.replaceOne(
      { "name" : "Central Perk Cafe" },
      { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
   );
}
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 Replace with Upsert

Replace 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 replace the document with name : "Pizza Rat's Pizzaria", with upsert : true:

try {
   db.restaurant.replaceOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { "_id:" 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 },
      { upsert: true }
   )
}
catch (e){
   print(e);
}

Since upsert : true the document is inserted based on the replacement document. 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" : "8" }

Replace with Write Concern¶

Given a three member replica set, the following operation specifies a w of majority and wtimeout of 100:

try {
   db.restaurant.replaceOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 },
       { w: "majority", wtimeout: 100 }
   );
}
catch (e) {
   print(e);
}

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

try {
   WriteConcernError({
      "code" : 64,
      "errInfo" : {
         "wtimeout" : true
      },
      "errmsg" : "waiting for replication timed out"
   });
}
catch {
   print(e);
}

← db.collection.reIndex() db.collection.remove() →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.