MongoDB\Collection::aggregate()

定义

MongoDB\Collection::aggregate()

对集合执行聚合框架管道操作。

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

参数

$pipeline ：大量|管道

指定聚合管道操作。您可以在 MongoDB\Builder\Pipeline实例或大量中包含聚合阶段。

$options : array

指定所需选项的数组。

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

Return Values

MongoDB\ 驱动程序\Cursor 或 ArrayIterator 对象。在这两种情况下，返回值均为 Traversable。

错误/异常

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

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

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

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

行为

MongoDB\Collection::aggregate() 返回一个 MongoDB\ 驱动程序\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()

• MongoDB 手册中的聚合命令参考

• MongoDB 手册中的聚合管道文档