$addFields (aggregation)
Definition
New in version 3.4.
Adds new fields to documents. $addFields
outputs documents thatcontain all existing fields from the input documents and newlyadded fields.
The $addFields
stage is equivalent to a$project
stage that explicitly specifies all existingfields in the input documents and adds the new fields.
Note
Starting in version 4.2, MongoDB adds a new aggregation pipelinestage $set
that is an alias for $addFields
.
$addFields
has the following form:
- { $addFields: { <newField>: <expression>, ... } }
Specify the name of each field to add and set its value to anaggregation expression. For moreinformation on expressions, see Expressions.
Important
If the name of the new field is the same as an existing field name(including _id
), $addFields
overwrites the existing valueof that field with the value of the specified expression.
Behavior
$addFields
appends new fields to existing documents. You caninclude one or more $addFields
stages in an aggregation operation.
To add field or fields to embedded documents (including documents inarrays) use the dot notation. See example.
To add an element to an existing array field with $addFields
, usewith $concatArrays
. See example.
Examples
Using Two $addFields Stages
A collection called scores
contains the following documents:
- {
- _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 toinclude 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.A collection called vehicles
contains the following documents:
- { _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
tothe 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
operationcauses the original field to be replaced.
A collection called animals
contains the following document:
- { _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 followingexample the item
field substitutes for the _id
field.
A collection called fruit
contains the following documents:
- { "_id" : 1, "item" : "tangerine", "type" : "citrus" }
- { "_id" : 2, "item" : "lemon", "type" : "citrus" }
- { "_id" : 3, "item" : "grapefruit", "type" : "citrus" }
The following aggregration operation uses $addFields
to replacethe _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 thehomework
field with a new array whose elements are the currenthomework
array concatenated with another array containing a newscore [ 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 }