MongoDB\Collection::mapReduce()

自版本 1.12 起已弃用。

1.2版本新增。

定义

MongoDB\Collection::mapReduce()

mapReduce命令允许您对集合运行map-reduce聚合操作。

function mapReduce(
    MongoDB\BSON\JavascriptInterface $map,
    MongoDB\BSON\JavascriptInterface $reduce,
    string|array|object $out,
    array $options = []
): MongoDB\MapReduceResult

参数

$map : MongoDB\ BSON\ JavaScript

将值与键关联或“映射”并发出键值对的 JavaScript 函数。

注意

不推荐使用传递带有作用域的 Javascript 实例的方式。将所有范围变量放在 MapReduce 操作的scope选项中。

$reduce : MongoDB\ BSON\ JavaScript

一个 JavaScript 函数，用于将与特定键关联的所有值“减少”为单个对象。

注意

不推荐使用传递带有作用域的 Javascript 实例的方式。将所有范围变量放在 MapReduce 操作的scope选项中。

$out ：字符串|数组|对象

指定输出 map-reduce 操作结果的位置。您可以输出到collection，也可以以内联方式返回结果。在副本集的主节点上，您可以输出到collection或内联，但在从节点上，只能内联输出。

$options : array

指定所需选项的数组。

名称	类型	说明
bypassDocumentValidation	布尔	如果为 `true`，则允许写入操作规避文档级验证。默认为 `false`。这仅适用于将结果输出到collection的情况。
排序规则	数组\|对象	Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document. 如果未指定排序规则但集合具有默认排序规则，则操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。 1.13版本新增。
finalize	MongoDB\BSON\Javascript	遵循 reduce 方法并修改输出。不推荐使用传递带有作用域的 Javascript 实例的方式。将所有范围变量放在 MapReduce 操作的`scope`选项中。
jsMode	布尔	指定是否在执行 map 和 reduce 函数之间将中间数据转换为 BSON 格式。
limit	整型	指定输入到地图函数的最大文档数。
maxTimeMS	整型	The cumulative time limit in milliseconds for processing operations on the cursor. MongoDB aborts the operation at the earliest following interrupt point.
查询	数组\|对象	使用查询操作符指定选择条件，以确定输入到映射函数的文档。
事务外的	MongoDB\Driver\ReadConcern	Read concern to use for the operation. Defaults to the collection's read concern. 无法将单个操作的读关注（read concern）指定为ACID 事务的一部分。相反，请在启动ACID 事务时设立`readConcern` 选项。
readPreference	MongoDB\Driver\ReadPreference	Read preference to use for the operation. Defaults to the collection's read preference. 将结果输出到collection时，将忽略此选项。
范围	数组\|对象	指定可在 map、reduce 和 finalize 函数中访问的全局变量。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3版本新增。
sort	数组\|对象	对结果排序的排序规范。
typeMap	阵列	应用游标的类型映射，决定如何将BSON文档转换为PHP值。默认为集合的类型映射。
verbose	布尔	指定是否在结果信息中包含定时信息。
writeConcern	MongoDB\Driver\WriteConcern	Write concern to use for the operation. Defaults to the collection's write concern. 无法将单个操作的写关注（write concern）指定为ACID 事务的一部分。相反，请在启动ACID 事务时设立`writeConcern` 选项。

Return Values

一个MongoDB\MapReduceResult对象，它允许迭代map-reduce结果，而不考虑输出方法（例如inline, 集合)。它还提供对命令统计信息的访问权限。

错误/异常

MongoDB\Exception\UnsupportedException，如果所选服务器使用了选项但不支持选项（例如collation、readConcern、writeConcern）。

MongoDB\Exception\InvalidArgumentException 用于与参数或选项解析相关的错误。

MongoDB\Exception\UnexpectedValueException ，如果来自服务器的命令响应格式错误。

MongoDB\ 驱动程序\Exception\RuntimeException 用于扩展级别的其他错误（例如连接错误）。

行为

在MongoDB中， map-reduce操作可以写入集合或以内联方式返回结果。如果写入map-reduce输出写入集合，则可以对同一输入集合执行后续map-reduce操作，将新结果与以前的结果进行合并替换、合并或减少。有关详细信息和示例，请参阅Map-Reduce和执行增量 Map-Reduce 。

When returning the results of a map-reduce operation inline, the result documents must be within the BSON Document Size limit, which is currently 16 megabytes.

MongoDB 支持对分片集合执行 map-reduce 操作。 Map-reduce 操作还可以将结果输出到分片集合。请参阅Map-Reduce 和分片集合。

例子

此示例将使用城市人口来计算每个州的总人口。

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

而输出将类似如下所示：

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

另请参阅

mapReduce command reference in the MongoDB manual
MongoDB手册中的Map-Reduce文档