Docs Menu
Docs Home
/
MongoDB Manual
/ / /

mapReduce

On this page

  • Definition
  • Syntax
  • Required Access
  • Restrictions
  • Map-Reduce Examples
  • Output
  • Additional Information

Note

Aggregation Pipeline as Alternative to Map-Reduce

An aggregation pipeline provides better performance and usability than a map-reduce operation.

Map-reduce operations can be rewritten using aggregation pipeline operators, such as $group, $merge, and others.

For map-reduce operations that require custom functionality, MongoDB provides the $accumulator and $function aggregation operators starting in version 4.4. Use these operators to define custom aggregation expressions in JavaScript.

For examples of aggregation pipeline alternatives to map-reduce operations, see Map-Reduce to Aggregation Pipeline and Map-Reduce Examples.

mapReduce

The mapReduce command allows you to run map-reduce aggregation operations over a collection.

Tip

In the mongo Shell, this command can also be run through the mapReduce() helper method.

Helper methods are convenient for mongo users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Note

Starting in version 4.4, MongoDB ignores the verbose option.

Starting in version 4.2, MongoDB deprecates:

  • The map-reduce option to create a new sharded collection as well as the use of the sharded option for map-reduce. To output to a sharded collection, create the sharded collection first. MongoDB 4.2 also deprecates the replacement of an existing sharded collection.

The mapReduce command has the following syntax:

db.runCommand( {
mapReduce: <string>,
map: <string or JavaScript>,
reduce: <string or JavaScript>,
finalize: <string or JavaScript>,
out: <output>,
query: <document>,
sort: <document>,
limit: <number>,
scope: <document>,
jsMode: <boolean>,
verbose: <boolean>,
bypassDocumentValidation: <boolean>,
collation: <document>,
maxTimeMS: <integer>,
writeConcern: <document>,
comment: <any>
} )

The command takes the following fields as arguments:

Field
Type
Description
string

The name of the collection on which you want to perform map-reduce. This collection will be filtered using query before being processed by the map function.

Note

Views do not support map-reduce operations.

JavaScript or String

A JavaScript function that associates or "maps" a value with a key and emits the key and value pair. You can specify the function as BSON type JavaScript (i.e. BSON type 13) or String (i.e. BSON type 2).

For more information, see Requirements for the map Function.

JavaScript or String

A JavaScript function that "reduces" to a single object all the values associated with a particular key. You can specify the function as BSON type JavaScript (i.e. BSON type 13) or String (i.e. BSON type 2).

For more information, see Requirements for the reduce Function.

string or document

Specifies where to output the result of the map-reduce operation. You can either output to a collection or return the result inline. On a primary member of a replica set you can output either to a collection or inline, but on a secondary, only inline output is possible.

For more information, see out Options.

document

Optional. Specifies the selection criteria using query operators for determining the documents input to the map function.

document

Optional. Sorts the input documents. This option is useful for optimization. For example, specify the sort key to be the same as the emit key so that there are fewer reduce operations. The sort key must be in an existing index for this collection.

number

Optional. Specifies a maximum number of documents for the input into the map function.

JavaScript or String

Optional. A JavaScript function that modifies the output after the reduce function. You can specify the function as BSON type JavaScript (i.e. BSON type 13) or String (i.e. BSON type 2).

For more information, see Requirements for the finalize Function.

document

Optional. Specifies global variables that are accessible in the map, reduce and finalize functions.

boolean

Optional. Specifies whether to convert intermediate data into BSON format between the execution of the map and reduce functions.

Defaults to false.

If false:

  • Internally, MongoDB converts the JavaScript objects emitted by the map function to BSON objects. These BSON objects are then converted back to JavaScript objects when calling the reduce function.

  • The map-reduce operation places the intermediate BSON objects in temporary, on-disk storage. This allows the map-reduce operation to execute over arbitrarily large data sets.

If true:

  • Internally, the JavaScript objects emitted during map function remain as JavaScript objects. There is no need to convert the objects for the reduce function, which can result in faster execution.

  • You can only use jsMode for result sets with fewer than 500,000 distinct key arguments to the mapper's emit() function.

boolean

Optional. Specifies whether to include the timing information in the result information. Set verbose to true to include the timing information.

Defaults to false.

Starting in MongoDB 4.4, this option is ignored. The result information always excludes the timing information. You can view timing information by running explain with the mapReduce command in the "executionStats" or "allPlansExecution" verbosity modes.

