MongoDB\Collection::aggregate()

本页内容

定义

参数
返回值
错误/异常
行为
示例
另请参阅

定义

MongoDB\Collection::aggregate()

function aggregate(
    array $pipeline,
    array $options = []
): Traversable

参数

$pipeline : array

指定一个聚合管道操作。

$options : array

指定所需选项的数组。

名称	类型	描述
allowDiskUse	布尔值	启用写入临时文件。当设置为`true`时，聚合阶段可以将数据写入`dbPath`目录下的`_tmp`子目录。
batchSize	整数	指定游标的批处理大小，该大小将应用于初始的`聚合`命令和任何后续的`getMore`命令。这决定了从服务器返回的每个响应中可返回的最大文档数。当`0`的批处理大小是特殊的，它只会应用于初始的`聚合`命令；后续的`getMore`命令将使用服务器的默认批处理大小。这可以用于快速从`聚合`返回游标或失败，而不进行大量的服务器端工作。
bypassDocumentValidation	布尔值	如果设置为`true`，允许写操作绕过文档级验证。默认为`false`。这仅适用于使用$out和$out阶段。
codec	MongoDB\Codec\DocumentCodec	用于编码或解码文档的`codec`。此选项与`typeMap`选项互斥。默认为集合的codec。默认`codec`选项的继承优先于`typeMap`选项。默认为集合的codec。默认`codec`选项的继承优先于`typeMap`选项。新在版本1.17.
collation	数组\|对象	校对允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定校对时，`locale`字段是必需的；所有其他校对字段都是可选的。有关字段的说明，请参阅校对文档。如果未指定校对，但集合具有默认校对，则操作使用集合指定的校对。如果集合或操作未指定校对，MongoDB将使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	允许用户指定任意注释以帮助通过数据库分析器、当前操作输出和日志跟踪操作。注释可以是服务器版本4.4及以上的任何有效BSON类型。早期服务器版本仅支持字符串值。新在版本1.3.
explain	布尔值	指定是否返回管道处理的信息。新在版本1.4.
hint	字符串\|数组\|对象	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。新在版本1.3.
let	数组\|对象	参数名称和值的映射。值必须是常数或封闭表达式，不引用文档字段。然后可以在聚合表达式上下文中作为变量访问参数（例如`$$var`）。此功能不支持服务器版本低于5.0，如果在执行时使用，将导致异常。新在版本1.9.
maxTimeMS	整数	处理游标上操作的总时间限制（以毫秒为单位）。MongoDB会在最早的中断点后中止操作。
readConcern	MongoDB\Driver\ReadConcern	读关注用于操作的。默认为集合的读关注。在事务中无法为单个操作指定读关注。相反，在开始事务时设置`readConcern`选项。
readPreference	MongoDB\Driver\ReadPreference	读偏好用于操作的。默认为集合的读偏好。
session	MongoDB\Driver\Session	与操作关联的客户端会话。新在版本1.3.
typeMap	array	应用于游标的类型映射，它决定了BSON文档如何转换为PHP值。默认为集合的类型映射。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作的。默认为集合的写关注。在事务中无法指定单个操作的写入关注点。相反，在开始事务时设置`writeConcern`选项。这仅适用于指定了$out或$merge阶段的情况。

返回值

一个 MongoDB\Driver\Cursor 或 ArrayIterator 对象。在两种情况下，返回值都将为可遍历的。

错误/异常

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

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

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

MongoDB\Driver\Exception\RuntimeException 对于扩展级别的其他错误（例如连接错误）。

行为

MongoDB\Collection::aggregate() 方法返回一个 MongoDB\Driver\Cursor 对象。

示例

以下聚合示例使用名为 names 的集合，并将 first_name 字段分组，计算每个组的结果总数，并按名称排序。

<?php
$collection = (new MongoDB\Client)->test->names;
$cursor = $collection->aggregate(
    [
        ['$group' => ['_id' => '$first_name', 'name_count' => ['$sum' => 1]]],
        ['$sort' => ['_id' => 1]],
    ]
);

另请参阅

MongoDB\Database::aggregate()
aggregate 命令参考 MongoDB 手册
聚合管道文档 MongoDB 手册

__construct()

bulkWrite()