update

On this page本页内容

Definition定义

update

The update command modifies documents in a collection. update命令修改集合中的文档。A single update command can contain multiple update statements. 一个update命令可以包含多个更新语句。The update methods provided by the MongoDB drivers use this command internally.MongoDB驱动程序提供的更新方法在内部使用此命令。

The mongo shell provides the following helper methods:mongo shell提供以下帮助程序方法：

Syntax语法

Changed in version 4.2.在版本4.2中更改。

The update command has the following syntax:update命令语法如下所示：

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

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Type类型Description描述
update string The name of the target collection.目标集合的名称。
updates array An array of one or more update statements to perform on the named collection. 要对命名集合执行的一个或多个update语句的数组。For details of the update statements, see Update Statements.有关更新语句的详细信息，请参阅update语句。
ordered boolean Optional.可选。If true, then when an update statement fails, return without performing the remaining update statements. 如果为true，则当update语句失败时，返回而不执行其余的update语句。If false, then when an update fails, continue with the remaining update statements, if any. 如果为false，则当更新失败时，继续执行剩余的update语句（如果有）。Defaults to true.默认为true。
writeConcern document

Optional.可选。A document expressing the write concern of the update command. 表示update命令的写关注点的文档。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.要将写关注点用于事务，请参阅事务和写关注点。

bypassDocumentValidation boolean

Optional.可选。Enables update to bypass document validation during the operation. 启用update以在操作期间绕过文档验证。This lets you update documents that do not meet the validation requirements.这允许您更新不符合验证要求的文档。

New in version 3.2.版本3.2中的新功能。

comment any

Optional.可选。A user-provided comment to attach to this command. 用户提供了要附加到此命令的注释。Once set, this comment appears alongside records of this command in the following locations:设置后，此注释将与此命令的记录一起出现在以下位置：

A comment can be any valid BSON type (string, integer, object, array, etc).注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。

New in version 4.4.版本4.4中的新功能。

Update Statements更新语句

Each element of the updates array is an update statement document. updates数组的每个元素都是一个update语句文档。Each document contains the following fields:每个文档都包含以下字段：

Field字段Type类型Description描述
q document

The query that matches documents to update. 匹配要更新的文档的查询。Use the same query selectors as used in the find() method.使用与find()方法相同的查询选择器。

u document or pipeline文档或管道

The modifications to apply.要应用的修改。

The value can be either:该值可以是：

For details, see Behavior.有关详细信息，请参阅行为。

upsert boolean

Optional. 可选。If true, perform an insert if no documents match the query. 如果为true，则在没有与查询匹配的文档时执行插入。If both upsert and multi are true and no documents match the query, the update operation inserts only a single document.如果upsert和multi都为true，并且没有与查询匹配的文档，则更新操作只插入一个文档。

multi boolean Optional.可选。If true, updates all documents that meet the query criteria. 如果为true，则更新满足查询条件的所有文档。If false, limit the update to one document that meet the query criteria. 如果为false，则将更新限制为满足查询条件的一个文档。Defaults to false.默认为false。
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. 指定排序规则时，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.例如，不能为每个字段指定不同的排序规则，或者如果使用排序执行查找，则不能对查找使用一种排序规则，对排序使用另一种排序规则。

New in version 3.4.版本3.4中的新功能。

arrayFilters array

Optional.可选。An array of filter documents that determines which array elements to modify for an update operation on an array field.筛选文档的数组，用于确定要为数组字段上的更新操作修改哪些数组元素。

In the update document, use the $[<identifier>] filtered positional operator to define an identifier, which you then reference in the array filter documents. 在更新文档中，使用筛选位置运算符$[<identifier>]定义一个标识符，然后在数组筛选文档中引用该标识符。You cannot have an array filter document for an identifier if the identifier is not included in the update document.如果标识符未包含在更新文档中，则不能使用标识符的数组筛选器文档。

Note

The <identifier> must begin with a lowercase letter and contain only alphanumeric characters.<identifier>必须以小写字母开头，并且只包含字母数字字符。

