update

在此页面上

定义

兼容性
语法
命令字段
访问控制
行为
示例
输出

定义

update: update 命令修改集合中的文档。一个 update 命令可以包含多条更新语句。
提示
在mongosh中，该命令还运行通过 updateOne() 、 updateMany() 、 replaceOne() 、 findOneAndReplace()和findOneAndUpdate()辅助方法运行。
辅助方法对 mongosh 用户来说很方便，但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段，请使用数据库命令。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有MongoDB Atlas集群都支持此命令。有关Atlas支持所有命令的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

5.0 版本中的更改。

该命令具有以下语法：

db.runCommand(
   {
      update: <collection>,
      updates: [
         {
           q: <query>,
           u: <document or pipeline>,
           c: <document>, // Added in MongoDB 5.0
           upsert: <boolean>,
           multi: <boolean>,
           collation: <document>,
           arrayFilters: <array>,
           hint: <document|string>
         },
         ...
      ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>,
      let: <document> // Added in MongoDB 5.0
   }
)

命令字段

该命令接受以下字段：

字段

类型

说明

update

字符串

目标集合的名称。

updates

阵列

对指定集合执行的一个或多个更新语句的数组。有关更新语句的详细信息，请参阅更新语句。

ordered

布尔

可选。如果为 true，则当更新语句失败时，则会返回而不执行剩余的更新语句。如果为 false，则当更新失败时，继续执行剩余的更新语句（如果有）。默认为 true。

maxTimeMS

non-negative integer

可选。

指定时间限制（以毫秒为单位）。如果您未指定 maxTimeMS 值，操作将不会超时。如果值为 0 ，则显式指定默认无限制行为。

MongoDB 使用与 db.killOp() 相同的机制终止超过分配的时间限制的操作。MongoDB 仅在指定的中断点之一中终止操作。

writeConcern

文档

可选。一份表达 update 命令写关注的文档。省略以使用默认写关注。

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

bypassDocumentValidation

布尔

可选。启用 update 可在操作过程中绕过文档验证。这样便可更新不符合验证要求的文档。

comment

any

可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置：

mongod 日志消息，位于 attr.command.cursor.comment 字段中。
command.comment 字段中的数据库分析器输出。
currentOp 输出，在 command.comment 字段。

注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

let

文档

可选。

指定包含变量列表的文档。这样可以将变量与查询文本分开，从而提高命令的可读性。

文档语法为：

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

变量设置为表达式返回的值，并且之后不能再进行更改。

要访问命令中的变量值，请使用双美元符号前缀 ($$) 以及 $$<variable_name> 形式的变量名称。例如：$$targetTotal。

有关完整示例，请参阅在 let 选项或 c 字段中使用变量。

版本 5.0 中的新增功能。

更新语句

updates 数组的每个元素都是一个更新语句文档。每个文档都包含以下字段：

字段

类型

说明

文档

匹配要更新文档的查询。使用与 find() 方法中相同的查询选择器。

文档或管道

要应用的修改。该值可为以下任一项：

包含更新操作符表达式的文档、
仅有 <field1>: <value1> 对的替换文档，或者
聚合管道。
- $addFields 及其别名 $set
- $project 及其别名 $unset
- $replaceRoot 及其别名 $replaceWith。

有关详细信息，请参阅行为。

文档

可选。只有当 u 是管道时，才能指定 c。

指定包含变量列表的文档。这样可以将变量与查询文本分开，从而提高命令的可读性。

文档语法为：

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

变量设置为表达式返回的值，并且之后不能再进行更改。

要访问命令中的变量值，请使用双美元符号前缀 ($$) 以及 $$<variable_name> 形式的变量名称。例如：$$targetTotal。

要使用变量筛选结果，您必须在 $expr 操作符中访问该变量。

有关使用 let 和变量的完整示例，请参阅在 let 选项或 c 字段中使用变量。

版本 5.0 中的新增功能。

更新插入

布尔

可选。当为 true 时，update 将：

如果没有文档与 query 匹配，则创建一个新文档。有关详细信息，请参阅更新或插入行为。
更新与 query 匹配的单份文档。

如果 upsert 和 multi 均为 true，并且没有文档与查询匹配，则更新操作仅插入单个文档。

为避免出现多个 upsert 操作，请确保 query 字段具有唯一索引。请参阅使用唯一索引进行 upsert 以查看示例。

默认值为 false；即，在未找到匹配项时不插入新文档。

multi

布尔

可选。如果 true，则更新所有符合查询条件的文档。如果 false，则将更新限制为满足查询条件的一份文档。默认为 false。

更新多个文档时，如果单个文档更新失败，则其他文档也不会更新。有关此行为的更多详情，请参阅多次更新失败。

collation

文档

可选。

指定用于操作的排序规则。

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

排序规则选项的语法如下：

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

指定排序规则时，locale 字段为必填字段；所有其他排序规则字段均为可选字段。有关字段的说明，请参阅排序规则文档。

如果未指定排序规则，但集合具有默认排序规则（请参阅 db.createCollection()），则操作将使用为集合指定的排序规则。

如果没有为收集或操作指定排序规则，MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。

您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果执行带排序的查找，则不能使用一种排序规则进行查找而另一种排序规则进行排序。

arrayFilters

阵列

可选。一个筛选器文档数组，确定要针对数组字段的更新操作修改哪些数组元素。

在更新文档中，使用 $[<identifier>] 筛选后的位置运算符来定义标识符，然后在数组筛选文档中引用该标识符。如果更新文档中未包含某一标识符，则无法获得该标识符的数组筛选文档。

<identifier> 必须以小写字母开头，且只能包含字母数字字符。

您可以在更新文档中多次包含相同的标识符；但对于更新文档中的每个不同标识符 ($[identifier])，您必须准确指定一个对应的数组筛选器文档。也就是说，不能为同一个标识符指定多个数组筛选器文档。例如，如果更新语句包含标识符 x（可能多次），则不能为 arrayFilters 指定以下内容，其中包括 x 的 2 个单独的筛选器文档：

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

但是，您可以在单个过滤器文档中的同一标识符上指定复合条件，例如以下示例：

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

有关示例，请参阅为数组更新操作指定 arrayFilters。

提示

文档或字符串

可选。指定用于支持查询谓词的索引的文档或字符串。

该选项可以采用索引规范文档或索引名称字符串。

如果指定不存在的索引，则操作出错。

有关示例，请参阅为更新操作指定 hint。

该命令返回一份包含操作状态的文档。例如：

{
   "ok" : 1,
   "nModified" : 0,
   "n" : 1,
   "upserted" : [
      {
         "index" : 0,
         "_id" : ObjectId("52ccb2118908ccd753d65882")
      }
   ]
}

有关输出字段的详细信息，请参阅输出。

访问控制

在使用 authorization 运行的部署中，用户必须具有包含以下特权的访问权限：

update 针对指定集合的操作。
find 针对指定集合的操作。
insert 针对指定集合的操作。

内置角色readWrite提供所需的特权。

行为

使用更新操作符表达式文档进行更新

更新语句字段 u 可以接受只包含更新运算符表达式的文档。例如：

updates: [
   {
     q: <query>,
     u: { $set: { status: "D" }, $inc: { quantity: 2 } },
      ...
   },
   ...
]

然后，update 命令仅更新文档中的相应字段。

使用替换文档进行更新

更新语句字段 u 字段可以接受替换文档，即该文档仅包含 field:value 表达式。例如：

updates: [
   {
      q: <query>,
      u: { status: "D", quantity: 4 },
      ...
   },
   ...
]

然后，update 命令将匹配文档替换为更新文档。update 命令只能替换单个匹配文档，即 multi 字段不能为 true。update 命令不会替换 _id 值。

多次更新失败

如果在multi参数设置为 true 的更新命令中单个文档无法更新，则不会再作为该命令的一部分更新任何文档。

例如，使用以下文档创建 members 集合：

db.members.insertMany( [
   { "_id" : 1, "member" : "Taylor", "status" : "pending", "points" : 1},
   { "_id" : 2, "member" : "Alexis", "status" : "enrolled", "points" : 59},
   { "_id" : 3, "member" : "Elizabeth", "status" : "enrolled", "points" : 34}
] )

以下操作在members集合上创建一个文档验证器，其规则是points值不能等于60 。

db.runCommand( {
   collMod: "members",
   validator: { points: { $ne: 60 } }
} )

此更新命令将每个文档的 points 字段增加 1。

db.runCommand(
 {
    update: "members",
    updates: [
     {
         q: {},
         u: { $inc: { points: 1 } },
         multi: true
     }
    ]
 }
)

运行该命令后，集合将包含以下文档：

{ _id: 1, member: 'Taylor', status: 'A', points: 2 }
{ _id: 2, member: 'Alexis', status: 'D', points: 59 }
{ _id: 3, member: 'Elizabeth', status: 'C', points: 34 }

更新命令更新了第一个文档的 points 值，但未能更新第二个文档，原因是验证器规则规定 points 值不能等于 60。第三个文档也未更新，原因是写入出错后就不会更新其他文档。

注意

如果更新了匹配文档的子集，例如当更新导致某些文档无法通过模式验证时，则update命令返回的nModified值可能不准确。

使用聚合管道进行更新

更新语句的 u 字段可以接受聚合管道 [ <stage1>, <stage2>, ... ]，用于指定要执行的修改。该管道可以由以下阶段组成：

使用聚合分析管道可以进行更具表现力的更新声明，例如基于当前字段值的Express条件更新或使用另一个字段的值更新一个字段。

例如：

updates: [
   {
      q: <query>,
      u: [
        { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
        { $unset: [ "misc1", "misc2" ] }
      ],
      ...
   },
   ...
]

注意

管道中使用的 $set 和 $unset 分别指聚合阶段 $set 和 $unset，而不是更新操作符 $set 和 $unset。

有关示例，请参阅使用聚合管道进行更新。

使用唯一索引进行 upsert

除非有唯一索引来防止重复，否则 upsert 可能会创建重复的文档。

以某一情况为例，其中不存在名为 Andy 的文档，且多个客户端大致会在同一时间发出以下命令：

db.runCommand(
   {
     update: "people",
     updates: [
       { q: { name: "Andy" }, u: { $inc: { score: 1 } }, multi: true, upsert: true }
     ]
   }
)

如果所有 update 操作在任何客户端成功插入数据之前完成了查询阶段，且 name 字段上没有唯一索引，则每个 update 操作都可能导致插入，从而使用 name: Andy 创建多个文档。

name 字段上的唯一索引可确保仅创建一个文档。通过此唯一索引，多个 update 操作此时便有如下行为：

只需执行一次 update 操作就能成功插入一个新文档。
其他 update 操作要么更新新插入的文档，要么由于唯一键冲突而失败。
为了让其他 update 操作更新新插入的文档，必须满足以下所有条件：
- 目标collection具有会导致重复键错误的唯一索引。
- 更新操作不是updateMany或multi是false 。
- 更新匹配条件为：
  - 单个相等谓词。例如 { "fieldA" : "valueA" }
  - 等式谓词的逻辑 AND。例如 { "fieldA" : "valueA", "fieldB" : "valueB" }
- 相等谓词中的字段与唯一索引键模式中的字段匹配。
- 更新操作不会修改唯一索引键模式中的任何字段。

下表显示了upsert操作的示例，当发生键冲突时，这些操作要么导致更新，要么失败。

唯一索引键模式

更新操作

结果

{ name : 1 }

db.people.updateOne(
   { name: "Andy" },
   { $inc: { score: 1 } },
   { upsert: true }
)

匹配文档的score字段递增 1。

{ name : 1 }

db.people.updateOne(
   { name: { $ne: "Joe" } },
   { $set: { name: "Andy" } },
   { upsert: true }
 )

操作失败是因为它修改了唯一索引键模式 ( name ) 中的字段。

{ name : 1 }

db.people.updateOne(
  { name: "Andy", email: "andy@xyz.com" },
  { $set: { active: false } },
  { upsert: true }
)

操作失败，因为等值谓词字段（ name 、 email ）与索引键字段（ name ）不匹配。

限制

对于 updates 数组中的每个更新元素，查询和更新大小（即 q 和u）之和必须小于或等于最大 BSON 文档大小。

updates 数组中更新语句的总数必须小于或等于最大批量大小。

文档验证

update 命令可为 bypassDocumentValidation 选项添加支持，以便在附带验证规则的集合中插入或更新文档时绕过文档验证。

分片集合

`upsert` 分片集合

要在分片集合上使用 update 和 multi: false，

如果未指定 upsert: true，则过滤器 q 必须在 _id 字段中包含等值匹配项或以单个分片为目标（例如通过包含分片键）。
如果您指定 upsert: true，则过滤器 q 必须在分片键上包含等值匹配项。
但是，分片集合中的文档可能缺少分片键字段。要定位缺失分片键的文档，可将 null 等值匹配与其他过滤条件（例如针对 _id 字段）结合使用。例如：
```
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
```

替换文档

替换文档时，update 会首先尝试使用查询过滤器来定位分片。如果该操作无法通过查询过滤器来定位单个分片，则会尝试通过替换文档来定位。

分片键修改

您可以更新文档的分片键值，除非分片键字段是不可变的 _id 字段。

要修改现有的分片键值（使用update）：

必须在 mongos 上运行。请勿直接对分片发出此操作。
你必须在事务中运行，或者以可重试写入的形式运行。
必须指定 multi: false。
你必须在完整分片键上包含相等查询过滤器。

提示

由于缺失的键值是作为 null 相等匹配的一部分返回的，因此为避免更新空值键，请酌情纳入其他查询条件（例如 _id 字段）。

另请参阅针对分片集合的 upsert。

缺少分片键

分片集合中的文档可能缺少分片键字段。要使用 update 来设置文档缺失的分片键，则必须在 mongos 上运行。请勿直接对分片发出此操作。

此外，以下要求也适用：

任务	要求
若要设为 `null`	可以指定 `multi: true`。如果指定了 `upsert: true`，则需要对完整的分片键使用相等筛选器。
要设置为非 `null` 值：	必须在事务中或作为可重试写入执行。必须指定 `multi: false`。如果满足以下任一条件，则需使用针对完整分片键的相等筛选器： `upsert: true`，或如果使用替换文档，并且新的分片键值属于另一个分片。

提示

由于缺失的键值是作为 null 相等匹配的一部分返回的，因此为避免更新空值键，请酌情纳入其他查询条件（例如 _id 字段）。

另请参阅：

事务

update 可以在分布式事务中使用。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

在 ACID 事务中进行更新或插入 (upsert)

如果分布式事务不是跨分片写入事务，则可以在该事务中创建集合和索引。

具有 upsert: true 的 update 可以在现有集合或不存在的集合上运行。如果在不存在的集合上运行，该操作将创建集合。

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

示例

更新一份文档的特定字段

使用更新操作符仅更新文档的指定字段。

例如，使用以下文档创建 members 集合：

db.members.insertMany([
   { _id: 1, member: "abc123", status: "Pending", points: 0, misc1: "note to self: confirm status", misc2: "Need to activate" },
   { _id: 2, member: "xyz123", status: "D", points: 59, misc1: "reminder: ping me at 100pts", misc2: "Some random comment" },
])

以下命令使用 $set 和 $inc 更新运算符，以更新文档的 status 和 points 字段，其中 member 等于 "abc123"：

db.runCommand(
   {
      update: "members",
      updates: [
         {
           q: { member: "abc123" }, u: { $set: { status: "A" }, $inc: { points: 1 } }
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

由于 <update> 文档未指定可选的 multi 字段，因此即使有多个文档符合 q 匹配条件，更新也只会修改一个文档。

返回的文档显示该命令找到并更新了单个文档。该命令会返回：

{ "n" : 1, "nModified" : 1, "ok" : 1, <additional fields if run on a replica set/sharded cluster> }

有关详细信息，请参阅输出。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 1, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "D", "points" : 59, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

更新多份文档的特定字段

使用更新运算符仅更新文档的指定字段，并在更新语句中包含设置为 true 的 multi 字段。

例如，members 集合包含以下文档：

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 1, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "D", "points" : 59, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

下面的命令使用 $set 和 $inc 更新操作符分别修改集合中所有文档的 status 和 points 字段：

db.runCommand(
   {
      update: "members",
      updates: [
         { q: { }, u: { $set: { status: "A" }, $inc: { points: 1 } }, multi: true }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

更新会修改与 q 字段中指定的查询匹配的所有文档，即与集合中的所有文档匹配的空查询。

返回的文档显示该命令找到并更新多个文档。对于副本集，命令会返回：

{ "n" : 2, "nModified" : 2, "ok" : 1,  <additional fields if run on a replica set/sharded cluster> }

有关详细信息，请参阅输出。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

使用聚合管道进行更新

update命令可以使用聚合管道进行更新。该管道可以由以下阶段组成：

使用聚合分析管道可以进行更具表现力的更新声明，例如基于当前字段值的Express条件更新或使用另一个字段的值更新一个字段。

示例 1

以下示例使用聚合分析管道使用文档中其他字段的值来修改字段。

members 集合包含以下文档：

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

假设您不想将 misc1 和 misc2 字段分开，而是将它们收集到新的 comments 字段中。以下更新操作使用 aggregation pipeline 来添加新的 comments 字段并删除集合中所有文档的 misc1 和 misc2 字段。

首先，将 status 字段设置为 "Modified" 并添加一个新字段 comments，其中包含另外两个字段 misc1 和 misc2 的当前内容。
其次，删除 misc1 和 misc2 字段。

db.runCommand(
   {
      update: "members",
      updates: [
         {
           q: { },
           u: [
              { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
              { $unset: [ "misc1", "misc2" ] }
           ],
           multi: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

注意

管道中使用的 $set 和 $unset 分别指聚合阶段 $set 和 $unset，而不是更新操作符 $set 和 $unset。

返回的文档显示该命令找到并更新多个文档。该命令会返回：

{ "n" : 2, "nModified" : 2, "ok" : 1, <additional fields if run on a replica set/sharded cluster> }

有关详细信息，请参阅输出。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "member" : "abc123", "status" : "Modified", "points" : 2, "comments" : [ "note to self: confirm status", "Need to activate" ] }
{ "_id" : 2, "member" : "xyz123", "status" : "Modified", "points" : 60, "comments" : [ "reminder: ping me at 100pts", "Some random comment" ] }

示例 2

聚合分析管道允许更新根据当前字段值执行条件更新以及使用当前字段值计算单独的字段值。

db.students.insertMany( [
   { "_id" : 1, "tests" : [ 95, 92, 90 ] },
   { "_id" : 2, "tests" : [ 94, 88, 90 ] },
   { "_id" : 3, "tests" : [ 70, 75, 82 ] }
] );

使用聚合分析管道，您可以使用计算出的平均成绩和字母等级来更新文档。

db.runCommand(
   {
      update: "students",
      updates: [
         {
           q: { },
           u: [
                 { $set: { average : { $avg: "$tests" } } },
                 { $set: { grade: { $switch: {
                                       branches: [
                                           { case: { $gte: [ "$average", 90 ] }, then: "A" },
                                           { case: { $gte: [ "$average", 80 ] }, then: "B" },
                                           { case: { $gte: [ "$average", 70 ] }, then: "C" },
                                           { case: { $gte: [ "$average", 60 ] }, then: "D" }
                                       ],
                                       default: "F"
                 } } } }
           ],
           multi: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

注意

管道中使用的 $set 指的是聚合阶段 $set，而不是更新操作符 $set。

第一个阶段：: $set 阶段根据 tests 字段的平均值计算新字段 average。有关 $avg 聚合运算符的更多信息，请参阅 $avg。
第二阶段: $set 阶段根据上一阶段计算的 average 字段计算新字段 grade。有关 $switch 聚合操作符的更多信息，请参阅 $switch。

返回的文档显示该命令找到并更新多个文档。该命令会返回：

{ "n" : 3, "nModified" : 3, "ok" : 1, <additional fields if run on a replica set/sharded cluster> }

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92.33333333333333, "grade" : "A" }
{ "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 90.66666666666667, "grade" : "A" }
{ "_id" : 3, "tests" : [ 70, 75, 82 ], "average" : 75.66666666666667, "grade" : "C" }

批量更新

以下示例对 members 集合执行多个更新操作：

db.runCommand(
   {
      update: "members",
      updates: [
         { q: { status: "P" }, u: { $set: { status: "D" } }, multi: true },
         { q: { _id: 5 }, u: { _id: 5, name: "abc123", status: "A" }, upsert: true }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

返回的文档显示该命令修改 10 文档并插入带有 _id 值 5 的文档。更多详情，请参阅输出。

{
   "ok" : 1,
   "nModified" : 10,
   "n" : 11,
   "upserted" : [
      {
         "index" : 1,
         "_id" : 5
      }
   ]
}

指定排序规则。

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

集合 myColl 包含以下文档：

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

以下操作包括排序规则选项：

db.runCommand({
   update: "myColl",
   updates: [
     { q: { category: "cafe", status: "a" }, u: { $set: { status: "Updated" } }, collation: { locale: "fr", strength: 1 } }
   ]
})

`arrayFilters`为数组更新操作指定

更新数组字段时，您可以指定 arrayFilters 确定要更新哪些数组元素。

更新匹配`arrayFilters` 条件的元素

使用以下文档创建集合 students：

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

要修改 grades 数组中大于或等于 100 的所有元素，请使用带有 arrayFilters 选项的筛选位置运算符 $[<identifier>]：

db.runCommand( {
   update: "students",
   updates: [
     { q: { grades: { $gte: 100 } }, u: { $set: { "grades.$[element]" : 100 } }, arrayFilters: [ { "element": { $gte: 100 } } ], multi: true}
   ]
} )

操作完成后，集合包含以下文档：

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

更新文档数组的特定元素

使用以下文档创建集合 students2：

db.students2.insertMany( [
   {
      "_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 字段的值，请将过滤后的位置操作符 $[<identifier>] 与 arrayFilters 结合使用：

db.runCommand({
   update: "students2",
   updates: [
     { q: { }, u: { $set: { "grades.$[elem].mean" : 100 } }, arrayFilters: [ { "elem.grade": { $gte: 85 } } ], multi: true }
   ]
})

操作完成后，集合有以下文档：

{
   "_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" : 100, "std" : 6 },
      { "grade" : 87, "mean" : 100, "std" : 3 },
      { "grade" : 85, "mean" : 100, "std" : 4 }
   ]
}

`hint`为更新操作指定

使用以下文档创建示例 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" }
])

在集合上创建以下索引：

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

以下更新操作明确提示使用索引 { status: 1 }：

注意

如果指定不存在的索引，则操作出错。

db.runCommand({
   update: "members",
   updates: [
     { q: { "points": { $lte: 20 }, "status": "P" }, u: { $set: { "misc1": "Need to activate" } }, hint: { status: 1 }, multi: true }
   ]
})

更新命令返回以下内容：

{ "n" : 3, "nModified" : 3, "ok" : 1 }

要查看使用的索引，请对操作运行 explain：

db.runCommand(
   {
     explain: {
       update: "members",
       updates: [
         { q: { "points": { $lte: 20 }, "status": "P" }, u: { $set: { "misc1": "Need to activate" } }, hint: { status: 1 }, multi: true }
       ]
     },
     verbosity: "queryPlanner"
   }
)

explain 不修改文档。

在`let` 选项或字段中使用变量`c`

版本 5.0 中的新增功能。

变量可以在 let 选项或 c 字段中定义，并在 updates 数组中访问。

注意

要使用变量筛选结果，您必须在 $expr 操作符中访问该变量。

创建集合 cakeFlavors：

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

以下示例在 let 中定义了 targetFlavor 和 newFlavor 变量，并使用这些变量将蛋糕口味从樱桃更改为橙子：

db.runCommand( {
   update: db.cakeFlavors.getName(),
   updates: [
      { q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
        u: [ { $set: { flavor: "$$newFlavor" } } ] }
   ],
   let : { targetFlavor: "cherry", newFlavor: "orange" }
} )

下一个示例在 c 中定义 targetFlavor 和 newFlavor 变量，并使用这些变量将蛋糕口味从巧克力更改为香草：

db.runCommand( {
   update: db.cakeFlavors.getName(),
   updates: [
      { q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
        u: [ { $set: { flavor: "$$newFlavor" } } ],
        c: { targetFlavor: "chocolate", newFlavor: "vanilla" } }
    ]
} )

输出

返回的文档包含以下字段的子集：

update.ok: 命令的状态。

update.n

update 命令接受一个文档更新数组，其中一些可以是更新插入 (upsert)。对于更新，n 是选定进行更新的文档数量。对于更新插入，插入文档的 n 为 1。服务器为所有更新和更新插入增加 n 值，并将总数返回为 update.n。

如果更新操作不会导致文档发生任何更改，例如，$set 表达式将数值更新为当前值，n 可大于 nModified.

update.nModified: 更新的文档数量。如果更新操作导致文档未发生变化，例如将字段的值设置为其当前值，则 nModified 可以小于 n。
注意
如果更新了匹配文档的子集，例如当更新导致某些文档无法通过模式验证时，则update命令返回的nModified值可能不准确。

update.upserted

文档数组，包含通过更新插入的每个文档的信息，更新时使用 upsert: true。

每个文档均包含以下信息：

update.upserted.index: 一个整数，用于标识 updates 数组中带有 upsert:true 语句的更新，该数组使用从零开始的索引。

update.upserted._id: 所添加文档的 _id 值。

update.writeErrors

包含在更新操作过程中遇到的任何错误的相关信息的文档数组。writeErrors 数组包含每个出错的更新语句的错误文档。

每个错误文档都包含以下字段：

update.writeErrors.index: 一个整数，用于标识 updates 数组中的更新语句，该数组使用从零开始的索引。

update.writeErrors.code: 标识错误的整数值。

update.writeErrors.errmsg: 错误描述。

update.writeConcernError

描述与写关注（write concern）相关的错误的文档。

在版本7.1中进行了更改：在update }mongos 上执行时，即使出现一个或多个写入错误，也始终会报告写关注错误。

在以前的版本中，发生写入错误可能会导致update不报告写关注（write concern）错误。

writeConcernError文档包含以下字段：

update.writeConcernError.code: 一个整数值，用于标识写关注错误原因。

update.writeConcernError.errmsg: 写关注错误原因的描述。

update.writeConcernError.errInfo.writeConcern

用于相应操作的写关注对象。有关写关注对象字段的信息，请参阅写关注规范。

写关注对象还可能包含以下字段，指示写关注的来源：

update.writeConcernError.errInfo.writeConcern.provenance

一个表示写关注来源（称为写关注provenance）的字符串值。下表显示该字段的可能值及其有效位数：

来源	说明
`clientSupplied`	应用程序中指定了写关注。
`customDefault`	写入关注源自自定义的默认值。请参阅 `setDefaultRWConcern`。
`getLastErrorDefaults`	写关注源自副本集的 `settings.getLastErrorDefaults` 字段。
`implicitDefault`	在没有所有其他写入关注规范的情况下，写入关注源自服务器。

除了上述特定的更新返回字段外，db.runCommand() 还包括其他信息：

针对副本集：optime、electionId、$clusterTime 和 operationTime。
对于分片集群：operationTime 和 $clusterTime。

有关这些字段的详细信息，请参阅 db.runCommand Response。

以下是成功执行更新或插入的 update 命令返回的示例文档：

{
   "ok" : 1,
   "nModified" : 0,
   "n" : 1,
   "upserted" : [
      {
         "index" : 0,
         "_id" : ObjectId("52ccb2118908ccd753d65882")
      }
   ]
}

以下是涉及三个更新语句的批量更新返回的示例文档，其中一个更新语句成功，另外两个更新语句出错：

{
   "ok" : 1,
   "nModified" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 16837,
         "errmsg" : "The _id field cannot be changed from {_id: 1.0} to {_id: 5.0}."
      },
      {
         "index" : 2,
         "code" : 16837,
         "errmsg" : "The _id field cannot be changed from {_id: 2.0} to {_id: 6.0}."
      },
   ]
}

后退

resetError

来年

查询计划缓存

定义

提示

兼容性

注意

语法

命令字段

更新语句

返回：

访问控制

行为

使用更新操作符表达式文档进行更新

使用替换文档进行更新

多次更新失败

注意

使用聚合管道进行更新

注意

使用唯一索引进行 upsert

限制

文档验证

分片集合

upsert 分片集合

替换文档

分片键修改

提示

缺少分片键

提示

事务

重要

在 ACID 事务中进行更新或插入 (upsert)

提示

另请参阅：

写关注和事务

示例

更新一份文档的特定字段

更新多份文档的特定字段

使用聚合管道进行更新

示例 1

注意

示例 2

注意

批量更新

指定排序规则。

arrayFilters为数组更新操作指定

更新匹配arrayFilters 条件的元素

更新文档数组的特定元素

hint为更新操作指定

注意

在let 选项或 字段中使用变量c

注意

输出

注意

`upsert` 分片集合

`arrayFilters`为数组更新操作指定

更新匹配`arrayFilters` 条件的元素

`hint`为更新操作指定

在`let` 选项或字段中使用变量`c`