update

在本页面

• Definition

• Behavior

• Examples

• Output

Definition

• update
  • 2.6 版的新功能。

update命令修改集合中的文档。一个update命令可以包含多个更新语句。 MongoDB 驱动程序提供的更新方法在内部使用此命令。

update命令具有以下语法：

{
   update: <collection>,
   updates: [
      { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean>,
        collation: <document>, arrayFilters: <array> },
      { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean>,
        collation: <document>, arrayFilters: <array> },
      { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean>,
        collation: <document>, arrayFilters: <array> },
      ...
   ],
   ordered: <boolean>,
   writeConcern: { <write concern> },
   bypassDocumentValidation: <boolean>
}

该命令包含以下字段：

Field	Type	Description
update	string	目标集合的名称。
updates	array	要在命名集合中执行的一个或多个更新语句的数组。
ordered	boolean	可选的。如果true，则当更新语句失败时，不执行其余的更新语句就返回。如果false，则更新失败时，请 continue 其余的更新语句(如果有)。默认为true。
writeConcern	document	可选的。表示update命令的write concern的文档。省略使用默认的写关注。
bypassDocumentValidation	boolean	可选的。使update在操作过程中绕过文档验证。这使您可以更新不满足验证要求的文档。

版本 3.2 中的新功能。

updates数组的每个元素包含以下字段：

Field	Type	Description
q	document	与要更新的文档匹配的查询。使用与find()方法中相同的query selectors。
u	document	要应用的修改。有关详细信息，请参见Behavior。
upsert	boolean	可选的。如果是true，则在没有文档匹配查询的情况下执行插入。如果upsert和multi均为 true，并且没有文档与查询匹配，则更新操作仅插入单个文档。
multi	boolean	可选的。如果true，则更新所有符合查询条件的文档。如果false，则将更新限制为符合查询条件的一个文档。默认为false。
collation	document	Optional.

指定用于操作的collation。
Collation允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。
排序规则选项具有以下语法：
collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}
指定排序规则时，locale字段为必填字段；所有其他排序规则字段都是可选的。有关字段的说明，请参见Collation Document。
如果未指定排序规则，但是集合具有默认排序规则(请参见db.createCollection())，则该操作将使用为集合指定的排序规则。
如果没有为集合或操作指定排序规则，则 MongoDB 使用先前版本中使用的简单二进制比较进行字符串比较。
您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。
3.4 版中的新功能。
| arrayFilters | array |可选。筛选器文档数组，用于确定要对数组字段进行更新操作要修改的数组元素。
在更新文档中，使用$[<identifier>]过滤的位置运算符定义标识符，然后在数组过滤器文档中引用该标识符。如果更新文档中未包含标识符，则不能具有数组过滤器文档作为标识符。

Returns:	包含操作状态的文档。有关详情，请参见Output。

Behavior

<update>文档可以包含所有update operator表达式或所有field:value表达式。

更新运算符表达式

如果<update>文档包含所有update operator表达式，则如下所示：

{
  $set: { status: "D" },
  $inc: { quantity: 2 }
}

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

字段：值表达式

如果<update>文档仅包含* field:value个表达式，例如：

{
  status: "D",
  quantity: 4
}

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

Limits

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

updates数组中的更新语句总数必须小于或等于maximum bulk size。

Document Validation

update命令增加了对bypassDocumentValidation选项的支持，该选项使您可以在使用验证规则在集合中插入或更新文档时绕过document validation。

Examples

更新一个文档的特定字段

使用update operators仅更新文档的指定字段。

例如，给定users集合，以下命令使用$set和$inc运算符分别修改user等于"abc123"的文档的status和points字段：

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

因为<update>文档未指定可选的multi字段，所以即使多个文档符合q匹配条件，更新也仅修改一个文档。

返回的文档表明该命令找到并更新了一个文档。有关详情，请参见Output。

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

更新多个文档的特定字段

使用update operators仅更新文档的指定字段，并在更新语句中包括设置为true的multi字段。

例如，对于给定的users集合，以下命令使用$set和$inc运算符分别修改集合中所有文档的status和points字段：

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

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

返回的文档表明该命令找到并更新了多个文档。有关详情，请参见Output。

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

Bulk Update

下面的示例对users集合执行多个更新操作：

db.runCommand(
   {
      update: "users",
      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的文档。有关详情，请参见Output。

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

Specify Collation

3.4 版的新功能。

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

集合myColl具有以下文档：

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

以下操作包括collation选项：

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

为阵列更新操作指定 arrayFilters

3.6 版的新功能。

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

更新元素匹配 arrayFilters 条件

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

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

要修改grades数组中所有等于或大于100的元素，请使用带有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.insert([
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
]);

要为grades数组中坡度大于或等于85的所有元素修改mean字段的值，请使用过滤后的位置运算符$[<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 }
   ]
}

Output

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

• update. ok

  • 命令的状态。

• update. n

  • 选择进行更新的文档数。如果更新操作导致文档没有更改，例如$set表达式会将值更新为当前值，n可以大于nModified。

• update. nModified

  • 更新的文档数。如果更新操作未更改文档，例如将字段的值设置为其当前值，则nModified可以小于n。

• 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

  • 描述与写关注有关的错误的文档，其中包含以下字段：

• update.writeConcernError. code

  • 标识写关注错误原因的整数值。

• update.writeConcernError. errmsg

  • 写关注错误原因的描述。

以下是为成功执行_1s 命令而返回的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}."
      },
   ]
}