Docs Home → MongoDB Manual

db.collection.replaceOne()

On this page本页内容

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.本页记录了一个mongosh方法。这不是数据库命令或特定语言驱动程序（如Node.js）的文档。

For the database command, see the update command.有关数据库命令，请参阅update命令。

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.有关MongoDB API驱动程序，请参阅特定语言的MongoDB驱动程序文档。

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:对于遗留的mongoshell文档，请参阅相应MongoDB Server版本的文档：

mongo shell v4.4

Replaces a single document within the collection based on the filter.基于筛选器替换集合中的单个文档。

The replaceOne() method has the following form:replaceOne()方法具有以下形式：

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:replaceOne()方法采用以下参数：

Parameter参数Type类型Description描述
filterdocumentThe selection criteria for the update. 更新的选择条件。The same query selectors as in the find() method are available.可以使用与find()方法中相同的查询选择器。
Specify an empty document { } to replace the first document returned in the collection. 指定一个空文档{ }以替换集合中返回的第一个文档。
replacementdocumentThe replacement document.替换文档。
Cannot contain update operators. 不能包含更新运算符。
upsertbooleanOptional.可选的。When true, replaceOne() either: 如果为true，replaceOne()将执行：
  • Inserts the document from the replacement parameter if no document matches the filter.如果没有与filter匹配的文档，则插入replacement参数中的文档。
  • Replaces the document that matches the filter with the replacement document.用replacement文档替换与filter匹配的文档。
MongoDB will add the _id field to the replacement document if it is not specified in either the filter or replacement documents. 如果filter或replacement文档中都没有指定_id字段，MongoDB会将其添加到替换文档中。If _id is present in both, the values must be equal.如果两者中都存在_id，则值必须相等。
To avoid multiple upserts, ensure that the query fields are uniquely indexed.为了避免出现多个混乱，请确保query字段的索引是唯一的。
Defaults to false. 默认为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 in a transaction. 如果在事务中运行，请不要显式设置操作的写入关注。To use write concern with transactions, see Transactions and Write Concern. 要在事务中使用写入关注，请参阅事务和写入关注。
collationdocumentOptional.可选的。
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选项具有以下语法：
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. 指定排序规则时，locale字段是必需的；所有其他排序规则字段都是可选的。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.如果未指定排序规则，但集合具有默认排序规则（请参见db.createCollection()），则操作将使用为集合指定的排序规则。
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.如果没有为集合或操作指定排序规则，MongoDB将使用以前版本中使用的简单二进制比较进行字符串比较。
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. 不能为一个操作指定多个排序规则。例如，不能为每个字段指定不同的排序规则，或者如果使用排序执行查找，则不能为查找使用一个排序规则，为排序使用另一个排序顺序。
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 index name string.该选项可以采用索引规范文档或索引名称字符串。
If you specify an index that does not exist, the operation errors.如果指定的索引不存在，则操作将出错。
For an example, see Specify hint for replaceOne. 有关示例，请参阅指定replaceOne的hint。
New in version 4.2.1. 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如果操作在有写入关注的情况下运行，则布尔值acknowledged为true；如果写入关注被禁用，则为false
  • matchedCount containing the number of matched documents包含匹配的文档数
  • modifiedCount containing the number of modified documents包含修改的文档数
  • upsertedId containing the _id for the upserted document包含被打乱的文档的_id

Behavior行为

replaceOne() replaces the first matching document in the collection that matches the filter, using the replacement document.使用replacement文档替换集合中与filter匹配的第一个匹配文档。

upsert

If upsert: true and no documents match the filter, db.collection.replaceOne() creates a new document based on the replacement document.如果upsert: true并且没有文档与filter匹配，则db.collection.replaceOne()将基于replacement文档创建一个新文档。

If you specify upsert: true on a sharded collection, you must include the full shard key in the filter. 如果在分片集合上指定upsert: true，则必须在filter中包含完整的分片键。For additional db.collection.replaceOne() behavior on a sharded collection, see Sharded Collections.有关分片化集合上的其他db.collection.replaceOne()行为，请参阅分片化集合。

See Replace with Upsert.请参见用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.不能对时间序列集合使用replaceOne()方法。

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.从MongoDB 4.2开始，db.collection.replaceOne()尝试以单个分片为目标，首先使用查询筛选器。如果查询筛选器无法将操作定位于单个分片，则会尝试将替换文档作为目标。

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. 从MongoDB 4.4开始，替换文档不需要包含分片键。In MongoDB 4.2 and earlier, the replacement document must include the shard key.在MongoDB 4.2及更早版本中，替换文档必须包含分片键。

