db.collection.updateOne()

在本页面

• Definition

• Behavior

• Examples

Definition

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

根据过滤器更新集合中的单个文档。

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

在版本 3.6 中更改。

db.collection.updateOne(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     arrayFilters: [ <filterdocument1>, ... ]
   }
)

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

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

指定一个空文档{ }以更新集合中返回的第一个文档。
| update |文档|要应用的修改。
使用Update Operators，例如$set，$unset或$rename。
为update参数使用field: value的update()模式会引发错误。
| upsert |布尔值|可选。当true，updateOne()时：
如果没有文档与filter相匹配，则创建一个新文档。有关更多详细信息，请参见upsert behavior。
更新与filter匹配的单个文档。
为避免多次更新，请确保filter字段为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 版中的新功能。
| arrayFilters | array |可选。筛选器文档数组，用于确定要对数组字段进行更新操作要修改的数组元素。
在更新文档中，使用$[<identifier>]过滤的位置运算符定义标识符，然后在数组过滤器文档中引用该标识符。如果更新文档中未包含标识符，则不能具有数组过滤器文档作为标识符。

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

Behavior

updateOne()使用update指令应用修改来更新集合中与filter匹配的第一个匹配文档。

如果upsert: true且没有文档与filter匹配，则updateOne()根据filter标准和update修改创建一个新文档。参见用 Upsert 更新。

Capped Collection

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

Explainability

updateOne()与db.collection.explain()不兼容。

请改用update()。

Examples

Update

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 }

以下操作使用violations字段更新单个文档name: "Central Perk Cafe"：

try {
   db.restaurant.updateOne(
      { "name" : "Central Perk Cafe" },
      { $set: { "violations" : 3 } }
   );
} 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.updateOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { $set: {"_id" : 4, "violations" : 7, "borough" : "Manhattan" } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

由于upsert:true，因此根据filter和update标准，文档是inserted。该操作返回：

{
   "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" : 4 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 7 }

name字段是使用filter条件填写的，而update运算符用于创建文档的其余部分。

以下操作使用大于10的violations更新第一个文档：

try {
   db.restaurant.updateOne(
      { "violations" : { $gt: 10} },
      { $set: { "Closed" : true } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

该操作返回：

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : ObjectId("56310c3c0c5cbb6031cafaea")
}

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

{ "_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" : 4 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "grade" : 7 }
{ "_id" : ObjectId("56310c3c0c5cbb6031cafaea"), "Closed" : true }

由于没有文档与过滤器匹配，并且upsert是true，因此updateOne插入了仅具有生成的_id和update标准的文档。

使用写关注更新

给定一个三成员副本集，以下操作指定w的majority，wtimeout的100：

try {
   db.restaurant.updateOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { $inc: { "violations" : 3}, $set: { "Closed" : true } },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

如果主服务器和至少一个辅助服务器在 100 毫秒内确认每个写操作，则返回：

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

如果确认花费的时间超过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.updateOne(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

为阵列更新操作指定 arrayFilters

3.6 版的新功能。

从 MongoDB 3.6 开始，在更新数组字段时，您可以指定arrayFilters来确定要更新的数组元素。

更新元素匹配 arrayFilters 条件

创建包含以下文档的集合students：

db.students.insert([
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
])

要修改grades数组中所有大于或等于100的元素，请在db.collection.updateOne方法中将过滤后的位置运算符$[<identifier>]与arrayFilters选项一起使用：

db.students.updateOne(
   { grades: { $gte: 100 } },
   { $set: { "grades.$[element]" : 100 } },
   { arrayFilters: [ { "element": { $gte: 100 } } ] }
)

该操作将更新单个文档的grades字段，并且在操作之后，该集合将包含以下文档：

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 110, 100 ] }

更新一系列文档的特定元素

创建包含以下文档的集合students2：

db.students2.insert([
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
])

要为grades数组中坡度大于或等于85的所有元素修改mean字段的值，请在db.collection.updateOne方法中将过滤后的位置运算符$[<identifier>]与arrayFilters一起使用：

db.students2.updateOne(
   { },
   { $set: { "grades.$[elem].mean" : 100 } },
   { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] }
)

该操作将更新单个文档的数组，并且在操作之后，该集合将包含以下文档：

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
    ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}