boolean

Optional. Enables mapReduce to bypass document validation during the operation. This lets you insert documents that do not meet the validation requirements.

New in version 3.2.

Note

If the output option is set to inline, no document validation occurs. If the output goes to a collection, mapReduce observes any validation rules which the collection has and does not insert any invalid documents unless the bypassDocumentValidation parameter is set to true.

document

Optional.

Specifies the collation to use for the operation.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The collation option has the following syntax:

collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}

When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.

If the collation is unspecified but the collection has a default collation (see db.createCollection()), the operation uses the collation specified for the collection.

If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.

New in version 3.4.

maxTimeMS
non-negative integer

Optional.

Specifies a time limit in milliseconds. If you do not specify a value for maxTimeMS, operations will not time out. A value of 0 explicitly specifies the default unbounded behavior.

MongoDB terminates operations that exceed their allotted time limit using the same mechanism as db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points.

document

Optional. A document that expresses the write concern to use when outputting to a collection. Omit to use the default write concern.

comment
any

Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:

A comment can be any valid BSON type (string, integer, object, array, etc).

New in version 4.4.

The following is a prototype usage of the mapReduce command:

var mapFunction = function() { ... };
var reduceFunction = function(key, values) { ... };
db.runCommand(
{
mapReduce: <input-collection>,
map: mapFunction,
reduce: reduceFunction,
out: { merge: <output-collection> },
query: <query>
}
)

Note

JavaScript in MongoDB

Although mapReduce uses JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application.

The map function is responsible for transforming each input document into zero or more documents. It can access the variables defined in the scope parameter, and has the following prototype:

function() {
...
emit(key, value);
}

The map function has the following requirements:

  • In the map function, reference the current document as this within the function.

  • The map function should not access the database for any reason.

  • The map function should be pure, or have no impact outside of the function (i.e. side effects.)

  • The map function may optionally call emit(key,value) any number of times to create an output document associating key with value.

  • In MongoDB 4.2 and earlier, a single emit can only hold half of MongoDB's maximum BSON document size. MongoDB removes this restriction starting in version 4.4.

  • Starting in MongoDB 4.4, mapReduce no longer supports the deprecated BSON type JavaScript code with scope (BSON type 15) for its functions. The map function must be either BSON type String (BSON type 2) or BSON type JavaScript (BSON type 13). To pass constant values which will be accessible in the map function, use the scope parameter.

    The use of JavaScript code with scope for the map function has been deprecated since version 4.2.1.

The following map function will call emit(key,value) either 0 or 1 times depending on the value of the input document's status field:

function() {
if (this.status == 'A')
emit(this.cust_id, 1);
}

The following map function may call emit(key,value) multiple times depending on the number of elements in the input document's items field:

function() {
this.items.forEach(function(item){ emit(item.sku, 1); });
}

The reduce function has the following prototype:

function(key, values) {
...
return result;
}

The reduce function exhibits the following behaviors:

  • The reduce function should not access the database, even to perform read operations.

  • The reduce function should not affect the outside system.

  • MongoDB can invoke the reduce function more than once for the same key. In this case, the previous output from the reduce function for that key will become one of the input values to the next reduce function invocation for that key.

  • The reduce function can access the variables defined in the scope parameter.

  • The inputs to reduce must not be larger than half of MongoDB's maximum BSON document size. This requirement may be violated when large documents are returned and then joined together in subsequent reduce steps.

  • Starting in MongoDB 4.4, mapReduce no longer supports the deprecated BSON type JavaScript code with scope (BSON type 15) for its functions. The reduce function must be either BSON type String (BSON type 2) or BSON type JavaScript (BSON type 13). To pass constant values which will be accessible in the reduce function, use the scope parameter.

    The use of JavaScript code with scope for the reduce function has been deprecated since version 4.2.1.

Because it is possible to invoke the reduce function more than once for the same key, the following properties need to be true:

  • the type of the return object must be identical to the type of the value emitted by the map function.

  • the reduce function must be associative. The following statement must be true:

    reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce( key, [ C, A, B ] )
  • the reduce function must be idempotent. Ensure that the following statement is true:

    reduce( key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray )
  • the reduce function should be commutative: that is, the order of the elements in the valuesArray should not affect the output of the reduce function, so that the following statement is true:

    reduce( key, [ A, B ] ) == reduce( key, [ B, A ] )

The finalize function has the following prototype:

function(key, reducedValue) {
...
return modifiedObject;
}

