Docs Home → MongoDB Manual

$setField (aggregation)

On this page本页内容

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描述
fieldStringField in the input object that you want to add, update, or remove. 要添加、更新或删除的input对象中的字段。field can be any valid expression that resolves to a string constant.field可以是解析为字符串常量的任何有效表达式。
inputObjectDocument that contains the field that you want to add or update. 包含要添加或更新的field的文档。input must resolve to an object, missing, null, or undefined.input必须解析为对象、missing、null或undefined。
valueExpressionThe value that you want to assign to field. 要分配给field的值。value can be any valid expression.可以是任何有效的表达式。
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的计算结果为missing、undefined或null，则$setField将返回null并且不更新输入。
  • If input evaluates to anything other than an object, missing, undefined, or null, $setField returns an error.如果input的求值结果不是对象、missing、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将field值"a.b.c"计算为顶级字段"a.b.c"，而不是嵌套字段{ "a": { "b": { "c": } } }。
  • $unsetField is an alias for $setField with an input value of $$REMOVE. 是输入值为$$REMOVE的$setField的别名。The following expressions are equivalent:以下表达式等效：

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

    {
       $unsetField: {
          field: <field name>,
          input: “$$ROOT”
       }
    }
Tip

See also: 另请参阅：

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. "price.usd"的值将等于每个文档中"price"的值。Finally, the operation uses the $unset pipeline stage to remove the "price" field.最后，该操作使用$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". The value of "$price" will equal the value of "price" in each document. 以下操作使用$replaceWith管道阶段以及$setField和$literal运算符为每个文档添加一个新字段"$price"。"$price"的值将等于每个文档中的"$price"值。Finally, the operation uses the $unset pipeline stage to remove the "price" field.最后，该操作使用$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

See also: 另请参阅：

$unsetField