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 : string|array|object

指定MapReduce操作的结果输出位置。您可以选择输出到集合或直接返回结果。在副本集的主成员上，您可以选择输出到集合或直接输出，但在副成员上，只能直接输出。

$options : array

一个数组，指定所需的选项。

名称	类型	描述
bypassDocumentValidation	布尔型	如果 `true`，则允许写操作绕过文档级别验证。默认为 `false`。这仅适用于结果输出到集合时。
排序	数组\|对象	排序允许用户指定字符串比较的语言特定规则，例如大小写和重音符号的规则。指定排序时，`locale` 字段是必需的；所有其他排序字段都是可选的。有关字段的描述，请参阅排序文档。如果未指定排序，但集合有默认排序，则操作使用为集合指定的排序。如果为集合或操作未指定排序，MongoDB 使用先前版本中用于字符串比较的简单二进制比较。
注释	混合	允许用户指定任意注释以帮助通过数据库分析器、当前操作输出和日志。此选项从 MongoDB 4.4 开始可用，如果为较旧的服务器版本指定，则在执行时会导致异常。新在版本1.13.
终结	MongoDB\BSON\Javascript	遵循 reduce 方法并修改输出。传递具有作用域的JavaScript实例已被弃用。将所有作用域变量放在MapReduce操作的`scope`选项中。
jsMode	布尔型	指定是否在执行 map 和 reduce 函数之间将中间数据转换为 BSON 格式。
limit	整数	指定输入到 map 函数的文档的最大数量。
maxTimeMS	整数	游标上操作处理的累积时间限制（以毫秒为单位）。MongoDB 在下一个中断点最早处中止操作。
query	数组\|对象	使用查询运算符指定选择标准，以确定输入到 map 函数的文档。
readConcern	MongoDB\Driver\ReadConcern	读取关注要用于操作。默认为集合的读取关注。在事务中无法指定单个操作的读取关注。相反，在开始事务时设置 `readConcern` 选项。
readPreference	MongoDB\Driver\ReadPreference	指定用于操作的读取偏好。默认为集合的读取偏好。当结果输出到集合时，此选项将被忽略。
作用域	数组\|对象	指定在map、reduce和finalize函数中可访问的全局变量。
会话	MongoDB\Driver\Session	与操作关联的客户端会话。新在版本1.3.
排序	数组\|对象	结果排序的排序规范。
typeMap	array	应用于游标的类型映射，它决定了BSON文档如何转换为PHP值。默认为集合的类型映射。
verbose	布尔型	指定是否在结果信息中包含计时信息。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作的写关注。默认为集合的写关注。在事务中无法为单个操作指定写关注。相反，在开始事务时时设置`writeConcern`选项。

返回值

AMongoDB\MapReduceResult 对象，允许无论输出方法（例如内联、集合）如何，都可以迭代 map-reduce 结果，通过 IteratorAggregate 接口。它还提供对命令统计数据的访问。

错误/异常

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

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

如果服务器的命令响应格式不正确，则抛出 MongoDB\Exception\UnexpectedValueException。

对于其他扩展级别的错误（例如连接错误），请参考 MongoDB\Driver\Exception\RuntimeException，如下的 SVG 图标所示：。

行为

在 MongoDB 中，map-reduce 操作可以将结果写入集合或直接返回。如果您将 map-reduce 输出写入集合，则可以在同一输入集合上执行后续的 map-reduce 操作，以合并替换、合并或减少新结果与旧结果。请参阅 Map-Reduce 和执行增量 Map-Reduce 获取详细信息示例。

当以内联方式返回 map-reduce 操作的结果时，结果文档必须在 BSON 文档大小限制内，目前限制为 16 兆字节。

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 命令参考，MongoDB手册
Map-Reduce 文档，MongoDB手册

listSearchIndexes()

rename()