• Reference >
• mongo Shell Methods >
• Collection Methods >
• db.collection.mapReduce()

db.collection.mapReduce()

db.collection.mapReduce(map, reduce, {<out>, <query>, <sort>, <limit>, <finalize>, <scope>, <jsMode>, <verbose>})

The db.collection.mapReduce() method provides a wrapper around the mapReduce command.

copy

db.collection.mapReduce(
                         <map>,
                         <reduce>,
                         {
                           out: <collection>,
                           query: <document>,
                           sort: <document>,
                           limit: <number>,
                           finalize: <function>,
                           scope: <document>,
                           jsMode: <boolean>,
                           verbose: <boolean>
                         }
                       )

db.collection.mapReduce() takes the following parameters:

Field	Type	Description
map	Javascript function	A JavaScript function that associates or “maps” a value with a key and emits the key and value pair. See Requirements for the map Function for more information.
reduce	JavaScript function	A JavaScript function that “reduces” to a single object all the values associated with a particular key. See Requirements for the reduce Function for more information.
options	document	A document that specifies additional parameters to db.collection.mapReduce().

The following table describes additional arguments that db.collection.mapReduce() can accept.

Field	Type	Description
query	document	Optional. Specifies the selection criteria using query operators for determining the documents input to the map function.
sort	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.
limit	number	Optional. Specifies a maximum number of documents to return from the collection.
scope	document	Optional. Specifies global variables that are accessible in the map, reduce and finalize functions.
jsMode	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. The jsMode defaults to false.
verbose	Boolean	Optional. Specifies whether to include the timing information in the result information. The verbose defaults to true to include the timing information.
out	string or document	Specifies the location of the result of the map-reduce operation. You can output to a collection, output to a collection with an action, or output inline. You may output to a collection when performing map reduce operations on the primary members of the set; on secondary members you may only use the inline output. See out Options for more information.
finalize	Javascript function	Optional. Follows the reduce method and modifies the output. See Requirements for the finalize Function for more information.

Note

Changed in version 2.4.

In MongoDB 2.4, map-reduce operations, the group command, and $where operator expressions cannot access certain global functions or properties, such as db, that are available in the mongo shell.

When upgrading to MongoDB 2.4, you will need to refactor your code if your map-reduce operations, group commands, or $where operator expressions include any global shell functions or properties that are no longer available, such as db.

The following JavaScript functions and properties are available to map-reduce operations, the group command, and $where operator expressions in MongoDB 2.4:

Available Properties	Available Functions
args MaxKey MinKey	assert() BinData() DBPointer() DBRef() doassert() emit() gc() HexData() hex_md5() isNumber() isObject() ISODate() isString()	Map() MD5() NumberInt() NumberLong() ObjectId() print() printjson() printjsononeline() sleep() Timestamp() tojson() tojsononeline() tojsonObject() UUID() version()

Requirements for the map Function

The map function has the following prototype:

copy

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

The map function exhibits the following behaviors:

• 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 emit(key,value) function associates the key with a value.

  • A single emit can only hold half of MongoDB’s maximum BSON document size.

  • The map function can call emit(key,value) any number of times, including 0, per each input document.

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

    copy

    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:

    copy

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

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

Requirements for the reduce Function

The reduce function has the following prototype:

copy

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 will not call the reduce function for a key that has only a single value. The values argument is an array whose elements are the value objects that are “mapped” to the key.
• 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.

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 to ensure that the following operations is true:

  copy

  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:

  copy

  reduce( key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray )
  

• the order of the elements in the valuesArray should not affect the output of the reduce function, so that the following statement is true:

  copy

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

out Options

You can specify the following options for the out parameter:

Output to a Collection

copy

out: <collectionName>

Output to a Collection with an Action

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

copy

out: { <action>: <collectionName>
        [, db: <dbName>]
        [, sharded: <boolean> ]
        [, nonAtomic: <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:

  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.

• nonAtomic:

  New in version 2.2.

  Optional. Specify output operation as non-atomic and is valid only for merge and reduce output modes which may take minutes to execute.

  If nonAtomic is true, the post-processing step will prevent MongoDB from locking the database; however, other clients will be able to read intermediate states of the output collection. Otherwise the map reduce operation must lock the database during post-processing.

Output Inline

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.

copy

out: { inline: 1 }

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

Requirements for the finalize Function

The finalize function has the following prototype:

copy

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.

Map-Reduce Examples

Consider the following map-reduce operations on a collection orders that contains documents of the following prototype:

copy

{
     _id: ObjectId("50a8240b927d5d8b5891743c"),
     cust_id: "abc123",
     ord_date: new Date("Oct 04, 2012"),
     status: 'A',
     price: 25,
     items: [ { sku: "mmm", qty: 5, price: 2.5 },
              { sku: "nnn", qty: 5, price: 2.5 } ]
}

Return the Total Price Per Customer

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 pair.
   copy

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

   var reduceFunction1 = function(keyCustId, valuesPrices) {
                             return Array.sum(valuesPrices);
                         };
   

3. Perform the map-reduce on all documents in the orders collection using the mapFunction1 map function and the reduceFunction1 reduce function.

   copy

   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:

Calculate Order and Total Quantity with Average Quantity Per Item

In this example, you will perform a map-reduce operation on the orders collection for all documents that have an ord_date value greater than 01/01/2012. The operation groups by the item.sku field, and calculates the number of orders and the total quantity ordered for each sku. The operation concludes by calculating the average quantity per order for each sku value:

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 and value pair.
   copy

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

   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:

   copy

   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.

   copy

   db.orders.mapReduce( mapFunction2,
                        reduceFunction2,
                        {
                          out: { merge: "map_reduce_example" },
                          query: { ord_date:
                                     { $gt: new Date('01/01/2012') }
                                 },
                          finalize: finalizeFunction2
                        }
                      )
   

   This operation uses the query field to select only those documents with ord_date greater than new Date(01/01/2012). Then it output the results to a collection map_reduce_example. If the map_reduce_example collection already exists, the operation will merge the existing contents with the results of this map-reduce operation.

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

See also

• Troubleshoot the Map Function
• Troubleshoot the Reduce Function
• mapReduce command
• Aggregation Concepts

←   db.collection.isCapped() db.collection.reIndex()  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.