You can include the same identifier multiple times in the update document; however, for each distinct identifier ($[identifier]) in the update document, you must specify exactly one corresponding array filter document. 您可以在更新文档中多次包含同一标识符；但是，对于更新文档中的每个不同标识符（$[identifier]），必须指定一个对应的数组筛选器文档。That is, you cannot specify multiple array filter documents for the same identifier. 也就是说，不能为同一标识符指定多个数组筛选器文档。For example, if the update statement includes the identifier x (possibly multiple times), you cannot specify the following for arrayFilters that includes 2 separate filter documents for x:例如，如果update语句包含标识符x（可能多次），则不能为包含x的两个单独筛选文档的arrayFilters指定以下内容：

// INVALID

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

However, you can specify compound conditions on the same identifier in a single filter document, such as in the following examples:但是，您可以在单个筛选文档中对同一标识符指定复合条件，如以下示例中所示：

// 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 } }
]

For examples, see Specify arrayFilters for Array Update Operations.有关示例，请参阅为数组更新操作指定数组筛选器。

New in version 3.6.版本3.6中的新功能。

hint Document or string文档或字符串

Optional. 可选。A document or string that specifies the index to use to support the query predicate.指定用于支持查询谓词的索引的文档或字符串。

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 Update Operations.有关示例，请参阅指定更新操作提示。

New in version 4.2.版本4.2中的新功能。

Returns返回

The command returns a document that contains the status of the operation. 该命令返回一个包含操作状态的文档。For example:例如：

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

For details of the output fields, see Output.有关输出字段的详细信息，请参阅输出。

Access Control访问控制

On deployments running with authorization, the user must have access that includes the following privileges:在使用authorization运行的部署中，用户必须具有包括以下权限的访问权限：

The built-in role readWrite provides the required privileges.内置角色readWrite提供所需的权限。

Behavior行为

Update with an Update Operator Expressions Document使用更新运算符表达式文档进行更新

The update statement field u can accept a document that only contains update operator expressions. update语句字段u可以接受仅包含更新运算符表达式的文档。For example:例如：

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

Then, the update command updates only the corresponding fields in the document.然后，update命令只更新文档中相应的字段。

Update with a Replacement Document用替换文档更新

The update statement field u field can accept a replacement document, i.e. the document contains only field:value expressions. update语句字段u字段可以接受替换文档，即该文档只包含field:value表达式。For example:例如：

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

Then the update command replaces the matching document with the update document. 然后，update命令将匹配的文档替换为更新文档。The update command can only replace a single matching document; i.e. the multi field cannot be true. update命令只能替换单个匹配的文档；亦即，多字段不可能是真的。The update command does not replace the _id value.update命令不会替换_id值。

Update with an Aggregation Pipeline使用聚合管道进行更新

Starting in MongoDB 4.2, the update statement field u field can accept an aggregation pipeline [ <stage1>, <stage2>, ... ] that specifies the modifications to perform. 从MongoDB 4.2开始，update语句字段u字段可以接受聚合管道[ <stage1>, <stage2>, ... ]指定要执行的修改。The pipeline can consist of the following stages:管道可包括以下阶段：

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).使用聚合管道可以实现更具表现力的update语句，例如基于当前字段值表达条件更新，或者使用另一个字段的值更新一个字段。

For example:例如：

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

Note

The $set and $unset used in the pipeline refers to the aggregation stages $set and $unset respectively, and not the update operators $set and $unset.管道中使用的$set和$unset分别指的是聚合阶段$set和$unset，而不是更新运算符$set和$unset。

For examples, see Update with Aggregation Pipeline.有关示例，请参阅使用聚合管道更新。

Limits限制

For each update element in the updates array, the sum of the query and the update sizes (i.e. q and u ) must be less than or equal to the maximum BSON document size.对于updates数组中的每个更新元素，查询和更新大小（即q和u）之和必须小于或等于maximum BSON document size。

The total number of update statements in the updates array must be less than or equal to the maximum bulk size.updates数组中update语句的总数必须小于或等于最大批量大小。

Document Validation文件验证

The update command adds support for the bypassDocumentValidation option, which lets you bypass document validation when inserting or updating documents in a collection with validation rules.update命令添加了对bypassDocumentValidation选项的支持，该选项允许在使用验证规则插入或更新集合中的文档时绕过文档验证。

