MongoDB\Database::aggregate()

本页内容

定义

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

新增自版本1.5.

定义

MongoDB\Database::aggregate()

执行指定的admin/diagnostic pipeline，它不需要底层集合。有关对集合数据的聚合，请参阅MongoDB\Collection::aggregate().

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

参数

$pipeline : 数组

指定一个聚合管道操作。

$options : 数组

指定所需选项的数组。

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

返回值

对象可以是MongoDB\Driver\Cursor或ArrayIterator。在这两种情况下，返回值都将为Traversable。

错误/异常

MongoDB\Exception\UnexpectedValueException 如果服务器命令响应格式不正确。

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

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

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

示例

以下聚合示例使用 $currentOp 聚合管道阶段列出所有正在运行的命令，然后过滤此列表以仅显示正在运行的命令操作。

<?php
$database = (new MongoDB\Client)->admin;
$cursor = $database->aggregate(
    [
        ['$currentOp' => []],
        ['$match' => ['op' => 'command']],
    ]
);

另请参阅

MongoDB\Collection::aggregate()
aggregate 命令参考，位于 MongoDB 手册中
聚合管道文档，位于 MongoDB 手册中

__get()

command()