- Reference >
- JavaScript Methods >
- db.collection.mapReduce()
db.collection.mapReduce()¶
On this page
-
db.collection.
mapReduce
(map, reduce, {<out>, <query>, <sort>, <limit>, <finalize>, <scope>, <jsMode>, <verbose>})¶ The
db.collection.mapReduce()
method provides a wrapper around themapReduce
command.db.collection.mapReduce()
takes the following parameters:Parameters: - map –
A JavaScript function that associates or “maps” a
value
with akey
and emits thekey
and valuepair
.The
map
function processes every input document for the map-reduce operation. However, themap
function can call emit any number of times, including 0, for each input document. The map-reduce operation groups the emittedvalue
objects by thekey
and passes these groupings to thereduce
function. See below for requirements for themap
function. - reduce –
A JavaScript function that “reduces” to a single object all the
values
associated with a particularkey
.The
reduce
function accepts two arguments:key
andvalues
. Thevalues
argument is an array whose elements are thevalue
objects that are “mapped” to thekey
. See below for requirements for thereduce
function. - out –
New in version 1.8.
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. - query – Optional. Specifies the selection criteria using query
operators for determining the documents
input to the
map
function. - sort – 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.
- limit – Optional. Specifies a maximum number of documents to return from the collection.
- finalize –
Optional. A JavaScript function that follows the
reduce
method and modifies the output.The
finalize
function receives two arguments:key
andreducedValue
. ThereducedValue
is the value returned from thereduce
function for thekey
. - scope (document) – Optional. Specifies global variables that are accessible in the
map
,reduce
and thefinalize
functions. - jsMode (Boolean) –
New in version 2.0.
Optional. Specifies whether to convert intermediate data into BSON format between the execution of the
map
andreduce
functions.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 thereduce
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 thereduce
function, which can result in faster execution. - You can only use
jsMode
for result sets with fewer than 500,000 distinctkey
arguments to the mapper’semit()
function.
The
jsMode
defaults to false. - Internally, MongoDB converts the JavaScript objects emitted
by the
- verbose (Boolean) – Optional. Specifies whether to include the
timing
information in the result information. Theverbose
defaults totrue
to include thetiming
information.
- map –
Requirements for the map
Function¶
The map
function has the following prototype:
The map
function exhibits the following behaviors:
In the
map
function, reference the current document asthis
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 thekey
with avalue
.A single emit can only hold half of MongoDB’s maximum BSON document size.
The
map
function can callemit(key,value)
any number of times, including 0, per each input document.The following
map
function may callemit(key,value)
either 0 or 1 times depending on the value of the input document’sstatus
field:The following
map
function may callemit(key,value)
multiple times depending on the number of elements in the input document’sitems
field:
The
map
function can access the variables defined in thescope
parameter.
Requirements for the reduce
Function¶
The reduce
function has the following prototype:
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. - MongoDB can invoke the
reduce
function more than once for the same key. In this case, the previous output from thereduce
function for that key will become one of the input values to the nextreduce
function invocation for that key. - The
reduce
function can access the variables defined in thescope
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 themap
function to ensure that the following operations is true:the
reduce
function must be idempotent. Ensure that the following statement is true:the order of the elements in the
valuesArray
should not affect the output of thereduce
function, so that the following statement is true:
out
Options¶
You can specify the following options for the out
parameter:
Output to a Collection¶
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.
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. Iftrue
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
andreduce
output modes which may take minutes to execute.If
nonAtomic
istrue
, 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.
The result must fit within the maximum size of a BSON document.
Requirements for the finalize
Function¶
The finalize
function has the following prototype:
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 thescope
parameter.
Map-Reduce Examples¶
Consider the following map-reduce operations on a collection orders
that contains documents of the following prototype:
Return the Total Price Per Customer Id¶
Perform map-reduce operation on the orders
collection to group by
the cust_id
, and for each cust_id
, calculate the sum of the
price
for each cust_id
:
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 thecust_id
for each document and emits thecust_id
andprice
pair.
- In the function,
Define the corresponding reduce function with two arguments
keyCustId
andvaluesPrices
:- The
valuesPrices
is an array whose elements are theprice
values emitted by the map function and grouped bykeyCustId
. - The function reduces the
valuesPrice
array to the sum of its elements.
- The
Perform the map-reduce on all documents in the
orders
collection using themapFunction1
map function and thereduceFunction1
reduce function.This operation outputs the results to a collection named
map_reduce_example
. If themap_reduce_example
collection already exists, the operation will replace the contents with the results of this map-reduce operation:
Calculate the Number of Orders, Total Quantity, and 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 for each sku
calculates the number of orders and the
total quantity ordered. The operation concludes by calculating the average quantity per
order for each sku
value:
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 objectvalue
that contains thecount
of1
and the itemqty
for the order and emits thesku
andvalue
pair.
- In the function,
Define the corresponding reduce function with two arguments
keySKU
andvaluesCountObjects
:valuesCountObjects
is an array whose elements are the objects mapped to the groupedkeySKU
values passed by map function to the reducer function.- The function reduces the
valuesCountObjects
array to a single objectreducedValue
that also contains thecount
and theqty
fields. - In
reducedValue
, thecount
field contains the sum of thecount
fields from the individual array elements, and theqty
field contains the sum of theqty
fields from the individual array elements.
Define a finalize function with two arguments
key
andreducedValue
. The function modifies thereducedValue
object to add a computed field namedaverage
and returns the modified object:Perform the map-reduce operation on the
orders
collection using themapFunction2
,reduceFunction2
, andfinalizeFunction2
functions.This operation uses the
query
field to select only those documents withord_date
greater thannew Date(01/01/2012)
. Then it output the results to a collectionmap_reduce_example
. If themap_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.
See also
- map-reduce and
mapReduce
command - Aggregation Framework