- Reference >
- Database Commands >
- mapReduce
mapReduce¶
On this page
-
mapReduce
¶ The
mapReduce
command allows you to run map-reduce aggregation operations over a collection. ThemapReduce
command has the following prototype form: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. The command also accepts 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.
The following is a prototype usage of the
mapReduce
command:- map –
Important
When connected to a mongos
for a sharded
cluster, to use the mapReduce
directly, you must
specify the all-lower-case form of the command (i.e.``mapreduce``.)
Examples¶
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:
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