db.collection.replaceOne()

在本页面

• Definition

• Behavior

• Examples

Definition

• db.collection. replaceOne(* filter ， replacement ， options *)
  • 3.2 版中的新功能。

根据过滤器替换集合中的单个文档。

replaceOne()方法具有以下形式：

db.collection.replaceOne(
   <filter>,
   <replacement>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>
   }
)

replaceOne()方法采用以下参数：

Parameter	Type	Description
filter	document	更新的选择标准。与find()方法中相同的query selectors可用。

指定一个空文档{ }来替换集合中返回的第一个文档。
| replacement |文档|替换文档。
不能包含update operators。
| upsert |布尔值|可选。当true，replaceOne()时：
如果没有文档与filter匹配，则从replacement参数插入文档。
将与filter匹配的文档替换为replacement文档。
如果在filter或replacement文档中均未指定，则 MongoDB 会将_id字段添加到替换文档中。如果两者中都存在_id，则值必须相等。
为避免多次更新，请确保query字段为uniquely indexed。
默认为false。
| writeConcern |文档|可选。表示write concern的文档。忽略使用默认的写关注。
| collation |文档|可选。
指定用于操作的collation。
Collation允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。
排序规则选项具有以下语法：
collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}
指定排序规则时，locale字段为必填字段；所有其他排序规则字段都是可选的。有关字段的说明，请参见Collation Document。
如果未指定排序规则，但是集合具有默认排序规则(请参见db.createCollection())，则该操作将使用为集合指定的排序规则。
如果没有为集合或操作指定排序规则，则 MongoDB 使用先前版本中使用的简单二进制比较进行字符串比较。
您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。
3.4 版中的新功能。

返回：	包含以下内容的文档： 如果操作以write concern或false运行，则布尔acknowledged为true，如果禁用了写关注 matchedCount包含匹配的文档数 modifiedCount包含已修改文档的数量 upsertedId包含要提交文档的_id

Behavior

replaceOne()使用replacement文档替换集合中与filter匹配的第一个匹配文档。

如果upsert: true并且没有文档匹配filter，则replaceOne()将基于replacement文档创建一个新文档。参见替换为 Upsert。

Capped Collections

如果替换操作更改了文档大小，则该操作将失败。

Examples

Replace

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 }

以下操作将替换单个文档，其中name: "Central Perk Cafe"：

try {
   db.restaurant.replaceOne(
      { "name" : "Central Perk Cafe" },
      { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
   );
} catch (e){
   print(e);
}

该操作返回：

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

如果未找到匹配项，则该操作返回：

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

如果未找到匹配项，则设置upsert: true将插入文档。见替换为 Upsert

替换为 Upsert

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 }

以下操作尝试将文档name : "Pizza Rat's Pizzaria"替换为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);
}

从upsert : true开始，文档是基于replacement文档插入的。该操作返回：

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4
}

现在，该集合包含以下文档：

{ "_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 }

替换为写入问题

给定一个三成员副本集，以下操作指定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);
}

如果确认花费的时间超过wtimeout限制，则会引发以下异常：

WriteConcernError({
   "code" : 64,
   "errInfo" : {
      "wtimeout" : true
   },
   "errmsg" : "waiting for replication timed out"
})

Specify Collation

3.4 版的新功能。

Collation允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。

集合myColl具有以下文档：

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

以下操作包括collation选项：

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

);