Database Manual / Reference / Query Language / Expressions

$setField (aggregation)（聚合）

Definition定义

$setField

New in version 5.0.在版本5.0中新增。

Adds, updates, or removes a specified field in a document.添加、更新或删除文档中的指定字段。

You can use $setField to add, update, or remove fields with names that contain periods (.) or start with dollar signs ($).您可以使用$setField添加、更新或删除名称包含句点（.）或以美元符号（$）开头的字段。

Tip

Use $getField to retrieve the values of fields that contain dollar signs ($) or periods (.) that you add or update with $setField.使用$getField检索包含您使用$setField添加或更新的美元符号（$）或句点（.）的字段的值。

Syntax语法

$setField has the following syntax:具有以下语法：

{
  $setField: {
    field: <String>,
    input: <Object>,
    value: <Expression>
  }
}

You must provide the following fields:您必须提供以下字段：

Field字段Type类型Description描述
fieldString字符串Field in the input object that you want to add, update, or remove. field can be any valid expression that resolves to a string constant.input对象中要添加、更新或删除的字段。field可以是解析为字符串常量的任何有效表达式。
inputObject对象Document that contains the field that you want to add or update. 包含要添加或更新的field的文档。input must resolve to an object, missing, null, or undefined.input必须解析为对象、缺失、null或undefined。
valueExpression表达式

The value that you want to assign to field. value can be any valid expression.要分配给field的值。value 可以是任何有效的表达式。

Set to $$REMOVE to remove field from the input document.设置为$$REMOVE可从input文档中删除field。

Behavior行为

  • If input evaluates to missing, undefined, or null, $setField returns null and does not update input.如果input计算结果为缺失、undefined或null，则$setField将返回null并且不更新输入。
  • If input evaluates to anything other than an object, missing, undefined, or null, $setField returns an error.如果input的结果不是对象、缺失、undefined或null，$setField将返回错误。
  • If field resolves to anything other than a string constant, $setField returns an error.若field解析为字符串常量以外的任何值，$setField将返回错误。
  • If field doesn't exist in input, $setField adds it.若input中不存在field，则$setField会添加它。
  • $setField doesn't implicitly traverse objects or arrays. For example, $setField evaluates a field value of "a.b.c" as a top-level field "a.b.c" instead of as a nested field, { "a": { "b": { "c": } } }.$setField不会隐式遍历对象或数组。例如，$setField将field值"a.b.c"计算为顶级字段"a.b.c"，而不是嵌套字段{ "a": { "b": { "c": } } }。

  • $unsetField is an alias for $setField with an input value of $$REMOVE. The following expressions are equivalent:$unsetField是$setField的别名，输入值为$$REMOVE。以下表达式是等价的：

    {
       $setField: {
          field: <field name>,
          input: "$$ROOT",
          value: "$$REMOVE"
       }
    }

    {
       $unsetField: {
          field: <field name>,
          input: "$$ROOT"
       }
    }

Tip

Considerations for field names字段名称的注意事项

Examples示例

Add Fields that Contain Periods (.)添加包含句点（.）的字段

Consider an inventory collection with the following documents:考虑使用以下文件进行inventory集合：

db.inventory.insertMany( [
   { _id: 1, item: "sweatshirt", price: 45.99, qty: 300 },
   { _id: 2, item: "winter coat", price: 499.99, qty: 200 },
   { _id: 3, item: "sun dress", price: 199.99, qty: 250 },
   { _id: 4, item: "leather boots", price: 249.99, qty: 300 },
   { _id: 5, item: "bow tie", price: 9.99, qty: 180 }
] )

The following operation uses the $replaceWith pipeline stage and the $setField operator to add a new field to each document, "price.usd". 以下操作使用$replaceWith管道阶段和$setField运算符向每个文档添加一个新字段"price.usd"。The value of "price.usd" will equal the value of "price" in each document. Finally, the operation uses the $unset pipeline stage to remove the "price" field."price.usd"的值将等于每个文档中的"price"的值。最后，该操作使用$unset管道阶段删除"price"字段。

db.inventory.aggregate( [
   { $replaceWith: {
        $setField: {
           field: "price.usd",
           input: "$$ROOT",
           value: "$price"
   } } },
   { $unset: "price" }
] )

The operation returns the following results:该操作返回以下结果：