Warning

Starting in version 4.4, documents in sharded collections can be missing the shard key fields. 从4.4版本开始，分片集合中的文档可能会缺少分片键字段。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.从MongoDB 4.2开始，在分片集合上包含upsert:true的db.collection.replaceOne()操作必须在筛选器中包含完整的分片键。

However, starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 但是，从4.4版本开始，分片集合中的文档可能会缺少分片键字段。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). 要针对缺少分片键的文档，可以将null相等匹配与另一个筛选条件结合使用（例如在_id字段上）。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. 从MongoDB 4.2开始，您可以更新文档的分片键值，除非分片键字段是不可变的_id字段。In MongoDB 4.2 and earlier, a document's shard key field value is immutable.在MongoDB 4.2及更早版本中，文档的分片键字段值是不可变的。

Warning

Starting in version 4.4, documents in sharded collections can be missing the shard key fields. 从4.4版本开始，分片集合中的文档可能会缺少分片键字段。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():要使用db.collection.replaceOne()修改现有的分片键值，请执行以下操作：

  • You must run on a mongos. Do not issue the operation directly on the shard.你必须在mongos上运行。不要直接在分片上发出操作。
  • 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. 从4.4版本开始，分片集合中的文档可能会缺少分片键字段。To use db.collection.replaceOne() to set the document's missing shard key, you must run on a mongos. 要使用db.collection.replaceOne()设置文档缺少的分片键，必须在mongos上运行。Do not issue the operation directly on the shard.不要直接在分片上发出操作。

In addition, the following requirements also apply:此外，以下要求也适用：

Task任务Requirements要求
To set to null设置为null
  • Requires equality filter on the full shard key if upsert: true is specified.如果指定了upsert: true，则需要对完整的分片键进行相等筛选器。
To set to a non-null value设置为非null值
  • 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.由于丢失的键值是作为null相等匹配的一部分返回的，为了避免更新null值的键，请酌情包括额外的查询条件（例如在_id字段上）。

See also:另请参阅：

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事务中的Upsert

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.从MongoDB 4.4开始，如果多文档事务不是跨分片写入事务，则可以在该事务内创建集合和索引。

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. 具体来说，在MongoDB 4.4及更高版本中，具有upsert:true的db.collection.replaceOne()可以在现有集合或不存在的集合上运行。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.在MongoDB 4.2及更早版本中，操作必须在现有集合上运行。

Tip

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:restaurant集合包含以下文件：

{ "_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":以下操作将替换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. 如果未找到匹配项，则设置upsert: true将插入文档。See Replace with Upsert请参见用Upsert替换

Replace with Upsert替换为Upsert

The restaurant collection contains the following documents:restaurant集合包含以下文件：

{ "_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:以下操作尝试将使用upsert : true把文档替换为name : "Pizza Rat's Pizzaria"替换为：

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:由于upsert : true，因此将根据replacement文档插入文档。操作返回：

{
   "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:给定一个由三个成员组成的复制集，以下操作指定w为majority，wtimeout为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:如果确认花费的时间超过wtimeout限制，则引发以下异常：

Changed in version 4.4.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:下表解释了errInfo.writeConcern.provenance的可能值：

Provenance来源Description描述
clientSuppliedThe write concern was specified in the application.写入关注已在应用程序中指定。
customDefaultThe write concern originated from a custom defined default value. 写入关注源自自定义定义的默认值。See setDefaultRWConcern.请参阅setDefaultRWConcern。
getLastErrorDefaultsThe write concern originated from the replica set's settings.getLastErrorDefaults field.写入关注源自复制副本集的settings.getLastErrorDefaults字段。
implicitDefaultThe 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.collation允许用户为字符串比较指定特定于语言的规则，例如大小写和重音标记的规则。

A collection myColl has the following documents:集合myColl包含以下文档：

{ _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:以下操作包括collation选项：

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

);

Specify hint for replaceOne指定replaceOne的hint

New in version 4.2.1. 4.2.1版新增。

Create a sample members collection with the following documents:使用以下文档创建示例members集合：

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 }:以下更新操作明确提示使用索引{ 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:要查看使用的索引，可以使用$indexStats管道：

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