Docs4dev
Docs
mongodb / v3.6 / reference / reference-command-mapReduce.html

mapReduce

On this page

mapReduce

The mapReduce command allows you to run map-reduce aggregation operations over a collection. The mapReduce command has the following prototype form:

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

Pass the name of the collection to the mapReduce command (i.e. <collection>) to use as the source documents to perform the map-reduce operation.

Note

Views do not support map-reduce operations.

The command also accepts the following parameters:

Field Type Description
mapReduce collection 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.
map 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 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.
out 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.

See out Options for more information.
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 for the input into the map function.
finalize function

Optional. Follows the reduce method and modifies the output.

See Requirements for the finalize Function for more information.
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.
verbose 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.
bypassDocumentValidation 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.
collation 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.
writeConcern document Optional. A document that expresses the write concern to use when outputing to a collection. Omit to use the default write concern.

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

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.

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 MongoDB’s 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.

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); });
}

Requirements for the reduce Function

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 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 MongoDB’s 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: