$addFields, $replaceRoot, $mergeObjects

Three Reshaping Stages

$addFields: Adding Without Dropping

// $addFields preserves all existing fields
db.products.aggregate([{
  $addFields: {
    // Add computed fields; all original fields (name, price, etc.) are kept
    totalWithTax: { $multiply: ['$price', 1.1] },
    priceLabel: { $concat: ['$', { $toString: '$price' }] },
    isExpensive: { $gt: ['$price', 1000] }
  }
}]);
// All original product fields PLUS the three new computed fields

$set: The Modern Alias for $addFields

// $set (modern) and $addFields (classic) are identical
db.orders.aggregate([{
  $set: {  // same as $addFields
    totalWithShipping: { $add: ['$amount', '$shippingFee'] },
    daysToDeliver: {
      $divide: [
        { $subtract: ['$deliveredAt', '$createdAt'] },
        1000 * 60 * 60 * 24
      ]
    }
  }
}]);

Overwriting Existing Fields With $addFields

// Normalise email to lowercase in pipeline output
db.users.aggregate([{
  $addFields: {
    email: { $toLower: '$email' }  // overwrites existing email field
  }
}]);
// The stored document is unchanged; only the pipeline output is normalised

// Promote a nested field to the top level by overwriting
db.orders.aggregate([{
  $addFields: {
    city: '$shippingAddress.city'  // copy nested field to top level
  }
}]);

$replaceRoot: Making a Sub-Document the Root

// Document: { order: { id: 1, amount: 100, customer: { name: 'Alice' } } }

// Make the nested 'order' sub-document the new root
db.transactions.aggregate([{
  $replaceRoot: { newRoot: '$order' }
}]);
// Output: { id: 1, amount: 100, customer: { name: 'Alice' } }
// The outer 'order' wrapper is gone; order's fields are now at the root level

$replaceWith: Alias for $replaceRoot

// After lookup + unwind, make the joined product the root
db.orders.aggregate([
  { $lookup: { from: 'products', localField: 'productId', foreignField: '_id', as: 'product' } },
  { $unwind: '$product' },
  // Promote product to root, but keep orderId
  { $replaceWith: {
    $mergeObjects: ['$product', { orderId: '$_id', orderAmount: '$amount' }]
  }}
]);

$mergeObjects: Combining Two Objects

// Merge two objects - last key wins on conflict
db.users.aggregate([{
  $replaceWith: {
    $mergeObjects: [
      { defaultRole: 'viewer', isActive: false },  // defaults first
      '$$ROOT',                                     // actual doc overrides defaults
      { processedAt: '$$NOW' }                      // add computed field last
    ]
  }
}]);

$mergeObjects as a $group Accumulator

// Merge all update events per entity into one current state
db.events.aggregate([
  { $sort: { timestamp: 1 } },  // process oldest first
  { $group: {
    _id: '$entityId',
    // Merge all event deltas into one object; later events override earlier
    currentState: { $mergeObjects: '$delta' }
  }}
]);
// Each group's 'delta' objects are merged sequentially, last wins

Practical Pattern: Flatten $lookup Result

// Flatten order + product into a single output document
db.orders.aggregate([
  { $lookup: {
    from: 'products',
    localField: 'productId',
    foreignField: '_id',
    as: 'product'
  }},
  { $unwind: '$product' },
  { $replaceWith: {
    $mergeObjects: [
      '$product',                            // all product fields at root
      { orderId: '$_id', qty: '$qty', total: { $multiply: ['$product.price', '$qty'] } }
    ]
  }}
]);
// Clean flat output: { name, category, price, orderId, qty, total }

$unset: Removing Fields

// Remove sensitive fields from output
db.users.aggregate([{
  $unset: ['password', 'apiKey', '__v']  // array of field names to remove
}]);
// All fields except password, apiKey, and __v are passed through

// Remove a single field
db.orders.aggregate([{ $unset: 'internalNotes' }]);

// Remove nested field with dot notation
db.users.aggregate([{ $unset: 'profile.ssn' }]);

Combining $addFields, $replaceRoot, and $mergeObjects

db.invoices.aggregate([
  { $addFields: { taxAmount: { $multiply: ['$subtotal', 0.08] } } },
  { $lookup: { from: 'clients', localField: 'clientId', foreignField: '_id', as: 'client' } },
  { $unwind: '$client' },
  { $replaceWith: {
    $mergeObjects: [
      { invoiceId: '$_id', subtotal: '$subtotal', taxAmount: '$taxAmount' },
      { clientName: '$client.name', clientEmail: '$client.email' }
    ]
  }},
  { $unset: ['_id'] }
]);

Quick Check

Lesson Recap