The finalize function receives as its arguments a key value and the reducedValue from the reduce function. Be aware that:

  • The finalize function should not access the database for any reason.

  • The finalize function should be pure, or have no impact outside of the function (i.e. side effects.)

  • The finalize function can access the variables defined in the scope parameter.

  • Starting in MongoDB 4.4, mapReduce no longer supports the deprecated BSON type JavaScript code with scope (BSON type 15) for its functions. The finalize function must be either BSON type String (BSON type 2) or BSON type JavaScript (BSON type 13). To pass constant values which will be accessible in the finalize function, use the scope parameter.

    The use of JavaScript code with scope for the finalize function has been deprecated since version 4.2.1.

You can specify the following options for the out parameter:

This option outputs to a new collection, and is not available on secondary members of replica sets.

out: <collectionName>

Note

Starting in version 4.2, MongoDB deprecates:

  • The map-reduce option to create a new sharded collection as well as the use of the sharded option for map-reduce. To output to a sharded collection, create the sharded collection first. MongoDB 4.2 also deprecates the replacement of an existing sharded collection.

This option is only available when passing a collection that already exists to out. It is not available on secondary members of replica sets.

out: { <action>: <collectionName>
[, db: <dbName>]
[, sharded: <boolean> ] }

When you output to a collection with an action, the out has the following parameters:

  • <action>: Specify one of the following actions:

    • replace

      Replace the contents of the <collectionName> if the collection with the <collectionName> exists.

    • merge

      Merge the new result with the existing result if the output collection already exists. If an existing document has the same key as the new result, overwrite that existing document.

    • reduce

      Merge the new result with the existing result if the output collection already exists. If an existing document has the same key as the new result, apply the reduce function to both the new and the existing documents and overwrite the existing document with the result.

  • db:

    Optional. The name of the database that you want the map-reduce operation to write its output. By default this will be the same database as the input collection.

  • sharded:

    Note

    Starting in version 4.2, the use of the sharded option is deprecated.

    Optional. If true and you have enabled sharding on output database, the map-reduce operation will shard the output collection using the _id field as the shard key.

    If true and collectionName is an existing unsharded collection, map-reduce fails.

Perform the map-reduce operation in memory and return the result. This option is the only available option for out on secondary members of replica sets.

out: { inline: 1 }

The result must fit within the maximum size of a BSON document.

If your MongoDB deployment enforces authentication, the user executing the mapReduce command must possess the following privilege actions:

Map-reduce with {out : inline} output option:

Map-reduce with the replace action when outputting to a collection:

Map-reduce with the merge or reduce actions when outputting to a collection:

The readWrite built-in role provides the necessary permissions to perform map-reduce aggregation.

MongoDB drivers automatically set afterClusterTime for operations associated with causally consistent sessions. Starting in MongoDB 4.2, the mapReduce command no longer support afterClusterTime. As such, mapReduce cannot be associated with causally consistent sessions.

In the mongo shell, the db.collection.mapReduce() method is a wrapper around the mapReduce command. The following examples use the db.collection.mapReduce() method:

The examples in this section include aggregation pipeline alternatives without custom aggregation expressions. For alternatives that use custom expressions, see Map-Reduce to Aggregation Pipeline Translation Examples.

Create a sample collection orders with these documents:

