MongoDB $addFields Stage

What You’ll Learn

The $addFields stage adds new computed fields to each document in a pipeline while keeping existing fields—ideal for line totals, formatted labels, flags, and derived metrics before sorting or grouping.

Definition and Usage

$addFields is an aggregation stage that outputs documents equal to the input documents plus any fields you define. Each new field’s value comes from an aggregation expression evaluated against the current document.

Use $addFields when downstream stages need calculated values—totals for $sort, categories for $group, or display strings before $limit. Pair with operators like $add and $multiply inside expressions.

📝 Syntax

$addFields takes a document mapping field names to expressions:

{
  $addFields: {
    <newField1>: <expression1>,
    <newField2>: <expression2>,
    ...
  }
}

Syntax Rules

• Preserves fields — all existing top-level fields remain unless overwritten by the same name.
• Expression values — use field paths ("$price"), literals, or operator expressions.
• Overwrite — assigning to an existing field name replaces that field’s value.
• Nested keys — dot notation ("meta.source") or nested objects add sub-fields.
• Multiple fields — add many computed columns in one stage.
• Alias — $set accepts identical syntax (MongoDB 4.2+).

db.orders.aggregate([
  {
    $addFields: {
      lineTotal: { $multiply: ["$price", "$quantity"] }
    }
  }
]);

Examples Gallery

Sample order line items—compute totals, build labels, compare with $project, and add conditional flags.

db.orders.insertMany([
  { product: "Keyboard", price: 45,  quantity: 2, firstName: "Sam",  lastName: "Lee",  score: 92 },
  { product: "Mouse",    price: 25,  quantity: 1, firstName: "Alex", lastName: "Kim",  score: 71 },
  { product: "Monitor",  price: 180, quantity: 1, firstName: "Jordan", lastName: "Wu", score: 85 }
]);

db.orders.aggregate([
  {
    $addFields: {
      lineTotal: { $multiply: ["$price", "$quantity"] }
    }
  },
  { $project: { product: 1, price: 1, quantity: 1, lineTotal: 1 } }
]);

/* Keyboard → lineTotal: 90  (45 × 2)
   Mouse    → lineTotal: 25
   Monitor  → lineTotal: 180 */
*/

product: "Keyboard"
price: 45, quantity: 2
lineTotal: 90

db.orders.aggregate([
  {
    $addFields: {
      fullName: {
        $concat: ["$firstName", " ", "$lastName"]
      }
    }
  },
  { $project: { fullName: 1, product: 1, _id: 0 } }
]);

/* Sam Lee, Alex Kim, Jordan Wu */
*/

{ fullName: "Sam Lee", product: "Keyboard" }

// $addFields — keeps ALL original fields + lineTotal
db.orders.aggregate([
  { $addFields: { lineTotal: { $multiply: ["$price", "$quantity"] } } },
  { $limit: 1 }
]);
// Output includes firstName, lastName, score, etc.

// $project — ONLY listed fields (plus _id unless suppressed)
db.orders.aggregate([
  {
    $project: {
      product: 1,
      lineTotal: { $multiply: ["$price", "$quantity"] }
    }
  },
  { $limit: 1 }
]);
// Output: product, lineTotal, _id only

$addFields → original doc + new fields
$project   → only fields you list

db.orders.aggregate([
  {
    $addFields: {
      lineTotal: { $multiply: ["$price", "$quantity"] },
      tier: {
        $cond: {
          if: { $gte: ["$score", 85] },
          then: "gold",
          else: "standard"
        }
      }
    }
  },
  { $sort: { lineTotal: -1 } }
]);

/* Monitor → lineTotal: 180, tier: "gold" (score 85)
   Keyboard → lineTotal: 90,  tier: "gold" (score 92)
   Mouse → lineTotal: 25, tier: "standard" */
*/

lineTotal: 180
tier: "gold"

📝 Notes

• $addFields does not write to the collection—it transforms documents in the pipeline only.
• To reference a field added in the same stage, use a second $addFields stage—expressions in one object cannot refer to sibling keys being defined simultaneously.
• $set and $addFields are interchangeable on MongoDB 4.2+.
• Dot-notation keys merge into nested objects; they do not replace the entire parent object unless intended.
• Place before $group when grouped accumulators need the computed field (e.g. group by lineTotal bucket).
• Previous topic: Installation. Next: $bucket.

💡 Best Practices