Sharded Collections碎片集合

upsert on a Sharded Collection分片集合上的upsert

To use update with multi: false on a sharded collection,

  • If you do not specify upsert: true, the filter q must either include an equality match on the _id field or target a single shard (such as by including the shard key).
  • If you specify upsert: true, the filter q must include an equality match on the shard key.

    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

Replace Document替换文件

Starting in MongoDB 4.2, when replacing a document, update attempts to target a shard, first by using the query filter. 从MongoDB 4.2开始，在替换文档时，update会首先使用查询筛选器尝试将碎片作为目标。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 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字段。Before MongoDB 4.2, a document’s shard key field value is immutable.在MongoDB 4.2之前，文档的shard key字段值是不可变的。

To modify the existing shard key value with update:要使用update修改现有的分片键值，请执行以下操作：

  • 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 specify multi: false.
  • You must include an equality query filter on the full shard key.

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.由于缺少的键值是作为空相等匹配的一部分返回的，为了避免更新空值键值，请酌情包括其他查询条件（例如在_id字段上）。

See also upsert on a Sharded Collection.另请参见在分片集合上upsert。

Missing Shard Key缺少碎片键

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. To use update 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:此外，以下要求也适用：

 Requirements要求
To set to null
  • Can specify multi: true.可以指定multi:true。
  • 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.
  • Must specify multi: false.必须指定multi:false。
  • Requires equality filter on the full shard key if either:如果出现以下情况之一，则需要对完整分片键进行相等筛选：
    • upsert: true, or
    • if using a replacement document and 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.由于缺少的键值是作为空相等匹配的一部分返回的，为了避免更新空值键值，请酌情包括其他查询条件（例如在_id字段上）。

See also:

Transactions事务

update 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.有关其他事务使用注意事项（如运行时限制和oplog大小限制），请参阅生产注意事项。

Upsert within Transactions在事务中插入

Starting in MongoDB 4.4 with feature compatibility version (fcv) "4.4", you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.

As such, for the feature compatibility version (fcv) is "4.4" or greater, update with upsert: true can be run against an existing collection or a non-existing collection. If run against a non-existing collection, the operation creates the collection.

If the feature compatibility version (fcv) is "4.2" or less, the operation must be against an existing collection.如果功能兼容版本（fcv）为"4.2"或更低，则操作必须针对现有集合。

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示例

Update Specific Fields of One Document更新一个文档的特定字段

Use update operators to update only the specified fields of a document.使用更新运算符仅更新文档的指定字段。

For example, create a members collection with the following documents:例如，使用以下文档创建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" },
])

The following command uses the $set and $inc update operators to update the status and the points fields of a document where the member equals "abc123":

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

Because <update> document does not specify the optional multi field, the update only modifies one document, even if more than one document matches the q match condition.因为<update>文档没有指定可选的multi字段，所以更新只修改一个文档，即使有多个文档符合q匹配条件。

The returned document shows that the command found and updated a single document. 返回的文档显示命令找到并更新了一个文档。The command returns:命令返回：

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

See Output for details.有关详细信息，请参阅输出。

After the command, the collection contains the following documents:命令发出后，集合包含以下文档：

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

Update Specific Fields of Multiple Documents更新多个文档的特定字段

Use update operators to update only the specified fields of a document, and include the multi field set to true in the update statement.

For example, a members collection contains the following documents:例如，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" }

The following command uses the $set and $inc update operators to modify the status and the points fields respectively of all documents in the collection:

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

The update modifies all documents that match the query specified in the q field, namely the empty query which matches all documents in the collection.更新将修改与q字段中指定的查询匹配的所有文档，即与集合中的所有文档匹配的空查询。

The returned document shows that the command found and updated multiple documents. 返回的文档显示命令找到并更新了多个文档。 For a replica set, the command returns:对于副本集，该命令返回：

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

See Output for details.有关详细信息，请参阅输出。

After the command, the collection contains the following documents:命令发出后，集合包含以下文档：

