Skip to content

Commit 68ed80c

Browse files
kvwalkerkvwalker
authored
PHPLIB-53 Add documentation for mapReduce (#419)
PHPLIB-53 Add documentation for mapReduce
1 parent 29a6234 commit 68ed80c

File tree

4 files changed

+252
-0
lines changed

4 files changed

+252
-0
lines changed

‎source/includes/apiargs-MongoDBCollection-method-mapReduce-option.yaml

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
source:
2+
file: apiargs-MongoDBCollection-common-option.yaml
3+
ref: bypassDocumentValidation
4+
---
5+
source:
6+
file: apiargs-MongoDBCollection-common-option.yaml
7+
ref: collation
8+
---
9+
arg_name: option
10+
name: finalize
11+
type: :php:`MongoDB\\BSON\\Javascript <class.mongodb-bson-javascript>`
12+
description: |
13+
Follows the reduce method and modifies the output.
14+
interface: phpmethod
15+
operation: ~
16+
optional: true
17+
---
18+
arg_name: option
19+
name: jsMode
20+
type: boolean
21+
description: |
22+
Specifies whether to convert intermediate data into BSON format between the
23+
execution of the map and reduce functions. The default is ``false``.
24+
interface: phpmethod
25+
operation: ~
26+
optional: true
27+
---
28+
arg_name: option
29+
name: limit
30+
type: integer
31+
description: |
32+
Specifies a maximum number of documents for the input into the map function.
33+
interface: phpmethod
34+
operation: ~
35+
optional: true
36+
---
37+
source:
38+
file: apiargs-common-option.yaml
39+
ref: maxTimeMS
40+
---
41+
arg_name: option
42+
name: query
43+
type: document
44+
description: |
45+
Specifies the selection criteria using query operators for determining the
46+
documents input to the map function.
47+
interface: phpmethod
48+
operation: ~
49+
optional: true
50+
---
51+
source:
52+
file: apiargs-MongoDBCollection-common-option.yaml
53+
ref: readConcern
54+
---
55+
source:
56+
file: apiargs-MongoDBCollection-common-option.yaml
57+
ref: readPreference
58+
---
59+
arg_name: option
60+
name: scope
61+
type: document
62+
description: |
63+
Specifies global variables that are accessible in the map, reduce, and finalize
64+
functions.
65+
interface: phpmethod
66+
operation: ~
67+
optional: true
68+
---
69+
source:
70+
file: apiargs-MongoDBCollection-method-find-option.yaml
71+
ref: sort
72+
---
73+
source:
74+
file: apiargs-MongoDBCollection-common-option.yaml
75+
ref: typeMap
76+
---
77+
arg_name: option
78+
name: verbose
79+
type: boolean
80+
description: |
81+
Specifies whether to include the timing information in the result information.
82+
The default is ``true``.
83+
interface: phpmethod
84+
operation: ~
85+
optional: true
86+
---
87+
source:
88+
file: apiargs-MongoDBCollection-common-option.yaml
89+
ref: writeConcern
90+
...

‎source/includes/apiargs-MongoDBCollection-method-mapReduce-param.yaml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
arg_name: param
2+
name: $map
3+
type: :php:`MongoDB\\BSON\\Javascript <mongodb-bson-javascript>`
4+
description: |
5+
A JavaScript function that associates or "maps" a value with a key and emits
6+
the key and value pair.
7+
interface: phpmethod
8+
operation: ~
9+
optional: false
10+
---
11+
arg_name: param
12+
name: $reduce
13+
type: :php:`MongoDB\\BSON\\Javascript <class.mongodb-bson-javascript>`
14+
description: |
15+
A JavaScript function that "reduces" to a single object all the values
16+
associated with a particular key.
17+
interface: phpmethod
18+
operation: ~
19+
optional: false
20+
---
21+
arg_name: param
22+
name: $out
23+
type: string|document
24+
description: |
25+
Specifies where to output the result of the map-reduce operation. You can
26+
either output to a collection or return the result inline. On a primary member
27+
of a replica set you can output either to a collection or inline, but on a
28+
secondary, only inline output is possible.
29+
interface: phpmethod
30+
operation: ~
31+
optional: false
32+
---
33+
source:
34+
file: apiargs-common-param.yaml
35+
ref: $options
36+
...

‎source/reference/class/MongoDBCollection.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ Methods
8787
/reference/method/MongoDBCollection-insertMany
8888
/reference/method/MongoDBCollection-insertOne
8989
/reference/method/MongoDBCollection-listIndexes
90+
/reference/method/MongoDBCollection-mapReduce
9091
/reference/method/MongoDBCollection-replaceOne
9192
/reference/method/MongoDBCollection-updateMany
9293
/reference/method/MongoDBCollection-updateOne

‎source/reference/method/MongoDBCollection-mapReduce.txt

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
=================================
2+
MongoDB\\Collection::mapReduce()
3+
=================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\Collection::mapReduce()
17+
18+
The :manual:`mapReduce </reference/command/mapReduce>` command allows you to
19+
run map-reduce aggregation operations over a collection.
20+
21+
.. code-block:: php
22+
23+
function mapReduce($map, $reduce, $out, array $options = []): MongoDB\MapReduceResult
24+
25+
This method has the following parameters:
26+
27+
.. include:: /includes/apiargs/MongoDBCollection-method-mapReduce-param.rst
28+
29+
The ``$options`` parameter supports the following options:
30+
31+
.. include:: /includes/apiargs/MongoDBCollection-method-mapReduce-option.rst
32+
33+
Return Values
34+
-------------
35+
36+
A :phpclass:`MongoDB\\MapReduceResult` object, which allows for iteration of
37+
mapReduce results irrespective of the output method (e.g. inline, collection)
38+
via the :php:`IteratorAggregate <iteratoraggregate>` interface. It also
39+
provides access to command statistics.
40+
41+
Errors/Exceptions
42+
-----------------
43+
44+
.. include:: /includes/extracts/error-unsupportedexception.rst
45+
.. include:: /includes/extracts/error-invalidargumentexception.rst
46+
.. include:: /includes/extracts/error-unexpectedvalueexception.rst
47+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
48+
49+
Behavior
50+
--------
51+
52+
In MongoDB, the map-reduce operation can write results to a collection
53+
or return the results inline. If you write map-reduce output to a
54+
collection, you can perform subsequent map-reduce operations on the
55+
same input collection that merge replace, merge, or reduce new results
56+
with previous results. See :manual:`Map-Reduce </core/map-reduce>` and
57+
:manual:`Perform Incremental Map-Reduce </tutorial/perform-incremental-map-reduce>`
58+
for details and examples.
59+
60+
When returning the results of a map-reduce operation *inline*, the
61+
result documents must be within the :limit:`BSON Document Size` limit,
62+
which is currently 16 megabytes.
63+
64+
MongoDB supports map-reduce operations on :manual:`sharded collections
65+
</sharding>`. Map-reduce operations can also output
66+
the results to a sharded collection. See
67+
:manual:`Map-Reduce and Sharded Collections </core/map-reduce-sharded-collections>`.
68+
69+
Example
70+
-------
71+
72+
This example will use city populations to calculate the overall population of
73+
each state.
74+
75+
.. code-block:: php
76+
77+
<?php
78+
79+
$collection = (new MongoDB\Client)->test->zips;
80+
81+
$map = new MongoDB\BSON\Javascript('function() { emit(this.state, this.pop); }');
82+
$reduce = new MongoDB\BSON\Javascript('function(key, values) { return Array.sum(values) }');
83+
$out = ['inline' => 1];
84+
85+
$populations = $collection->mapReduce($map, $reduce, $out);
86+
87+
foreach ($populations as $pop) {
88+
var_dump($pop);
89+
};
90+
91+
The output would then resemble::
92+
93+
object(stdClass)#2293 (2) {
94+
["_id"]=>
95+
string(2) "AK"
96+
["value"]=>
97+
float(544698)
98+
}
99+
object(stdClass)#2300 (2) {
100+
["_id"]=>
101+
string(2) "AL"
102+
["value"]=>
103+
float(4040587)
104+
}
105+
object(stdClass)#2293 (2) {
106+
["_id"]=>
107+
string(2) "AR"
108+
["value"]=>
109+
float(2350725)
110+
}
111+
object(stdClass)#2300 (2) {
112+
["_id"]=>
113+
string(2) "AZ"
114+
["value"]=>
115+
float(3665228)
116+
}
117+
118+
119+
See Also
120+
--------
121+
122+
- :manual:`mapReduce </reference/command/mapReduce>` command reference in the MongoDB
123+
manual
124+
- :manual:`Map-Reduce </core/map-reduce>` documentation in the MongoDB manual
125+

0 commit comments

Comments
 (0)