$mergeObjects (expression)

Definition

$mergeObjects

Merges an array of documents into a single document.

Syntax

When used as an expression, $mergeObjects has this syntax:

{ $mergeObjects: <expression> }

The <expression> operand can be either:

• A single expression that evaluates to an array of documents to merge. For example, $blogPosts where the document field blogPosts contains an array of documents.

• An array of expressions, each of which evaluates to a document. For example, [ "$doc1", "$doc2", "$doc3" ] where each document field contains a single document.

Behavior

$mergeObjects ignores null input values. If all input values are null, $mergeObjects returns an empty document { }.

$mergeObjects overwrites field values as it merges documents. If multiple input documents contain the same field name, the output contains the value from the last input document that contains the conflicting field.

{ $mergeObjects: [ { a: 1 }, null ] }

{ a: 1 }

{ $mergeObjects: [ null, null ] }

{ }

{
   $mergeObjects: [
      { a: 1 },
      { a: 2, b: 2 },
      { a: 3, c: 3 }
   ]
}

{ a: 3, b: 2, c: 3 }

{
  $mergeObjects: [
    { a: 1 },
    { a: 2, b: 2 },
    { a: 3, b: null, c: 3 }
  ]
}

{ a: 3, b: null, c: 3 }

Example

The examples on this page use data from the sample_mflix dataset. For details on how to load this dataset into your self-managed MongoDB deployment, see Load the Sample Dataset. If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

The following pipeline uses $mergeObjects in $replaceWith to merge each movie's imdb and tomatoes.critic sub-documents into a single ratings document. Both sub-documents contain a rating field, so $mergeObjects overwrites the imdb rating with the tomatoes.critic rating. Unique fields from each sub-document are preserved in the result.

db.movies.aggregate( [
   {
      $match: {
         genres: "Action",
         year: 2010,
         "imdb.rating": { $exists: true },
         "tomatoes.critic.rating": { $exists: true }
      }
   },
   { $sort: { title: 1 } },
   { $limit: 5 },
   {
      $replaceWith: {
         title: "$title",
         year: "$year",
         ratings: { $mergeObjects: [ "$imdb", "$tomatoes.critic" ] }
      }
   }
] )

[
  {
    title: '13 Assassins',
    year: 2010,
    ratings: {
      rating: 8,
      votes: 47152,
      id: 1436045,
      numReviews: 118,
      meter: 96
    }
  },
  {
    title: '14 Blades',
    year: 2010,
    ratings: {
      rating: 4.1,
      votes: 5496,
      id: 1442571,
      numReviews: 11,
      meter: 64
    }
  },
  {
    title: 'Batman: Under the Red Hood',
    year: 2010,
    ratings: {
      rating: 7.3,
      votes: 29421,
      id: 1569923,
      numReviews: 7,
      meter: 100
    }
  },
  {
    title: 'Black Death',
    year: 2010,
    ratings: {
      rating: 6.2,
      votes: 32582,
      id: 1181791,
      numReviews: 59,
      meter: 68
    }
  },
  {
    title: 'Boy Wonder',
    year: 2010,
    ratings: {
      rating: 6.4,
      votes: 7128,
      id: 1456060,
      numReviews: 5,
      meter: 40
    }
  }
]

In the preceding pipeline:

• $match filters to Action movies from 2010 with an existing imdb.rating and tomatoes.critic.rating.

• $sort sorts documents alphabetically by title.

• $limit restricts the output to 5 documents to improve readability.

• $replaceWith uses $mergeObjects to merge $imdb and $tomatoes.critic into a ratings field.

  • Because both sub-documents contain a rating field, $mergeObjects uses the value from tomatoes.critic (the last argument).

  • The unique fields votes and id from imdb, and numReviews and meter from tomatoes.critic, are all preserved.