db.orders.insertMany([
{ _id: 1, cust_id: "Ant O. Knee", ord_date: new Date("2020-03-01"), price: 25, items: [ { sku: "oranges", qty: 5, price: 2.5 }, { sku: "apples", qty: 5, price: 2.5 } ], status: "A" },
{ _id: 2, cust_id: "Ant O. Knee", ord_date: new Date("2020-03-08"), price: 70, items: [ { sku: "oranges", qty: 8, price: 2.5 }, { sku: "chocolates", qty: 5, price: 10 } ], status: "A" },
{ _id: 3, cust_id: "Busby Bee", ord_date: new Date("2020-03-08"), price: 50, items: [ { sku: "oranges", qty: 10, price: 2.5 }, { sku: "pears", qty: 10, price: 2.5 } ], status: "A" },
{ _id: 4, cust_id: "Busby Bee", ord_date: new Date("2020-03-18"), price: 25, items: [ { sku: "oranges", qty: 10, price: 2.5 } ], status: "A" },
{ _id: 5, cust_id: "Busby Bee", ord_date: new Date("2020-03-19"), price: 50, items: [ { sku: "chocolates", qty: 5, price: 10 } ], status: "A"},
{ _id: 6, cust_id: "Cam Elot", ord_date: new Date("2020-03-19"), price: 35, items: [ { sku: "carrots", qty: 10, price: 1.0 }, { sku: "apples", qty: 10, price: 2.5 } ], status: "A" },
{ _id: 7, cust_id: "Cam Elot", ord_date: new Date("2020-03-20"), price: 25, items: [ { sku: "oranges", qty: 10, price: 2.5 } ], status: "A" },
{ _id: 8, cust_id: "Don Quis", ord_date: new Date("2020-03-20"), price: 75, items: [ { sku: "chocolates", qty: 5, price: 10 }, { sku: "apples", qty: 10, price: 2.5 } ], status: "A" },
{ _id: 9, cust_id: "Don Quis", ord_date: new Date("2020-03-20"), price: 55, items: [ { sku: "carrots", qty: 5, price: 1.0 }, { sku: "apples", qty: 10, price: 2.5 }, { sku: "oranges", qty: 10, price: 2.5 } ], status: "A" },
{ _id: 10, cust_id: "Don Quis", ord_date: new Date("2020-03-23"), price: 25, items: [ { sku: "oranges", qty: 10, price: 2.5 } ], status: "A" }
])

Perform the map-reduce operation on the orders collection to group by the cust_id, and calculate the sum of the price for each cust_id:

  1. Define the map function to process each input document:

    • In the function, this refers to the document that the map-reduce operation is processing.

    • The function maps the price to the cust_id for each document and emits the cust_id and price.

    var mapFunction1 = function() {
    emit(this.cust_id, this.price);
    };
  2. Define the corresponding reduce function with two arguments keyCustId and valuesPrices:

    • The valuesPrices is an array whose elements are the price values emitted by the map function and grouped by keyCustId.

    • The function reduces the valuesPrice array to the sum of its elements.

    var reduceFunction1 = function(keyCustId, valuesPrices) {
    return Array.sum(valuesPrices);
    };
  3. Perform map-reduce on all documents in the orders collection using the mapFunction1 map function and the reduceFunction1 reduce function:

    db.orders.mapReduce(
    mapFunction1,
    reduceFunction1,
    { out: "map_reduce_example" }
    )

    This operation outputs the results to a collection named map_reduce_example. If the map_reduce_example collection already exists, the operation will replace the contents with the results of this map-reduce operation.

  4. Query the map_reduce_example collection to verify the results:

    db.map_reduce_example.find().sort( { _id: 1 } )

    The operation returns these documents:

    { "_id" : "Ant O. Knee", "value" : 95 }
    { "_id" : "Busby Bee", "value" : 125 }
    { "_id" : "Cam Elot", "value" : 60 }
    { "_id" : "Don Quis", "value" : 155 }

Using the available aggregation pipeline operators, you can rewrite the map-reduce operation without defining custom functions:

db.orders.aggregate([
{ $group: { _id: "$cust_id", value: { $sum: "$price" } } },
{ $out: "agg_alternative_1" }
])
  1. The $group stage groups by the cust_id and calculates the value field (See also $sum). The value field contains the total price for each cust_id.

    The stage output the following documents to the next stage:

    { "_id" : "Don Quis", "value" : 155 }
    { "_id" : "Ant O. Knee", "value" : 95 }
    { "_id" : "Cam Elot", "value" : 60 }
    { "_id" : "Busby Bee", "value" : 125 }
  2. Then, the $out writes the output to the collection agg_alternative_1. Alternatively, you could use $merge instead of $out.

  3. Query the agg_alternative_1 collection to verify the results:

    db.agg_alternative_1.find().sort( { _id: 1 } )

    The operation returns the following documents:

    { "_id" : "Ant O. Knee", "value" : 95 }
    { "_id" : "Busby Bee", "value" : 125 }
    { "_id" : "Cam Elot", "value" : 60 }
    { "_id" : "Don Quis", "value" : 155 }

Tip

See also:

For an alternative that uses custom aggregation expressions, see Map-Reduce to Aggregation Pipeline Translation Examples.

In the following example, you will see a map-reduce operation on the orders collection for all documents that have an ord_date value greater than or equal to 2020-03-01.

The operation in the example:

  1. Groups by the item.sku field, and calculates the number of orders and the total quantity ordered for each sku.

  2. Calculates the average quantity per order for each sku value and merges the results into the output collection.

