db.collection.replaceOne()

Definition

  • db.collection.replaceOne(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 within the collection based on the filter.

The replaceOne() method has the following form:

  1. db.collection.replaceOne(
  2.    <filter>,
  3.    <replacement>,
  4.    {
  5.      upsert: <boolean>,
  6.      writeConcern: <document>,
  7.      collation: <document>,
  8.      hint: <document|string>                   // Available starting in 4.2.1
  9.    }
  10. )

The replaceOne() method takes the followingparameters:

ParameterTypeDescriptionfilterdocumentThe selection criteria for the update. The same queryselectors as in the find() method are available.

Specify an empty document { } to replace the first document returned inthe collection.replacementdocumentThe replacement document.

Cannot containupdate operators.upsertbooleanOptional. When true, replaceOne() either:

  • Inserts the document from the replacement parameter if no document matches thefilter.
  • 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 specifiedin 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 fieldsare uniquely indexed.

Defaults to false.writeConcerndocumentOptional. A document expressing the write concern. Omit to use the default write concern.

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

Specifies the collation to use for the operation.

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

The collation option has the following syntax:

  1. collation: {
  2.    locale: <string>,
  3.    caseLevel: <boolean>,
  4.    caseFirst: <string>,
  5.    strength: <int>,
  6.    numericOrdering: <boolean>,
  7.    alternate: <string>,
  8.    maxVariable: <string>,
  9.    backwards: <boolean>
  10. }

When specifying collation, the locale field is mandatory; allother collation fields are optional. For descriptions of the fields,see Collation Document.

If the collation is unspecified but the collection has adefault collation (see db.createCollection()), theoperation uses the collation specified for the collection.

If no collation is specified for the collection or for theoperations, MongoDB uses the simple binary comparison used in priorversions for string comparisons.

You cannot specify multiple collations for an operation. Forexample, you cannot specify different collations per field, or ifperforming a find with a sort, you cannot use one collation for thefind and another for the sort.

New in version 3.4.

hintdocumentOptional. A document or string that specifies the index to use to support the filter.

The option can take an index specification document or the indexname string.

If you specify an index that does not exist, the operationerrors.

For an example, see Specify hint for replaceOne.

New in version 4.2.1.

Returns:A document containing:

  • A boolean acknowledged as true if the operation ran withwrite 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 inthe collection that matches the filter, using the replacementdocument.

upsert

If upsert: true and no documents match the filter,db.collection.replaceOne() creates a new document based onthe replacement document.

If you specify upsert: true on a sharded collection, you mustinclude the full shard key in the filter. For additionaldb.collection.replaceOne() behavior on a sharded collection,see Sharded Collections.

See Replace with Upsert.

Capped Collections

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

Sharded Collections

Starting in MongoDB 4.2, db.collection.replaceOne() attemptsto target a single shard, first by using the query filter. If the operationcannot target a single shard by the query filter, it then attempts to targetby the replacement document.

In earlier versions, the operation attempts to target using thereplacement document.

If replacing a document in a sharded collection, the replacementdocument must include the shard key. Additional requirements apply forupsert on a Sharded Collection andShard Key Modification.

upsert on a Sharded Collection

Starting in MongoDB 4.2, for a db.collection.replaceOne()operation that includes upsert: true and is on a shardedcollection, you must include the full shard key in the filter.

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.

To use db.collection.replaceOne() to update the shard key:

  • You must run on a mongos either in atransaction or as a retryablewrite. Do not issue the operationdirectly on the shard.
  • You must include an equality condition on the full shardkey in the query filter. For example, if a collection messagesuses { country : 1, userid : 1 } as the shard key, to updatethe shard key for a document, you must include country: <value>,userid: <value> in the query filter. You can include additionalfields in the query as appropriate.

Transactions

db.collection.replaceOne() 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

The restaurant collection contains the following documents:

  1. { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" },
  2. { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
  3. { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

The following operation replaces a single document wherename: "Central Perk Cafe":

  1. try {
  2.    db.restaurant.replaceOne(
  3.       { "name" : "Central Perk Cafe" },
  4.       { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
  5.    );
  6. } catch (e){
  7.    print(e);
  8. }

The operation returns:

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

If no matches were found, the operation instead returns:

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

Setting upsert: true would insert the document if no match was found. SeeReplace with Upsert

Replace with Upsert

The restaurant collection contains the following documents:

  1. { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan",  "violations" : 3 },
  2. { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
  3. { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

The following operation attempts to replace the document withname : "Pizza Rat's Pizzaria", with upsert : true:

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

Since upsert : true the document is inserted based on thereplacement document. The operation returns:

  1. {
  2.    "acknowledged" : true,
  3.    "matchedCount" : 0,
  4.    "modifiedCount" : 0,
  5.    "upsertedId" : 4
  6. }

The collection now contains the following documents:

  1. { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
  2. { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
  3. { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 },
  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 aw of majority and wtimeout of 100:

  1. try {
  2.    db.restaurant.replaceOne(
  3.        { "name" : "Pizza Rat's Pizzaria" },
  4.        { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 },
  5.        { w: "majority", wtimeout: 100 }
  6.    );
  7. } catch (e) {
  8.    print(e);
  9. }

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

  1. WriteConcernError({
  2.    "code" : 64,
  3.    "errInfo" : {
  4.       "wtimeout" : true
  5.    },
  6.    "errmsg" : "waiting for replication timed out"
  7. })

Specify Collation

New in version 3.4.

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

A collection myColl has the following documents:

  1. { _id: 1, category: "café", status: "A" }
  2. { _id: 2, category: "cafe", status: "a" }
  3. { _id: 3, category: "cafE", status: "a" }

The following operation includes the collationoption:

  1. db.myColl.replaceOne(
  2.    { category: "cafe", status: "a" },
  3.    { category: "cafÉ", status: "Replaced" },
  4.    { collation: { locale: "fr", strength: 1 } }
  5.  
  6. );

Specify hint for replaceOne

New in version 4.2.1.

Create a sample members collection with the following documents:

  1. db.members.insertMany([
  2.    { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
  3.    { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
  4.    { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
  5.    { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
  6.    { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
  7.    { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
  8. ])

Create the following indexes on the collection:

  1. db.members.createIndex( { status: 1 } )
  2. db.members.createIndex( { points: 1 } )

The following update operation explicitly hints to use the index {status: 1 }:

Note

If you specify an index that does not exist, the operation errors.

  1. db.members.replaceOne(
  2.    { "points": { $lte: 20 }, "status": "P" },
  3.    { "misc1": "using index on status", status: "P", member: "replacement", points: "20"},
  4.    { hint: { status: 1 } }
  5. )

The operation returns the following:

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

To view the indexes used, you can use the $indexStats pipeline:

  1. db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )