MongoDB\Collection::mapReduce()

定义

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的情况。
排序规则	数组|对象	排序规则允许用户为string比较指定特定于语言的规则，例如字母大小写和重音符号规则。 指定排序规则时， locale字段为必填字段；所有其他排序规则字段都是可选的。 有关字段的说明，请参阅排序规则文档。 如果未指定排序规则但集合具有默认排序规则，则操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。 自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.13 版本中的新增功能。
finalize	MongoDB\BSON\Javascript	遵循 reduce 方法并修改输出。 不推荐使用传递带有作用域的 Javascript 实例的方式。 将所有范围变量放在 MapReduce 操作的scope选项中。
jsMode	布尔	指定是否在执行 map 和 reduce 函数之间将中间数据转换为 BSON 格式。
limit	整型	指定输入到地图函数的最大文档数。
maxTimeMS	整型	处理游标操作的累计时间限制（以毫秒为单位）。MongoDB 最早会在中断点之后中止操作。
查询	数组|对象	使用查询操作符指定选择条件，以确定输入到映射函数的文档。
事务外的	MongoDB\Driver\ReadConcern	读取关注以用于操作。 默认为集合的读关注。 无法将单个操作的读关注指定为事务的一部分。 相反，请在readConcern 启动事务 时设置 选项。
readPreference	MongoDB\Driver\ReadPreference	读取要用于操作的偏好。 默认为集合的读取偏好。 将结果输出到collection时，将忽略此选项。
范围	数组|对象	指定可在 map、reduce 和 finalize 函数中访问的全局变量。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3 版本中的新增功能。
sort	数组|对象	对结果排序的排序规范。
typeMap	阵列	类型映射 应用于游标，决定如何将 BSON 文档转换为 PHP 值。默认为集合的类型映射。
verbose	布尔	指定是否在结果信息中包含定时信息。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作。默认为集合的写关注。 无法将单个操作的写关注指定为事务的一部分。 相反，请在writeConcern 启动事务 时设置 选项。

Return Values

一个 MongoDB\MapReduceResult对象，允许对map-reduce结果进行迭代，而与输出方法无关（例如 inline, 集合) 通过 IteratorAggregate 接口。它还提供对命令统计信息的访问权限。

错误/异常

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 。

返回map-reduce操作inline的结果时，结果文档必须在BSON文档大小限制（当前为16 MB）之内。

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

另请参阅

• MongoDB 手册中的mapReduce命令参考

• MongoDB手册中的Map-Reduce文档