MongoDB\Collection::aggregate()

在此页面上

定义

参数
Return Values
错误/异常
行为
示例
另请参阅

定义

MongoDB\Collection::aggregate()

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

参数

$pipeline : array

指定聚合管道操作。

$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	读取关注以用于操作。默认为集合的读关注。无法将单个操作的读关注指定为事务的一部分。相反，请在`readConcern` 启动事务时设置选项。
readPreference	MongoDB\Driver\ReadPreference	读取要用于操作的偏好。默认为集合的读取偏好。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3 版本中的新增功能。
typeMap	阵列	类型映射应用于游标，决定如何将 BSON 文档转换为 PHP 值。默认为集合的类型映射。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作。默认为集合的写关注。无法将单个操作的写关注指定为事务的一部分。相反，请在`writeConcern` 启动事务时设置选项。这仅适用于指定 $out 或 $merge 阶段时的情况。

Return Values

A MongoDB\Driver\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 手册中的聚合管道文档

后退

__construct()

来年

bulkWrite()