When merging results, if an existing document has the same key as the new result, the operation overwrites the existing document. If there is no existing document with the same key, the operation inserts the document.

Example steps:

  1. Define the map function to process each input document:

    • In the function, this refers to the document that the map-reduce operation is processing.

    • For each item, the function associates the sku with a new object value that contains the count of 1 and the item qty for the order and emits the sku (stored in the key) and the value.

    var mapFunction2 = function() {
    for (var idx = 0; idx < this.items.length; idx++) {
    var key = this.items[idx].sku;
    var value = { count: 1, qty: this.items[idx].qty };
    emit(key, value);
    }
    };
  2. Define the corresponding reduce function with two arguments keySKU and countObjVals:

    • countObjVals is an array whose elements are the objects mapped to the grouped keySKU values passed by map function to the reducer function.

    • The function reduces the countObjVals array to a single object reducedValue that contains the count and the qty fields.

    • In reducedVal, the count field contains the sum of the count fields from the individual array elements, and the qty field contains the sum of the qty fields from the individual array elements.

    var reduceFunction2 = function(keySKU, countObjVals) {
    reducedVal = { count: 0, qty: 0 };
    for (var idx = 0; idx < countObjVals.length; idx++) {
    reducedVal.count += countObjVals[idx].count;
    reducedVal.qty += countObjVals[idx].qty;
    }
    return reducedVal;
    };
  3. Define a finalize function with two arguments key and reducedVal. The function modifies the reducedVal object to add a computed field named avg and returns the modified object:

    var finalizeFunction2 = function (key, reducedVal) {
    reducedVal.avg = reducedVal.qty/reducedVal.count;
    return reducedVal;
    };
  4. Perform the map-reduce operation on the orders collection using the mapFunction2, reduceFunction2, and finalizeFunction2 functions:

    db.orders.mapReduce(
    mapFunction2,
    reduceFunction2,
    {
    out: { merge: "map_reduce_example2" },
    query: { ord_date: { $gte: new Date("2020-03-01") } },
    finalize: finalizeFunction2
    }
    );

    This operation uses the query field to select only those documents with ord_date greater than or equal to new Date("2020-03-01"). Then it outputs the results to a collection map_reduce_example2.

    If the map_reduce_example2 collection already exists, the operation will merge the existing contents with the results of this map-reduce operation. That is, if an existing document has the same key as the new result, the operation overwrites the existing document. If there is no existing document with the same key, the operation inserts the document.

  5. Query the map_reduce_example2 collection to verify the results:

    db.map_reduce_example2.find().sort( { _id: 1 } )

    The operation returns these documents:

    { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } }
    { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } }
    { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } }
    { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } }
    { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } }

Using the available aggregation pipeline operators, you can rewrite the map-reduce operation without defining custom functions:

