db.collection.updateOne()

On this page本页内容

Definition定义

db.collection.updateOne(filter, update, options)

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. 本页记录了mongo shell方法，未提及MongoDB Node.js驱动程序（或任何其他驱动程序）方法。For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.有关相应的MongoDB驱动程序API，请参阅特定的MongoDB驱动程序文档。

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

Updates a single document within the collection based on the filter.根据筛选器更新集合中的单个文档。

Syntax语法

The updateOne() method has the following syntax:语法如下所示：

db.collection.updateOne(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     arrayFilters: [ <filterdocument1>, ... ],
     hint:  <document|string>        // Available starting in MongoDB 4.2.1
   }
)

Parameters参数

The db.collection.updateOne() method takes the following parameters:db.collection.updateOne()方法采用以下参数：

Parameter参数Type类型Description描述
filter document

The selection criteria for the update. 更新的选择标准。The same query selectors as in the find() method are available.与find()方法中相同的查询选择器可用。

Specify an empty document { } to update the first document returned in the collection.指定一个空文档{ }，以更新集合中返回的第一个文档。

update document or pipeline

The modifications to apply. 要应用的修改。Can be one of the following:可以是以下内容之一：

Update document更新文档

Contains only update operator expressions.仅包含更新运算符表达式。

For more information, see Update with an Update Operator Expressions Document有关更多信息，请参阅使用更新运算符表达式更新文档

Aggregation pipeline聚合管道 (Starting in MongoDB 4.2从MongoDB 4.2开始)

Contains only the following aggregation stages:仅包含以下聚合阶段：

For more information, see Update with an Aggregation Pipeline.有关更多信息，请参阅使用聚合管道更新。

To update with a replacement document, see db.collection.replaceOne().要使用替换文档进行更新，请参阅db.collection.replaceOne()。

upsert boolean

Optional.可选。When true, updateOne() either:如果为true，则updateOne()可以：

  • Creates a new document if no documents match the filter. 如果没有与filter匹配的文档，则创建新文档。For more details see upsert behavior.有关更多详细信息，请参阅upsert行为。
  • Updates a single document that matches the filter.更新与filter匹配的单个文档。

To avoid multiple upserts, ensure that the filter fields are uniquely indexed.要避免多个Upsert，请确保filter字段的索引是唯一的。

Defaults to false.默认为false。

writeConcern document

Optional.可选。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.要将写关注点用于事务，请参阅事务和写关注点。

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选项语法如下所示：

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 determine 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:例如，如果更新语句包含标识符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 an 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.1.在4.2.1版中新增。

Returns返回值

The method returns a document that contains:该方法返回一个包含以下内容的文档：

  • matchedCount containing the number of matched documents包含匹配文档的数量
  • modifiedCount containing the number of modified documents包含已修改文档的数量
  • upsertedId containing the _id for the upserted document.包含所插入文档的_id。
  • A boolean acknowledged as true if the operation ran with write concern or false if write concern was disabled如果操作以写关注点运行，则布尔值acknowledged为true；如果写关注点被禁用，则布尔值acknowledged为false

Access Control访问控制

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

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

Behavior行为

Updates a Single Document更新单个文档

db.collection.updateOne() finds the first document that matches the filter and applies the specified update modifications.查找与筛选器匹配的第一个文档，并应用指定的更新修改。

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

For the update specifications, the db.collection.updateOne() method can accept a document that only contains update operator expressions.对于更新规范，db.collection.updateOne()方法可以接受只包含更新运算符表达式的文档。

For example:例如：

db.collection.updateOne(
   <query>,
{ $set: { status: "D" }, $inc: { quantity: 2 } },   ...
)

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