[
  { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 45.99 },
  { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
  { _id: 3, item: 'sun dress', qty: 250, 'price.usd': 199.99 },
  { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 },
  { _id: 5, item: 'bow tie', qty: 180, 'price.usd': 9.99 }
]

Add Fields that Start with a Dollar Sign ($)添加以美元符号（$）开头的字段

Consider an inventory collection with the following documents:考虑使用以下文件进行inventory集合：

db.inventory.insertMany( [
   { _id: 1, item: "sweatshirt", price: 45.99, qty: 300 },
   { _id: 2, item: "winter coat", price: 499.99, qty: 200 },
   { _id: 3, item: "sun dress", price: 199.99, qty: 250 },
   { _id: 4, item: "leather boots", price: 249.99, qty: 300 },
   { _id: 5, item: "bow tie", price: 9.99, qty: 180 }
] )

The following operation uses the $replaceWith pipeline stage and the $setField and $literal operators to add a new field to each document, "$price". 以下操作使用$replaceWith管道阶段以及$setField和$literal运算符向每个文档添加一个新字段"$price"。The value of "$price" will equal the value of "price" in each document. Finally, the operation uses the $unset pipeline stage to remove the "price" field."$price"的值将等于每个文档中的"price"值。最后，该操作使用$unset管道阶段删除"price"字段。

db.inventory.aggregate( [
   { $replaceWith: {
        $setField: {
           field: { $literal: "$price" },
           input: "$$ROOT",
           value: "$price"
   } } },
   { $unset: "price" }
] )

The operation returns the following results:该操作返回以下结果：

[
  { _id: 1, item: 'sweatshirt', qty: 300, '$price': 45.99 },
  { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
  { _id: 3, item: 'sun dress', qty: 250, '$price': 199.99 },
  { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 },
  { _id: 5, item: 'bow tie', qty: 180, '$price': 9.99 }
]

Update Fields that Contain Periods (.)更新包含句点（.）的字段

Consider an inventory collection with the following documents:考虑使用以下文件进行inventory集合：

db.inventory.insertMany( [
   { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, 'price.usd': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, 'price.usd': 9.99 }
] )

The following operation uses the $match pipeline stage to find a specific document and the $replaceWith pipeline stage and the $setField operator to update the "price.usd" field in the matching document:以下操作使用$match管道阶段查找特定文档，使用$replaceWith管道阶段和$setField运算符更新匹配文档中的"price.usd"字段：

db.inventory.aggregate( [
   { $match: { _id: 1 } },
   { $replaceWith: {
        $setField: {
           field: "price.usd",
           input: "$$ROOT",
           value: 49.99
    } } }
] )

The operation returns the following results:该操作返回以下结果：

[
  { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 49.99 }
]

Update Fields that Start with a Dollar Sign ($)更新以美元符号（$）开头的字段

Consider an inventory collection with the following documents:考虑使用以下文件进行inventory集合：

db.inventory.insertMany([
   { _id: 1, item: 'sweatshirt', qty: 300, '$price': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, '$price': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, '$price': 9.99 }
] )

The following operation uses the $match pipeline stage to find a specific document and the $replaceWith pipeline stage and the $setField and $literal operators to update the "$price" field in the matching document:以下操作使用$match管道阶段查找特定文档，使用$replaceWith管道阶段以及$setField和$literal运算符更新匹配文档中的"$price"字段：

db.inventory.aggregate( [
   { $match: { _id: 1 } },
   { $replaceWith: {
        $setField: {
           field: { $literal: "$price" },
           input: "$$ROOT",
           value: 49.99
   } } }
] )

The operation returns the following results:该操作返回以下结果：

[
  { _id: 1, item: 'sweatshirt', qty: 300, '$price': 49.99 }
]

Remove Fields that Contain Periods (.)删除包含句点（.）的字段

Consider an inventory collection with the following documents:考虑使用以下文件进行inventory集合：

db.inventory.insertMany([
   { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, 'price.usd': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, 'price.usd': 9.99 }
] )

The following operation uses the $replaceWith pipeline stage and the $setField operator and $$REMOVE to remove the "price.usd" field from each document:以下操作使用$replaceWith管道阶段、$setField运算符和$$REMOVE从每个文档中删除"price.usd"字段：

db.inventory.aggregate( [
   { $replaceWith:  {
        $setField: {
           field: "price.usd",
           input: "$$ROOT",
           value: "$$REMOVE"
   } } }
] )

The operation returns the following results:该操作返回以下结果：

[
  { _id: 1, item: 'sweatshirt', qty: 300 },
  { _id: 2, item: 'winter coat', qty: 200 },
  { _id: 3, item: 'sun dress', qty: 250 },
  { _id: 4, item: 'leather boots', qty: 300 },
  { _id: 5, item: 'bow tie', qty: 180 }
]

A similar query written using the $unsetField alias returns the same results:使用$unsetField别名编写的类似查询返回相同的结果：

db.inventory.aggregate( [
   { $replaceWith:  {
        $unsetField: {
           field: "price.usd",
           input: "$$ROOT"
   } } }
] )

Remove Fields that Start with a Dollar Sign ($)删除以美元符号（$）开头的字段

Consider an inventory collection with the following documents:考虑使用以下文件进行inventory集合：

db.inventory.insertMany( [
   { _id: 1, item: 'sweatshirt', qty: 300, '$price': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, '$price': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, '$price': 9.99 }
] )

The following operation uses the $replaceWith pipeline stage, the $setField and $literal operators, and $$REMOVE to remove the "$price" field from each document:以下操作使用$replaceWith管道阶段、$setField和$literal运算符以及$$REMOVE从每个文档中删除"$price"字段：

db.inventory.aggregate( [
   { $replaceWith: {
        $setField: {
           field: { $literal: "$price" },
           input: "$$ROOT",
           value: "$$REMOVE"
   } } }
] )

The operation returns the following results:该操作返回以下结果：

[
  { _id: 1, item: 'sweatshirt', qty: 300 },
  { _id: 2, item: 'winter coat', qty: 200 },
  { _id: 3, item: 'sun dress', qty: 250 },
  { _id: 4, item: 'leather boots', qty: 300 },
  { _id: 5, item: 'bow tie', qty: 180 }
]

A similar query written using the $unsetField alias returns the same results:使用$unsetField别名编写的类似查询返回相同的结果：

db.inventory.aggregate( [
  { $replaceWith: {
       $unsetField: {
          field: { $literal: "$price" },
          input: "$$ROOT"
  } } }
] )

Tip

$unsetField