w3resource
MongoDB Tutorial

MongoDB: db.collection.mapReduce() method

db.collection.mapReduce

The db.collection.mapReduce() method is used to performs map-reduce style data aggregation.

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

Syntax:

db.collection.mapReduce()

Parameters:

Name Description Required /
Optional
Type
out 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. Required string or document
query Specifies the selection criteria using query operators for determining the documents input to the map function. Optional document
sort Sorts the input documents. This option is useful for optimization. The sort key must be in an existing index for this collection. Required document
limit Specifies a maximum number of documents for the input into the map function. Required number
finalize Follows the reduce method and modifies the output. Optional function
scope Specifies global variables that are accessible in the map, reduce and finalize functions. Required document
jsMode 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 mappers emit() function.
The jsMode defaults to false.
Required boolean
verbose Specifies whether to include the timing information in the result information. The verbose defaults to true to include the timing information. Required boolean

Requirements for the map Function

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.)
  • A single emit can only hold half of MongoDBs maximum BSON document size.
  • The map function may optionally call emit(key,value) any number of times to create an output document associating key with value.

Requirements for the reduce Function

The reduce function has the following prototype:


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

Retrieve the restaurants data from here

Behaviors:

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.
  • The inputs to reduce must not be larger than half of MongoDBs maximum BSON document size. This requirement may be violated when large documents are returned and then joined together in subsequent reduce steps.

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 ] )

Previous: db.collection.isCapped() method
Next: db.collection.reIndex() method