Starting in MongoDB 4.2, the db.collection.updateOne() method can accept an aggregation pipeline [ <stage1>, <stage2>, ... ] that specifies the modifications to perform. 从MongoDB 4.2开始，db.collection.updateOne()方法可以接受聚合管道[ <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:例如：

db.collection.updateOne(
   <query>,
[{ $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.有关示例，请参阅使用聚合管道更新。

Upsert

If upsert: true and no documents match the filter, db.collection.updateOne() creates a new document based on the filter criteria and update modifications. 如果upsert:true且没有与filter匹配的文档，db.collection.updateOne()将根据filter条件和update修改创建一个新文档。See Update with Upsert.请参阅使用Upsert更新。

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

Capped Collection封顶集合

If an update operation changes the document size, the operation will fail.如果更新操作更改了文档大小，则操作将失败。

Sharded Collections碎片集合

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

To use db.collection.updateOne() on a sharded collection:要在分片集合上使用db.collection.updateOne()：

  • If you don’t specify upsert: true, you must include an exact match on the _id field or target a single shard (such as by including the shard key in the filter).如果未指定upsert:true，则必须在_id字段中包含精确匹配项，或将单个碎片作为目标（例如，通过在筛选器中包含碎片键）。
  • If you specify upsert: true, the filter must include the shard key.如果指定upsert:true，则筛选器必须包含碎片密钥。

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开始，可以更新文档的shard key值，除非分片键字段是不可变的_id字段。Before MongoDB 4.2, 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。Take precaution to avoid accidentally removing the shard key when changing a document’s shard key value.采取预防措施，以避免在更改文档的shard key值时意外删除shard key。

To modify the existing shard key value with db.collection.updateOne():要使用db.collection.updateOne()修改现有切分键值，请执行以下操作：

  • You must run on a mongos. 你必须在mongos上运行。Do not issue the operation directly on the shard.不要直接在分片上发布操作。
  • You must run either in a transaction or as a retryable write.您必须在事务中运行，或作为可重试写入运行。
  • You must include an equality filter on the full shard key.必须在完整分片键上包含相等筛选器。

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

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

 Requirements要求
To set to null设置为null
  • Requires equality filter on the full shard key if upsert: true.如果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 upsert: true.如果upsert:true，则需要对完整分片键进行相等筛选。

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:另见：

Explainability解释能力

updateOne() is not compatible with 与db.collection.explain().不兼容。

Use update() instead.请改用update()。

Transactions事务

db.collection.updateOne() 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在事务中Upsert

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.从功能兼容版本（fcv）"4.4"的MongoDB 4.4开始，如果事务不是跨切分写入事务，则可以在多文档事务中创建集合和索引。

As such, for the feature compatibility version (fcv) is "4.4" or greater, db.collection.updateOne() with upsert: true can be run against an existing collection or a non-existing collection. 因此，对于功能兼容性版本（fcv）为"4.4"或更高版本的，可以对现有集合或不存在的集合运行带有upsert:true的db.collection.updateOne()。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 using Update Operator Expressions使用更新运算符表达式更新

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 updates a single document where name: "Central Perk Cafe" with the violations field:以下操作将更新一个name为"Central Perk Cafe"的文档，其中包含violations字段：

try {
   db.restaurant.updateOne(
      { "name" : "Central Perk Cafe" },
      { $set: { "violations" : 3 } }
   );
} 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 Update with Upsert请参阅使用Upsert更新

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

Starting in MongoDB 4.2, the db.collection.updateOne() can use an aggregation pipeline for the update. 从MongoDB 4.2开始，db.collection.updateOne()可以使用聚合管道进行更新。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.以下示例使用聚合管道使用文档中其他字段的值修改字段。

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

db.members.insertMany([
    { "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
    { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, comments: [ "reminder: ping me at 100pts", "Some random comment" ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
])

Assume that instead of separate misc1 and misc2 fields in the first document, you want to gather these into a comments field, like the second document. 假设您不想在第一个文档中单独显示misc1和misc2字段，而是希望将它们收集到一个comments字段中，就像第二个文档一样。The following update operation uses an aggregation pipeline to:以下更新操作使用聚合管道来：

  • add the new comments field and set the lastUpdate field.添加新comments字段并设置lastUpdate字段。
  • remove the misc1 and misc2 fields for all documents in the collection.删除集合中所有文档的misc1和misc2字段。
db.members.updateOne(
   { _id: 1 },
   [
      { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ], lastUpdate: "$$NOW" } },
      { $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。

First Stage第一阶段

The $set stage:$set阶段：

  • creates a new array field comments whose elements are the current content of the misc1 and misc2 fields and创建一个新的数组字段comments，其元素是misc1和misc2字段的当前内容，以及
  • sets the field lastUpdate to the value of the aggregation variable NOW. 将字段lastUpdate设置为聚合变量NOW的值。The aggregation variable NOW resolves to the current datetime value and remains the same throughout the pipeline. 聚合变量NOW解析为当前日期时间值，并在整个管道中保持不变。To access aggregation variables, prefix the variable with double dollar signs $$ and enclose in quotes.要访问聚合变量，请在变量前面加上双美元符号$$并用引号括起来。
Second Stage第二阶段
The $unset stage removes the misc1 and misc2 fields.$unset阶段删除misc1和misc2字段。

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

{ "_id" : 1, "member" : "abc123", "status" : "Modified", "points" : 2, "lastUpdate" : ISODate("2020-01-23T05:21:59.321Z"), "comments" : [ "note to self: confirm status", "Need to activate" ] }
{ "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "comments" : [ "reminder: ping me at 100pts", "Some random comment" ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }

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.聚合管道允许更新基于当前字段值执行条件更新，并使用当前字段值计算单独的字段值。

For example, create a students3 collection with the following documents:例如，使用以下文档创建students3集合：

db.students3.insert([
   { "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
   { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
   { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
]);

The third document _id: 3 is missing the average and grade fields. 第三个文档_id:3缺少average和grade字段。Using an aggregation pipeline, you can update the document with the calculated grade average and letter grade.使用聚合管道，可以使用计算出的平均成绩和字母成绩更新文档。

db.students3.updateOne(
   { _id: 3 },
   [
     { $set: { average: { $trunc: [  { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } },
     { $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"
     } } } }
   ]
)

Note

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

First Stage第一阶段

The $set stage:$set阶段：

  • calculates a new field average based on the average of the tests field. 基于test字段的平均值计算新字段average。See $avg for more information on the $avg aggregation operator and $trunc for more information on the $trunc truncate aggregation operator.有关$avg聚合运算符的更多信息，请参阅$avg；有关$trunc截断聚合运算符的更多信息，请参见$trunc。
  • sets the field lastUpdate to the value of the aggregation variable NOW. 将字段lastUpdate设置为聚合变量NOW的值。The aggregation variable NOW resolves to the current datetime value and remains the same throughout the pipeline. 聚合变量NOW解析为当前日期时间值，并在整个管道中保持不变。To access aggregation variables, prefix the variable with double dollar signs $$ and enclose in quotes.要访问聚合变量，请在变量前面加上双美元符号$$并用引号括起来。
Second Stage第二阶段
The $set stage calculates a new field grade based on the average field calculated in the previous stage. $set阶段根据前一阶段计算的平均字段计算新的字段等级。See $switch for more information on the $switch aggregation operator.有关$switch聚合运算符的更多信息，请参阅$switch。

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

{ "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
{ "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
{ "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:33:30.674Z"), "average" : 75, "grade" : "C" }

See also参阅

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

Update 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 update the document with name : "Pizza Rat's Pizzaria", while upsert: true :以下操作将尝试更新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);
}

Since upsert:true the document is inserted based on the filter and update criteria. 自upsert:true起，根据filter和update条件插入文档。The operation returns:操作返回：

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

The name field was filled in using the filter criteria, while the update operators were used to create the rest of the document.name字段使用filter条件填充，而update运算符用于创建文档的其余部分。

The following operation updates the first document with violations that are greater than 10:以下操作将使用大于10的violations更新第一个文档：

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

The operation returns:操作返回：

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

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

Since no documents matched the filter, and upsert was true, updateOne inserted the document with a generated _id and the update criteria only.由于没有与筛选器匹配的文档，且upsert为true，因此updateOne仅使用生成的_id和update条件插入文档。

Update with Write Concern带着写问题更新

Given a three member replica set, the following operation specifies a w of majority, wtimeout of 100:给定一个由三个成员组成的副本集，以下操作指定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);
}

If the primary and at least one secondary acknowledge each write operation within 100 milliseconds, it returns:如果主设备和至少一个辅助设备在100毫秒内确认每个写入操作，则返回：

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

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描述
clientSupplied The write concern was specified in the application.应用程序中指定了写入问题。
customDefault The write concern originated from a custom defined default value. 写入问题源于自定义的默认值。See setDefaultRWConcern.请参阅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.在没有所有其他写关注规范的情况下，写关注源于服务器。

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.myColl.updateOne(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

Specify arrayFilters for an 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 in the db.collection.updateOne method:要修改grades数组中大于或等于100的所有元素，请在db.collection.updateOne方法中使用筛选的位置运算符$[<identifier>]和arrayFilters选项：

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

The operation updates the grades field of a single document, and after the operation, the collection has the following documents:该操作会更新单个文档的grades字段，操作完成后，集合中有以下文档：

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }{ "_id" : 3, "grades" : [ 95, 110, 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 in the db.collection.updateOne method:要修改等级大于或等于85的grades数组中所有元素的mean（平均值）字段，请在db.collection.updateOne方法中使用筛选的位置运算符$[<identifier>]和arrayFilters：

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

The operation updates the array of a single document, and 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" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}

Specify hint for Update Operations指定更新操作的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.updateOne(
   { "points": { $lte: 20 }, "status": "P" },
   { $set: { "misc1": "Need to activate" } },
   { hint: { status: 1 } }
)

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

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

See also参阅

To update multiple documents, see db.collection.updateMany().要更新多个文档，请参阅db.collection.updateMany()。