db.collection.replaceOne()

On this page

Definition
Behavior
Examples

Definition

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

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the update command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

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

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>,
     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: 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 in conjunction with another filter condition (such as on the _id field). For example:

{ _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 must run on a mongos. Do not issue the operation directly on the shard.
You must run either in a transaction or as a retryable write.
You 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 must run on a mongos. Do 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	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.

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 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.

Tip

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:

Changed in version 4.4.

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:

{ _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:

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:

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:

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.

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:

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

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

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

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

db.collection.replaceOne()

Definition

Important

mongosh Method

Behavior

`upsert`

Capped Collections

Time Series Collections

Sharded Collections

Shard Key Requirements In Replacement Document

Warning

`upsert` on a Sharded Collection

Shard Key Modification

Warning

Missing Shard Key

Tip

Transactions

Important

Upsert within Transactions

Tip

See also:

Write Concerns and Transactions

Examples

Replace

Replace with Upsert

Replace with Write Concern

Specify Collation

Specify `hint` for `replaceOne`

Note

db.collection.replaceOne()

Definition

Important

mongosh Method

Behavior

upsert

Capped Collections

Time Series Collections

Sharded Collections

Shard Key Requirements In Replacement Document

Warning

upsert on a Sharded Collection

Shard Key Modification

Warning

Missing Shard Key

Tip

Transactions

Important

Upsert within Transactions

Tip

See also:

Write Concerns and Transactions

Examples

Replace

Replace with Upsert

Replace with Write Concern

Specify Collation

Specify hint for replaceOne

Note

`upsert`

`upsert` on a Sharded Collection

Specify `hint` for `replaceOne`