$replaceWith (aggregation)

Definition

  • $replaceWith

New in version 4.2.

Replaces the input document with the specified document. Theoperation replaces all existing fields in the input document,including the _id field. With $replaceWith, you canpromote an embedded document to the top-level. You can also specifya new document as the replacement.

The $replaceWith is an alias for$replaceRoot.

The $replaceWith stage has the following form:

  1. { $replaceWith: <replacementDocument> }

The replacement document can be any valid expression that resolves to a document.For more information on expressions, seeExpressions.

Behavior

If the <replacementDocument> is not a document,$replaceWith errors and fails.

If the <replacementDocument> resolves to a missing document (i.e.the document does not exist), $replaceWith errors andfails. For example, create a collection with the followingdocuments:

  1. db.collection.insertMany([
  2.    { "_id": 1, "name" : { "first" : "John", "last" : "Backus" } },
  3.    { "_id": 2, "name" : { "first" : "John", "last" : "McCarthy" } },
  4.    { "_id": 3, "name": { "first" : "Grace", "last" : "Hopper" } },
  5.    { "_id": 4, "firstname": "Ole-Johan", "lastname" : "Dahl" },
  6. ])

Then the following $replaceWith operation fails because oneof the document does not have the name field:

  1. db.collection.aggregate([
  2.    { $replaceWith: "$name" }
  3. ])

To avoid the error, you can use $mergeObjects to mergethe name document with some default document; for example:

  1. db.collection.aggregate([
  2.    { $replaceWith: { $mergeObjects: [ { _id: "$_id", first: "", last: "" }, "$name" ] } }
  3. ])

Alternatively, you can skip the documents that are missing the name field byincluding a $match stage to check for existence of thedocument field before passing documents to the $replaceWithstage:

  1. db.collection.aggregate([
  2.    { $match: { name : { $exists: true, $not: { $type: "array" }, $type: "object" } } },
  3.    { $replaceWith: "$name" }
  4. ])

Or, you can use $ifNull expression to specify some otherdocument to be root; for example:

  1. db.collection.aggregate([
  2.    { $replaceWith: { $ifNull: [ "$name", { _id: "$_id", missingName: true} ] } }
  3. ])

Examples

$replaceWith an Embedded Document Field

Create a collection named people with the following documents:

  1. db.people.insertMany([
  2.    { "_id" : 1, "name" : "Arlene", "age" : 34, "pets" : { "dogs" : 2, "cats" : 1 } },
  3.    { "_id" : 2, "name" : "Sam", "age" : 41, "pets" : { "cats" : 1, "fish" : 3 } },
  4.    { "_id" : 3, "name" : "Maria", "age" : 25 }
  5. ])

The following operation uses the $replaceWith stage toreplace each input document with the result of a$mergeObjects operation. The $mergeObjectsexpression merges the specified default document with the petsdocument.

  1. db.people.aggregate( [
  2.    { $replaceWith: { $mergeObjects:  [ { dogs: 0, cats: 0, birds: 0, fish: 0 }, "$pets" ] } }
  3. ] )

The operation returns the following results:

  1. { "dogs" : 2, "cats" : 1, "birds" : 0, "fish" : 0 }
  2. { "dogs" : 0, "cats" : 1, "birds" : 0, "fish" : 3 }
  3. { "dogs" : 0, "cats" : 0, "birds" : 0, "fish" : 0 }

$replaceWith a Document Nested in an Array

A collection named students contains the following documents:

  1. db.students.insertMany([
  2.    {
  3.       "_id" : 1,
  4.       "grades" : [
  5.          { "test": 1, "grade" : 80, "mean" : 75, "std" : 6 },
  6.          { "test": 2, "grade" : 85, "mean" : 90, "std" : 4 },
  7.          { "test": 3, "grade" : 95, "mean" : 85, "std" : 6 }
  8.       ]
  9.    },
  10.    {
  11.       "_id" : 2,
  12.       "grades" : [
  13.          { "test": 1, "grade" : 90, "mean" : 75, "std" : 6 },
  14.          { "test": 2, "grade" : 87, "mean" : 90, "std" : 3 },
  15.          { "test": 3, "grade" : 91, "mean" : 85, "std" : 4 }
  16.       ]
  17.    }
  18. ])

The following operation promotes the embedded document(s) with thegrade field greater than or equal to 90 to the top level:

  1. db.students.aggregate( [
  2.    { $unwind: "$grades" },
  3.    { $match: { "grades.grade" : { $gte: 90 } } },
  4.    { $replaceWith: "$grades" }
  5. ] )

The operation returns the following results:

  1. { "test" : 3, "grade" : 95, "mean" : 85, "std" : 6 }
  2. { "test" : 1, "grade" : 90, "mean" : 75, "std" : 6 }
  3. { "test" : 3, "grade" : 91, "mean" : 85, "std" : 4 }

$replaceWith a Newly Created Document

Example 1

An example collection sales is populated with the followingdocuments:

  1. db.sales.insertMany([
  2.    { "_id" : 1, "item" : "butter", "price" : 10, "quantity": 2, date: ISODate("2019-03-01T08:00:00Z"), status: "C" },
  3.    { "_id" : 2, "item" : "cream", "price" : 20, "quantity": 1, date: ISODate("2019-03-01T09:00:00Z"), status: "A" },
  4.    { "_id" : 3, "item" : "jam", "price" : 5, "quantity": 10, date: ISODate("2019-03-15T09:00:00Z"), status: "C" },
  5.    { "_id" : 4, "item" : "muffins", "price" : 5, "quantity": 10, date: ISODate("2019-03-15T09:00:00Z"), status: "C" }
  6. ])

