You are viewing an offline version of MongoDB documentation. Some page features might be unavailable. To view the latest version of the page or use interactive features, visit the live page.

Database Manual

Aggregation Operations

Reference

Stages

$addFields (aggregation)

Definition

$addFields

Adds new fields to documents. $addFields outputs documents that contain all existing fields from the input documents and newly added fields.

The $addFields stage is equivalent to a $project stage that explicitly specifies all existing fields in the input documents and adds the new fields.

Note

You can also use the $set stage, which is an alias for $addFields.

Compatibility

You can use $addFields for deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The stage has the following syntax:

{ $addFields: { <newField>: <expression>, ... } }

Specify the name of each field to add and set its value to an aggregation expression or an empty object. For more information on expressions, see Expression Operators.

Important

If the name of the new field is the same as an existing field name (including _id), $addFields overwrites the existing value of that field with the value of the specified expression.

Behavior

$addFields appends new fields to existing documents. You can include one or more $addFields stages in an aggregation operation.
$addFields accepts the embedding of objects where you can set a value to an aggregation expression or to an empty object. For example, the following nested objects are accepted:
```
{$addFields: { a: { b: { } } } }
```
To add a field or fields to embedded documents (including documents in arrays) use the dot notation. See example.
To add an element to an existing array field with $addFields, use with $concatArrays. See example.

Examples

Using Two `$addFields` Stages

A collection called scores contains the following documents:

db.scores.insertMany( [
   {
      _id: 1,
      student: "Maya",
      homework: [ 10, 5, 10 ],
      quiz: [ 10, 8 ],
      extraCredit: 0
   },
   {
      _id: 2,
      student: "Ryan",
      homework: [ 5, 6, 5 ],
      quiz: [ 8, 8 ],
      extraCredit: 8
   }
] )

The following operation uses two $addFields stages to include three new fields in the output documents:

db.scores.aggregate( [
   {
     $addFields: {
       totalHomework: { $sum: "$homework" } ,
       totalQuiz: { $sum: "$quiz" }
     }
   },
   {
     $addFields: { totalScore:
       { $add: [ "$totalHomework", "$totalQuiz", "$extraCredit" ] } }
   }
] )

The operation returns the following documents:

[
   {
      _id: 1,
      student: "Maya",
      homework: [ 10, 5, 10 ],
      quiz: [ 10, 8 ],
      extraCredit: 0,
      totalHomework: 25,
      totalQuiz: 18,
      totalScore: 43
   },
   {
      _id: 2,
      student: "Ryan",
      homework: [ 5, 6, 5 ],
      quiz: [ 8, 8 ],
      extraCredit: 8,
      totalHomework: 16,
      totalQuiz: 16,
      totalScore: 40
   }
]

Adding Fields to an Embedded Document

Use dot notation to add new fields to embedded documents.

For example, create a collection called vehicles with the following documents:

db.vehicles.insertMany( [
      { _id: 1, type: "car", specs: { doors: 4, wheels: 4 } },
      { _id: 2, type: "motorcycle", specs: { doors: 0, wheels: 2 } },
      { _id: 3, type: "jet ski" }
] )

The following aggregation operation adds a new field fuel_type to the embedded document specs.

db.vehicles.aggregate( [
   { $addFields: { "specs.fuel_type": "unleaded" } }
] )

The operation returns the following results:

[
   { _id: 1, type: "car",
      specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } },
   { _id: 2, type: "motorcycle",
      specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } },
   { _id: 3, type: "jet ski",
      specs: { fuel_type: "unleaded" } }
]

Overwriting an existing field

Specifying an existing field name in an $addFields operation causes the original field to be replaced.

A collection called animals contains the following document:

db.animals.insertOne(
   { _id: 1, dogs: 10, cats: 15 }
)

The following $addFields operation specifies the cats field.

db.animals.aggregate( [
  {
    $addFields: { cats: 20 }
  }
] )

The operation returns the following document:

[ { _id: 1, dogs: 10, cats: 20 } ]

It is possible to replace one field with another. In the following example the item field substitutes for the _id field.

A collection called fruit contains the following documents:

db.fruit.insertMany( [
   { _id: 1, item: "tangerine", type: "citrus" },
   { _id: 2, item: "lemon", type: "citrus" },
   { _id: 3, item: "grapefruit", type: "citrus" }
] )

The following aggregation operation uses $addFields to replace the _id field of each document with the value of the item field, and replaces the item field with a static value.

db.fruit.aggregate( [
  {
    $addFields: {
      _id : "$item",
      item: "fruit"
    }
  }
] )

The operation returns the following:

[
   { _id: "tangerine", item: "fruit", type: "citrus" },
   { _id: "lemon", item: "fruit", type: "citrus" },
   { _id: "grapefruit", item: "fruit", type: "citrus" }
]

Add Element to an Array

Create a sample scores collection with the following:

db.scores.insertMany( [
   { _id: 1, student: "Maya", homework: [ 10, 5, 10 ], quiz: [ 10, 8 ], extraCredit: 0 },
   { _id: 2, student: "Ryan", homework: [ 5, 6, 5 ], quiz: [ 8, 8 ], extraCredit: 8 }
] )

You can use $addFields with a $concatArrays expression to add an element to an existing array field. For example, the following operation uses $addFields to replace the homework field with a new array whose elements are the current homework array concatenated with another array containing a new score [ 7 ].

db.scores.aggregate( [
   { $match: { _id: 1 } },
   { $addFields: { homework: { $concatArrays: [ "$homework", [ 7 ] ] } } }
] )

The operation returns the following:

[ { _id: 1, student: "Maya", homework: [ 10, 5, 10, 7 ], quiz: [ 10, 8 ], extraCredit: 0 } ]

Remove Fields

You can use $addFields with the $$REMOVE variable to remove document fields.

For example, create a labReadings collection:

db.labReadings.insertMany( [
   {
      date: ISODate("2024-10-09"),
      temperature: 80
   },
   {
      date: null,
      temperature: 83
   },
   {
      date: ISODate("2024-12-09"),
      temperature: 85
   }
] )

To remove the date field from the labReadings documents, use $addFields with the $$REMOVE variable:

db.labReadings.aggregate( [
   {
      $addFields: { date: "$$REMOVE" }
   }
] )

Output:

[
   { _id: ObjectId('671285306fd2c3b24f2e7eaa'), temperature: 80 },
   { _id: ObjectId('671285306fd2c3b24f2e7eab'), temperature: 83 },
   { _id: ObjectId('671285306fd2c3b24f2e7eac'), temperature: 85 }
]

You can also use $$REMOVE to conditionally remove fields. For example, the following aggregation removes the date field from documents where date is null:

db.labReadings.aggregate( [
   {
      $addFields:
         {
            date: {
               $ifNull: [ "$date", "$$REMOVE" ]
            }
         }
   }
] )