=================================
MongoDB\\Collection::mapReduce()
=================================
.. versionadded:: 1.2
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. phpmethod:: MongoDB\\Collection::mapReduce()
The :manual:`mapReduce </reference/command/mapReduce>` command allows you to
run map-reduce aggregation operations over a collection.
.. code-block:: php
function mapReduce($map, $reduce, $out, array $options = []): MongoDB\MapReduceResult
This method has the following parameters:
.. include:: /includes/apiargs/MongoDBCollection-method-mapReduce-param.rst
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBCollection-method-mapReduce-option.rst
Return Values
-------------
A :phpclass:`MongoDB\\MapReduceResult` object, which allows for iteration of
map-reduce results irrespective of the output method (e.g. inline, collection)
via the :php:`IteratorAggregate <iteratoraggregate>` interface. It also
provides access to command statistics.
Errors/Exceptions
-----------------
.. include:: /includes/extracts/error-unsupportedexception.rst
.. include:: /includes/extracts/error-invalidargumentexception.rst
.. include:: /includes/extracts/error-unexpectedvalueexception.rst
.. include:: /includes/extracts/error-driver-runtimeexception.rst
Behavior
--------
In MongoDB, the map-reduce operation can write results to a collection
or return the results inline. If you write map-reduce output to a
collection, you can perform subsequent map-reduce operations on the
same input collection that merge replace, merge, or reduce new results
with previous results. See :manual:`Map-Reduce </core/map-reduce>` and
:manual:`Perform Incremental Map-Reduce </tutorial/perform-incremental-map-reduce>`
for details and examples.
When returning the results of a map-reduce operation *inline*, the
result documents must be within the :limit:`BSON Document Size` limit,
which is currently 16 megabytes.
MongoDB supports map-reduce operations on :manual:`sharded collections
</sharding>`. Map-reduce operations can also output
the results to a sharded collection. See
:manual:`Map-Reduce and Sharded Collections </core/map-reduce-sharded-collections>`.
Example
-------
This example will use city populations to calculate the overall population of
each state.
.. code-block:: php
<?php
$collection = (new MongoDB\Client)->test->zips;
$map = new MongoDB\BSON\Javascript('function() { emit(this.state, this.pop); }');
$reduce = new MongoDB\BSON\Javascript('function(key, values) { return Array.sum(values) }');
$out = ['inline' => 1];
$populations = $collection->mapReduce($map, $reduce, $out);
foreach ($populations as $pop) {
var_dump($pop);
};
The output would then resemble::
object(stdClass)#2293 (2) {
["_id"]=>
string(2) "AK"
["value"]=>
float(544698)
}
object(stdClass)#2300 (2) {
["_id"]=>
string(2) "AL"
["value"]=>
float(4040587)
}
object(stdClass)#2293 (2) {
["_id"]=>
string(2) "AR"
["value"]=>
float(2350725)
}
object(stdClass)#2300 (2) {
["_id"]=>
string(2) "AZ"
["value"]=>
float(3665228)
}
See Also
--------
- :manual:`mapReduce </reference/command/mapReduce>` command reference in the MongoDB
manual
- :manual:`Map-Reduce </core/map-reduce>` documentation in the MongoDB manual
|
Download