Assume that for reporting purposes, you want to calculate for eachcompleted sale, the total amount as of the current report run time. Thefollowing operation finds all the sales with status C and createsnew documents using the $replaceWith stage. The$replaceWith calculates the total amount as well as usesthe variable NOW to get the current time.

  1. db.sales.aggregate([
  2.    { $match: { status: "C" } },
  3.    { $replaceWith: { _id: "$_id", item: "$item", amount: { $multiply: [ "$price", "$quantity"]}, status: "Complete", asofDate: "$$NOW" } }
  4. ])

The operation returns the following documents:

  1. { "_id" : 1, "item" : "butter", "amount" : 20, "status" : "Complete", "asofDate" : ISODate("2019-06-03T22:47:54.812Z") }
  2. { "_id" : 3, "item" : "jam", "amount" : 50, "status" : "Complete", "asofDate" : ISODate("2019-06-03T22:47:54.812Z") }
  3. { "_id" : 4, "item" : "muffins", "amount" : 50, "status" : "Complete", "asofDate" : ISODate("2019-06-03T22:47:54.812Z") }

Example 2

An example collection reportedsales is populated with thereported sales information by quarter and regions:

  1. db.reportedsales.insertMany( [
  2.    { _id: 1, quarter: "2019Q1", region: "A", qty: 400 },
  3.    { _id: 2, quarter: "2019Q1", region: "B", qty: 550 },
  4.    { _id: 3, quarter: "2019Q1", region: "C", qty: 1000 },
  5.    { _id: 4, quarter: "2019Q2", region: "A", qty: 660 },
  6.    { _id: 5, quarter: "2019Q2", region: "B", qty: 500 },
  7.    { _id: 6, quarter: "2019Q2", region: "C", qty: 1200 }
  8. ] )

Assume that for reporting purposes, you want to view the reported salesdata by quarter; e.g.

  1. { "_id" : "2019Q1", "A" : 400, "B" : 550, "C" : 1000 }

To view the data grouped by quarter, you can use the followingaggregation pipeline:

  1. db.reportedsales.aggregate( [
  2.    { $addFields: { obj:  { k: "$region", v: "$qty" } } },
  3.    { $group: { _id: "$quarter", items: { $push: "$obj" } } },
  4.    { $project: { items2: { $concatArrays: [ [ { "k": "_id", "v": "$_id" } ], "$items" ] } } },
  5.    { $replaceWith: { $arrayToObject: "$items2" } }
  6. ] )
  • First stage:
  • The $addFields stage adds a new obj documentfield that defines the key k as the region value and thevalue v as the quantity for that region. For example:
  1. { "_id" : 1, "quarter" : "2019Q1", "region" : "A", "qty" : 400, "obj" : { "k" : "A", "v" : 400 } }
  • Second stage:
  • The $group stage groups by the quarter and uses$push to accumulate the obj fields into a newitems array field. For example:
  1. { "_id" : "2019Q1", "items" : [ { "k" : "A", "v" : 400 }, { "k" : "B", "v" : 550 }, { "k" : "C", "v" : 1000 } ] }
  • Third stage:
  • The $project stage uses $concatArrays tocreate a new array items2 that includes the _id info and theelements from the items array:
  1. { "_id" : "2019Q1", "items2" : [ { "k" : "_id", "v" : "2019Q1" }, { "k" : "A", "v" : 400 }, { "k" : "B", "v" : 550 }, { "k" : "C", "v" : 1000 } ] }
  • Fourth stage:
  • The $replaceWith uses the$arrayToObject to convert the items2 into adocument, using the specified key k and value v pairs andoutputs that document to the next stage. For example:
  1. { "_id" : "2019Q1", "A" : 400, "B" : 550, "C" : 1000 }

The aggregation returns the following document:

  1. { "_id" : "2019Q1", "A" : 400, "B" : 550, "C" : 1000 }
  2. { "_id" : "2019Q2", "A" : 660, "B" : 500, "C" : 1200 }

$replaceWith a New Document Created from $$ROOT and a Default Document

Create a collection named contacts with the following documents:

  1. db.contacts.insert([
  2.    { "_id" : 1, name: "Fred", email: "fred@example.net" },
  3.    { "_id" : 2, name: "Frank N. Stine", cell: "012-345-9999" },
  4.    { "_id" : 3, name: "Gren Dell", cell: "987-654-3210", email: "beo@example.net" }
  5. ]);

The following operation uses $replaceWith with$mergeObjects to output current documents with defaultvalues for missing fields:

  1. db.contacts.aggregate([
  2.    { $replaceWith: { $mergeObjects: [ { _id: "", name: "", email: "", cell: "", home: "" }, "$$ROOT" ] } }
  3. ])

The aggregation returns the following documents:

  1. { "_id" : 1, "name" : "Fred", "email" : "fred@example.net", "cell" : "", "home" : "" }
  2. { "_id" : 2, "name" : "Frank N. Stine", "email" : "", "cell" : "012-345-9999", "home" : "" }
  3. { "_id" : 3, "name" : "Gren Dell", "email" : "beo@example.net", "cell" : "", "home" : "987-654-3210" }