db.collection.findOneAndReplace()

Definition

• db.collection.findOneAndReplace(filter, replacement, options)

mongo Shell Method

This page documents the mongo shell method, and doesnot refer to the MongoDB Node.js driver (or any other driver)method. For corresponding MongoDB driver API, refer to your specificMongoDB driver documentation instead.

New in version 3.2.

Replaces a single document based on the specified filter.

Syntax

The findOneAndReplace() method has the followingform:

db.collection.findOneAndReplace(
   <filter>,
   <replacement>,
   {
     projection: <document>,
     sort: <document>,
     maxTimeMS: <number>,
     upsert: <boolean>,
     returnNewDocument: <boolean>,
     collation: <document>
   }
)

Parameters and Options

The findOneAndReplace() method takes the followingparameters and options:

collation: {   locale: <string>,   caseLevel: <boolean>,   caseFirst: <string>,   strength: <int>,   numericOrdering: <boolean>,   alternate: <string>,   maxVariable: <string>,   backwards: <boolean>}

Returns

Returns either the original document or, if returnNewDocument:true, the replacement document.

Behavior

Document Match

db.collection.findOneAndReplace() replaces the first matchingdocument in the collection that matches the filter.The sort parameter can be used to influence which document is modified.

Projection

The projection parameter takes a document in the following form:

{ field1 : < boolean >, field2 : < boolean> ... }

The <boolean> value can be any of the following:

• 1 or true to include the field. The method returns the_id field even if it is not explicitly stated in the projectionparameter.
• 0 or false to exclude the field. This can be used on anyfield, including _id.

Sharded Collections

To use db.collection.findOneAndReplace() on a sharded collection, the query filter mustinclude an equality condition on the shard key.

Shard Key Modification

Starting in MongoDB 4.2, you can update a document’s shard key valueunless the shard key field is the immutable _id field. For detailson updating the shard key, see Change a Document’s Shard Key Value.

Before MongoDB 4.2, a document’s shard key field value is immutable.

Transactions

db.collection.findOneAndReplace() can be used inside multi-document transactions.

If the operation results in an upsert, the collection must already exist.

Do not explicitly set the write concern for the operation if run ina transaction. To use write concern with transactions, seeTransactions and Write Concern.

Important

In most cases, multi-document transaction incurs a greaterperformance cost over single document writes, and theavailability of multi-document transactions should not be areplacement for effective schema design. For many scenarios, thedenormalized data model (embedded documents and arrays) will continue to be optimal for yourdata and use cases. That is, for many scenarios, modeling your dataappropriately will minimize the need for multi-documenttransactions.

For additional transactions usage considerations(such as runtime limit and oplog size limit), see alsoProduction Considerations.

Examples

Replace A Document

Create a sample scores collection with the following documents:

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

The following operation finds a document with score less than20000 and replaces it:

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 }
)

The operation returns the original document that has been replaced:

{ "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }

If returnNewDocument wastrue, the operation would return the replacement document instead.

Although multiple documents meet the filter criteria,db.collection.findOneAndReplace replaces only one document.

Sort and Replace A Document

Create a sample scores collection with the following documents:

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

By including an ascending sort onthe score field, the following example replaces the document with thelowest score among those documents that match the filter:

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 },
   { sort: { "score" : 1 } }
)

The operation returns the original document that has been replaced:

{ "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }

See Replace A Document for the non-sortedresult of this command.

Project Specific Fields in Return Document

Create a sample scores collection with the following documents:

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
])

The following operation uses projection to only display the team field inthe returned document:

db.scores.findOneAndReplace(
   { "score" : { $lt : 22250 } },
   { "team" : "Therapeutic Hamsters", "score" : 22250 },
   { sort : { "score" : 1 }, projection: { "_id" : 0, "team" : 1 } }
)

The operation returns the original document with only the team field:

{ "team" : "Cuddly Zebras" }

Replace Document with Time Limit

The following operation sets a 5ms time limit to complete:

try {
   db.scores.findOneAndReplace(
      { "score" : { $gt : 25000 } },
      { "team" : "Emphatic Rhinos", "score" : 25010 },
      { maxTimeMS: 5 }
   );
} catch(e){
   print(e);
}

If the operation exceeds the time limit, it returns:

Error: findAndModifyFailed failed: { "ok" : 0, "errmsg" : "operation exceeded time limit", "code" : 50 }

Replace Document with Upsert

The following operation uses the upsert field to insert thereplacement document if no document matches the filter:

try {
   db.scores.findOneAndReplace(
      { "team" : "Fortified Lobsters" },
      { "_id" : 6019, "team" : "Fortified Lobsters" , "score" : 32000},
      { upsert : true, returnNewDocument: true }
   );
} catch (e){
   print(e);
}

The operation returns the following:

{
   "_id" : 6019,
   "team" : "Fortified Lobsters",
   "score" : 32000
}

If returnNewDocument was false, the operation would return null asthere is no original document to return.

Specify Collation

New in version 3.4.

Collation allows users to specifylanguage-specific rules for string comparison, such as rules forlettercase and accent marks.

Create a sample myColl collection with the following documents:

db.myColl.insertMany([
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
]);

The following operation includes the collationoption:

db.myColl.findOneAndReplace(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

The operation returns the following document:

{ "_id" : 1, "category" : "café", "status" : "A" }