• Reference >
• mongosh Methods >
• Collection Methods >
• db.collection.replaceOne()

db.collection.replaceOne()

Definition

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

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for a language-specific driver such as Node.js.

For MongoDB API drivers, refer to the language-specific :driver:`MongoDB driver documentation </>`.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

• :v4.4:`mongo shell v4.4 </mongo>`
• mongo shell v4.2

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

The replaceOne() method has the following form:

copy

db.collection.replaceOne(
   <filter>,
   <replacement>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     hint: <document|string>                   // Available starting in 4.2.1
   }
)

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.
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.
writeConcern	document	Optional. 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 in a transaction. To use write concern with transactions, see Transactions and 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.
hint	document	Optional. A document or string that specifies the index to use to support the filter. The option can take an index specification document or the index name string. If you specify an index that does not exist, the operation errors. 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 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.

upsert

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

If you specify upsert: true on a sharded collection, you must include the full shard key in the filter. For additional db.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.

Time Series Collections

You cannot use the replaceOne() method on a time series collection.

Sharded Collections

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

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

Shard Key Requirements In Replacement Document

Starting in MongoDB 4.4, the replacement document does not need to include the shard key. In MongoDB 4.2 and earlier, the replacement document must include the shard key.

Warning

Starting in version 4.4, documents in sharded collections can be missing the shard key fields. Take precaution to avoid accidentally removing the shard key when changing a document’s shard key value.

upsert on a Sharded Collection

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

However, starting in version 4.4, documents in a sharded collection can be missing the shard key fields. To target a document that is missing the shard key, you can use the null equality match :red:`in conjunction with` another filter condition (such as on the _id field). For example:

copy

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Shard Key Modification

Starting in MongoDB 4.2, you can update a document’s shard key value unless the shard key field is the immutable _id field. In MongoDB 4.2 and earlier, a document’s shard key field value is immutable.

Warning

Starting in version 4.4, documents in sharded collections can be missing the shard key fields. Take precaution to avoid accidentally removing the shard key when changing a document’s shard key value.

To modify the existing shard key value with db.collection.replaceOne():

• You :red:`must` run on a mongos. Do :red:`not` issue the operation directly on the shard.
• You :red:`must` run either in a transaction or as a retryable write.
• You :red:`must` include an equality filter on the full shard key.

Missing Shard Key

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. To use db.collection.replaceOne() to set the document’s missing shard key, you :red:`must` run on a mongos. Do :red:`not` issue the operation directly on the shard.

In addition, the following requirements also apply:

Task	Requirements
To set to null	Requires equality filter on the full shard key if upsert: true is specified.
To set to a non-null value	:red:`Must` be performed either inside a transaction or as a retryable write. Requires equality filter on the full shard key if either: upsert: true, or the new shard key value belongs to a different shard.

Tip

Since a missing key value is returned as part of a null equality match, to avoid updating a null-valued key, include additional query conditions (such as on the _id field) as appropriate.

See also:

• upsert on a Sharded Collection
• Missing Shard Key Fields

Transactions

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

Important

In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.

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

Upsert within Transactions

Starting in MongoDB 4.4, you can create collections and indexes inside a multi-document transaction if the transaction is :red:`not` a cross-shard write transaction.

Specifically, in MongoDB 4.4 and greater, db.collection.replaceOne() with upsert: true can be run on an existing collection or a non-existing collection. If run on a non-existing collection, the operation creates the collection.

In MongoDB 4.2 and earlier, the operation must be run on an existing collection.

See also

Create Collections and Indexes In a Transaction

Write Concerns and Transactions

Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

Examples

Replace

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

copy

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

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

copy

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:

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

copy

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:

Changed in version 4.4.

copy

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

The following table explains the possible values of errInfo.writeConcern.provenance:

Provenance	Description
clientSupplied	The write concern was specified in the application.
customDefault	The write concern originated from a custom defined default value. See setDefaultRWConcern.
getLastErrorDefaults	The write concern originated from the replica set’s settings.getLastErrorDefaults field.
implicitDefault	The write concern originated from the server in absence of all other write concern specifications.

Specify Collation

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.replaceOne(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }

);

Specify hint for replaceOne

New in version 4.2.1.

Create a sample members collection with the following documents:

copy

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

Create the following indexes on the collection:

copy

db.members.createIndex( { status: 1 } )
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.

copy

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

The operation returns the following:

copy

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

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

copy

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

←   db.collection.renameCollection() db.collection.stats()  →

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