/ /

$mergeObjects (window function)

Definition

$mergeObjects: New in version 8.3.

Returns a document created by merging the input documents from a window.

Note

Disambiguation

This page describes $mergeObjects when used as a window function.

You can also use $mergeObjects in these other contexts:

$mergeObjects (accumulator), which returns a merged document across a group of input documents.
$mergeObjects (expression), which merges an array of documents into a single document.

Syntax

{
   $setWindowFields: {
      output: {
         <outputField>: {
            $mergeObjects: <document>,
            window: {
               <documents|range>: [ "unbounded", <upper> ]
            }
         }
      }
   }
}

Note

The sortBy option in $setWindowFields is optional when the upper window bound is "unbounded" or when window is omitted. sortBy is required when the upper window bound is not "unbounded", such as "current".

When you omit sortBy, the order in which $mergeObjects resolves conflicting field names is not guaranteed.

Command Fields

Field	Type	Necessity	Description
`<document>`	Expression	Required	A field name or expression that evaluates to a document. `$percentile` merges the document values from all documents in the window.
`window`	Document	Optional	Specifies the window of documents over which `$percentile` operates. The lower bound must be `"unbounded"`. If omitted, the window includes all documents in the partition.

Behavior

Non-Removable Windows

$mergeObjects only supports non-removable windows, meaning the lower bound is "unbounded". If you specify a window where the lower bound is not "unbounded", the operation returns an error.

Null Input Handling

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

Field Overwrite Behavior

$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.

Example

Create a productUpdates collection:

db.productUpdates.insertMany( [
   { _id: 1, product: "gadget", date: ISODate("2024-01-01"), specs: { color: "blue" } },
   { _id: 2, product: "gadget", date: ISODate("2024-01-02"), specs: { size: "medium" } },
   { _id: 3, product: "gadget", date: ISODate("2024-01-03"), specs: { weight: 0.5 } },
   { _id: 4, product: "widget", date: ISODate("2024-01-01"), specs: { color: "red" } },
   { _id: 5, product: "widget", date: ISODate("2024-01-02"), specs: { material: "plastic" } }
] )

Each document represents a product update that adds new specification fields. Because each update contributes different field names to the specs sub-document, $mergeObjects can accumulate a complete specification profile as the window expands.

The following pipeline uses $mergeObjects in $setWindowFields to return a list of product specifications that updates cumulatively as new specifications are added to the window. For each document, cumulativeSpecs contains the merged specifications from all updates up to and including the current document:

db.productUpdates.aggregate( [
   {
      $setWindowFields: {
         partitionBy: "$product",
         sortBy: { date: 1 },
         output: {
            cumulativeSpecs: {
               $mergeObjects: "$specs",
               window: {
                  documents: [ "unbounded", "current" ]
               }
            }
         }
      }
   },
   { $sort: { product: 1, date: 1 } },
   { $project: { _id: 0, product: 1, date: 1, specs: 1, cumulativeSpecs: 1 } }
] )

[
  {
    product: 'gadget',
    date: ISODate('2024-01-01T00:00:00.000Z'),
    specs: { color: 'blue' },
    cumulativeSpecs: { color: 'blue' }
  },
  {
    product: 'gadget',
    date: ISODate('2024-01-02T00:00:00.000Z'),
    specs: { size: 'medium' },
    cumulativeSpecs: { color: 'blue', size: 'medium' }
  },
  {
    product: 'gadget',
    date: ISODate('2024-01-03T00:00:00.000Z'),
    specs: { weight: 0.5 },
    cumulativeSpecs: { color: 'blue', size: 'medium', weight: 0.5 }
  },
  {
    product: 'widget',
    date: ISODate('2024-01-01T00:00:00.000Z'),
    specs: { color: 'red' },
    cumulativeSpecs: { color: 'red' }
  },
  {
    product: 'widget',
    date: ISODate('2024-01-02T00:00:00.000Z'),
    specs: { material: 'plastic' },
    cumulativeSpecs: { color: 'red', material: 'plastic' }
  }
]

In the preceding pipeline:

$setWindowFields partitions documents by product and sorts by date in ascending order.
$mergeObjects uses an unbounded to current window to merge all specs documents from the beginning of each partition up to the current document, producing a running accumulated specification.
$sort sorts the final results by product and date in ascending order.

Back

$median

$min