{ "_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 with Aggregation Pipeline使用聚合管道更新

Starting in MongoDB 4.2, the update command can use an aggregation pipeline for the update. The pipeline can consist of the following stages:

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).使用聚合管道可以实现更具表现力的update语句，例如基于当前字段值表达条件更新，或者使用另一个字段的值更新一个字段。

Example 1例1

The following examples uses the aggregation pipeline to modify a field using the values of the other fields in the document.以下示例使用聚合管道使用文档中其他字段的值修改字段。

A members collection contains the following documents: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" }

Assume that instead of separate misc1 and misc2 fields, you want to gather these into a new comments field. 假设不需要单独的misc1和misc2字段，而是希望将它们收集到一个新的comments字段中。The following update operation uses an aggregation pipeline to add the new comments field and remove the misc1 and misc2 fields for all documents in the collection.以下更新操作使用聚合管道添加新comments字段，并删除集合中所有文档的misc1和misc2字段。

  • First, set the status field to "Modified" and add a new field comments that contains the current contents of two other fields misc1 and misc2 fields.
  • Second, remove the misc1 and misc2 fields.其次，删除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 }
   }
)

Note

The $set and $unset used in the pipeline refers to the aggregation stages $set and $unset respectively, and not the update operators $set and $unset.

The returned document shows that the command found and updated multiple documents. 返回的文档显示命令找到并更新了多个文档。 The command returns:命令返回：

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

See Output for details.有关详细信息，请参阅输出。

After the command, the collection contains the following documents:命令发出后，集合包含以下文档：

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

Example 2例2

The aggregation pipeline allows the update to perform conditional updates based on the current field values as well as use current field values to calculate a separate field value.聚合管道允许更新基于当前字段值执行条件更新，并使用当前字段值计算单独的字段值。

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

Using an aggregation pipeline, you can update the documents with the calculated grade average and letter grade.使用聚合管道，可以使用计算出的平均成绩和字母成绩更新文档。

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 }
   }
)

Note

The $set used in the pipeline refers to the aggregation stage $set, and not the update operators $set.

First Stage
The $set stage calculates a new field average based on the average of the tests field. See $avg for more information on the $avg aggregation operator.
Second Stage
The $set stage calculates a new field grade based on the average field calculated in the previous stage. See $switch for more information on the $switch aggregation operator.

The returned document shows that the command found and updated multiple documents. 返回的文档显示命令找到并更新了多个文档。The command returns:命令返回：

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

After the command, the collection contains the following documents:命令发出后，集合包含以下文档：

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

Bulk Update批量更新

The following example performs multiple update operations on the members collection:以下示例对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 }
   }
)

The returned document shows that the command modified 10 documents and inserted a document with the _id value 5. 返回的文档显示，该命令修改了10个文档，并插入了一个_id值为5的文档。See Output for details.有关详细信息，请参阅输出。

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

Specify Collation指定排序规则

New in version 3.4.版本3.4中的新功能。

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: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:以下操作包括排序规则选项：

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

Specify arrayFilters for Array Update Operations为数组更新操作指定arrayFilters

New in version 3.6.版本3.6中的新功能。

Starting in MongoDB 3.6, when updating an array field, you can specify arrayFilters that determine which array elements to update.从MongoDB 3.6开始，在更新数组字段时，可以指定确定要更新哪些数组元素的arrayFilters。

Update Elements Match arrayFilters Criteria更新元素匹配arrayFilters条件

Create a collection students with the following documents:创建一个包含以下文档的students集合：

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

To modify all elements that are greater than or equal to 100 in the grades array, use the filtered positional operator $[<identifier>] with the arrayFilters option:

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

After the operation, the collection contains the following documents:操作完成后，集合包含以下文档：

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

Update Specific Elements of an Array of Documents更新文档数组的特定元素

Create a collection students2 with the following documents:使用以下文档创建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 }
      ]
   }
]);

To modify the value of the mean field for all elements in the grades array where the grade is greater than or equal to 85, use the filtered positional operator $[<identifier>] with the arrayFilters:

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

After the operation, the collection has the following documents:操作完成后，集合具有以下文档：

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

Specify hint for Update Operations指定更新操作的hint

