$addFields (aggregation)

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

Output:

[
   {
      _id: ObjectId('671285306fd2c3b24f2e7eaa'),
      date: ISODate('2024-10-09T00:00:00.000Z'),
      temperature: 80
   },
   { _id: ObjectId('671285306fd2c3b24f2e7eab'), temperature: 83 },
   {
      _id: ObjectId('671285306fd2c3b24f2e7eac'),
      date: ISODate('2024-12-09T00:00:00.000Z'),
      temperature: 85
   }
]