db.collection.updateOne()

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字段中包含一个精确匹配项，或以单个分片为目标（例如，在filter中包含分片键）。
• 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). 要将缺少shard键的文档作为目标，可以将null相等匹配与另一个筛选条件（例如在_id字段上）结合使用。For example:例如：

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Shard Key ModificationShard Key修改

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字段。In MongoDB 4.2 and earlier, a document's shard key field value is immutable.在MongoDB 4.2及更早版本中，文档的shard键字段值是不可变的。

To modify the existing shard key value with db.collection.updateOne():要使用db.collection.updateOne()修改现有的shard键值：

• 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缺少Shard密钥

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:此外，以下要求也适用：

See also:参阅：

• upsert on a Sharded Collection分片集合上的upsert
• Missing Shard Key Fields缺少分片键字段

Upsert within Transactions在事务中更新

Starting in MongoDB 4.4, you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.从MongoDB 4.4开始，如果事务不是跨分片写事务，则可以在多文档事务中创建集合和索引。

Specifically, in MongoDB 4.4 and greater, db.collection.updateOne() with upsert: true can be run on an existing collection or a non-existing collection. 具体来说，在MongoDB 4.4及更高版本中，带有upsert:true的db.collection.updateOne()可以在现有集合或不存在的集合上运行。If run on a non-existing collection, the operation creates the collection.如果在不存在的集合上运行，则该操作将创建集合。

In MongoDB 4.2 and earlier, the operation must be run on an existing collection.在MongoDB 4.2及更早版本中，操作必须在现有集合上运行。

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

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

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

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.insertMany( [
   { "_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"
     } } } }
   ]
)

First Stage第一阶段

The $set stage:$set阶段：

• calculates a new field average based on the average of the tests field. 基于tests字段的平均值计算新的字段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阶段根据上一阶段计算的average字段计算新字段grade。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" }

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

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

db.students.insertMany( [
   { "_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的所有元素，请在dbcollectionupdateOne()方法中使用带arrayFilters选项的筛选位置运算符$[<identifier>]：

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

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:要修改grade大于或等于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 }
   ]
}