New in version 4.2.版本4.2中的新功能。

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.runCommand({
   update: "members",
   updates: [
     { q: { "points": { $lte: 20 }, "status": "P" }, u: { $set: { "misc1": "Need to activate" } }, hint: { status: 1 }, multi: true }
   ]
})

The update command returns the following:update命令返回以下内容：

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

To see the index used, run explain on the operation:要查看使用的索引，请对操作运行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"
   }
)

The explain does not modify the documents.explain不会修改文档。

Output输出

The returned document contains a subset of the following fields:返回的文档包含以下字段的子集：

update.ok

The status of the command.命令的状态。

update.n

The number of documents selected for update. 选择要更新的文档数。If the update operation results in no change to the document, e.g. $set expression updates the value to the current value, n can be greater than nModified.如果更新操作不会导致文档发生任何更改，例如，$set表达式将值更新为当前值，则n可以大于nModified。

update.nModified

The number of documents updated. 更新的文档数。If the update operation results in no change to the document, such as setting the value of the field to its current value, nModified can be less than n.如果更新操作不会导致文档发生任何更改，例如将字段的值设置为其当前值，则nModified可以小于n。

update.upserted

An array of documents that contains information for each document inserted through the update with upsert: true.文档数组，其中包含通过upsert:true更新插入的每个文档的信息。

Each document contains the following information:每个文档都包含以下信息：

update.upserted.index

An integer that identifies the update with upsert:true statement in the updates array, which uses a zero-based index.在updates数组中使用upsert:true语句标识更新的整数，updates数组使用从零开始的索引。

update.upserted._id

The _id value of the added document.添加文档的_id值。

update.writeErrors

An array of documents that contains information regarding any error encountered during the update operation. 包含有关更新操作期间遇到的任何错误的信息的文档数组。The writeErrors array contains an error document for each update statement that errors.writeErrors数组包含每个发生错误的update语句的错误文档。

Each error document contains the following fields:每个错误文档都包含以下字段：

update.writeErrors.index

An integer that identifies the update statement in the updates array, which uses a zero-based index.一个整数，用于标识updates数组中的update语句，该数组使用基于零的索引。

update.writeErrors.code

An integer value identifying the error.标识错误的整数值。

update.writeErrors.errmsg

A description of the error.对错误的描述。

update.writeConcernError

Document that describe error related to write concern and contains the field:描述与写入问题相关的错误的文档，包含以下字段：

update.writeConcernError.code

An integer value identifying the cause of the write concern error.标识写入问题错误原因的整数值。

update.writeConcernError.errmsg

A description of the cause of the write concern error.对写入问题错误原因的描述。

update.writeConcernError.errInfo.writeConcern

New in version 4.4.版本4.4中的新功能。

The write concern object used for the corresponding operation. 用于相应操作的写关注点对象。For information on write concern object fields, see Write Concern Specification.有关写入关注点对象字段的信息，请参阅写入关注点规范。

The write concern object may also contain the following field, indicating the source of the write concern:写关注点对象还可能包含以下字段，指示写关注点的来源：

update.writeConcernError.errInfo.writeConcern.provenance

A string value indicating where the write concern originated (known as write concern provenance). 一个字符串值，指示写关注点的来源（称为写关注点provenance）。The following table shows the possible values for this field and their significance:下表显示了该字段的可能值及其重要性：

ProvenanceDescription描述
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.写入问题源于副本集的settings.getLastErrorDefaults字段。
implicitDefault The write concern originated from the server in absence of all other write concern specifications.在没有所有其他写关注规范的情况下，写关注源于服务器。

In addition to the aforementioned update specific return fields, the db.runCommand() includes additional information:除了上述特定于更新的返回字段外，db.runCommand()包含其他信息：

See db.runCommand Response for details on these fields.有关这些字段的详细信息，请参阅db.runCommand响应。

The following is an example document returned for a successful update command that performed an upsert:以下是成功执行upsert的update命令返回的示例文档：

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

The following is an example document returned for a bulk update involving three update statements, where one update statement was successful and two other update statements encountered errors:以下是批量更新返回的示例文档，涉及三条update语句，其中一条update语句成功，另两条update语句遇到错误：

{
   "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}."
      },
   ]
}