db.orders.aggregate( [
{ $match: { ord_date: { $gte: new Date("2020-03-01") } } },
{ $unwind: "$items" },
{ $group: { _id: "$items.sku", qty: { $sum: "$items.qty" }, orders_ids: { $addToSet: "$_id" } } },
{ $project: { value: { count: { $size: "$orders_ids" }, qty: "$qty", avg: { $divide: [ "$qty", { $size: "$orders_ids" } ] } } } },
{ $merge: { into: "agg_alternative_3", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }
] )
  1. The $match stage selects only those documents with ord_date greater than or equal to new Date("2020-03-01").

  2. The $unwind stage breaks down the document by the items array field to output a document for each array element. For example:

    { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" }
    { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" }
    { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" }
    { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" }
    { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" }
    { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" }
    { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" }
    { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" }
    ...
  3. The $group stage groups by the items.sku, calculating for each sku:

    • The qty field. The qty field contains the
      total qty ordered per each items.sku (See $sum).
    • The orders_ids array. The orders_ids field contains an
      array of distinct order _id's for the items.sku (See $addToSet).
    { "_id" : "chocolates", "qty" : 15, "orders_ids" : [ 2, 5, 8 ] }
    { "_id" : "oranges", "qty" : 63, "orders_ids" : [ 4, 7, 3, 2, 9, 1, 10 ] }
    { "_id" : "carrots", "qty" : 15, "orders_ids" : [ 6, 9 ] }
    { "_id" : "apples", "qty" : 35, "orders_ids" : [ 9, 8, 1, 6 ] }
    { "_id" : "pears", "qty" : 10, "orders_ids" : [ 3 ] }
  4. The $project stage reshapes the output document to mirror the map-reduce's output to have two fields _id and value. The $project sets:

  5. The $unwind stage breaks down the document by the items array field to output a document for each array element. For example:

    { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" }
    { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" }
    { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" }
    { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" }
    { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" }
    { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" }
    { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" }
    { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" }
    ...
  6. The $group stage groups by the items.sku, calculating for each sku:

    • The qty field. The qty field contains the total qty ordered per each items.sku using $sum.

    • The orders_ids array. The orders_ids field contains an array of distinct order _id's for the items.sku using $addToSet.

    { "_id" : "chocolates", "qty" : 15, "orders_ids" : [ 2, 5, 8 ] }
    { "_id" : "oranges", "qty" : 63, "orders_ids" : [ 4, 7, 3, 2, 9, 1, 10 ] }
    { "_id" : "carrots", "qty" : 15, "orders_ids" : [ 6, 9 ] }
    { "_id" : "apples", "qty" : 35, "orders_ids" : [ 9, 8, 1, 6 ] }
    { "_id" : "pears", "qty" : 10, "orders_ids" : [ 3 ] }
  7. The $project stage reshapes the output document to mirror the map-reduce's output to have two fields _id and value. The $project sets:

    • the value.count to the size of the orders_ids array using $size.

    • the value.qty to the qty field of input document.

    • the value.avg to the average number of qty per order using $divide and $size.

    { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } }
    { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } }
    { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } }
    { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } }
    { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } }
  8. Finally, the $merge writes the output to the collection agg_alternative_3. If an existing document has the same key _id as the new result, the operation overwrites the existing document. If there is no existing document with the same key, the operation inserts the document.

  9. Query the agg_alternative_3 collection to verify the results:

    db.agg_alternative_3.find().sort( { _id: 1 } )

    The operation returns the following documents:

    { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } }
    { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } }
    { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } }
    { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } }
    { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } }

Tip

See also:

For an alternative that uses custom aggregation expressions, see Map-Reduce to Aggregation Pipeline Translation Examples.

For more information and examples, see the Map-Reduce page and Perform Incremental Map-Reduce.

If you set the out parameter to write the results to a collection, the mapReduce command returns a document in the following form:

{ "result" : "map_reduce_example", "ok" : 1 }
{
"result" : <string or document>,
"timeMillis" : <int>,
"counts" : {
"input" : <int>,
"emit" : <int>,
"reduce" : <int>,
"output" : <int>
},
"ok" : <int>,
}

If you set the out parameter to output the results inline, the mapReduce command returns a document in the following form:

{
"results" : [
{
"_id" : <key>,
"value" :<reduced or finalizedValue for key>
},
...
],
"ok" : <int>
}
{
"results" : [
{
"_id" : <key>,
"value" :<reduced or finalizedValue for key>
},
...
],
"timeMillis" : <int>,
"counts" : {
"input" : <int>,
"emit" : <int>,
"reduce" : <int>,
"output" : <int>
},
"ok" : <int>
}
mapReduce.result

For output sent to a collection, this value is either:

  • a string for the collection name if out did not specify the database name, or

  • a document with both db and collection fields if out specified both a database and collection name.

mapReduce.results

For output written inline, an array of resulting documents. Each resulting document contains two fields:

  • _id field contains the key value,

  • value field contains the reduced or finalized value for the associated key.

mapReduce.timeMillis

Available for MongoDB 4.2 and earlier only

The command execution time in milliseconds.

mapReduce.counts

Available for MongoDB 4.2 and earlier only

Various count statistics from the mapReduce command.

mapReduce.counts.input

Available for MongoDB 4.2 and earlier only

The number of input documents, which is the number of times the mapReduce command called the map function.

mapReduce.counts.emit

Available for MongoDB 4.2 and earlier only

The number of times the mapReduce command called the emit function.

mapReduce.counts.reduce

Available for MongoDB 4.2 and earlier only

The number of times the mapReduce command called the reduce function.

mapReduce.counts.output

Available for MongoDB 4.2 and earlier only

The number of output values produced.

mapReduce.ok

A value of 1 indicates the mapReduce command ran successfully. A value of 0 indicates an error.

In addition to the aforementioned command specific return fields, the db.runCommand() includes additional information:

  • for replica sets: $clusterTime, and operationTime.

  • for sharded clusters: operationTime and $clusterTime.

See db.runCommand Response for details on these fields.

Back

distinct