Navigation
This version of the documentation is archived and no longer supported.

db.collection.replaceOne()

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, replaceOne() either:

  • Inserts the document from the replacement parameter if no document matches the filter.
  • Replaces the document that matches the filter with the replacement document.

MongoDB will add the _id field to the replacement document if it is not specified in either the filter or replacement documents. If _id is present in both, the values must be equal.

To avoid multiple upserts, ensure that the query fields are uniquely indexed.

Defaults to false.

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

If a replacement operation changes the document size, the operation will fail.

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.restaurant.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" : 0 },
{ "_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:

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