通过聚合转换数据

在此页面上

Overview
比较聚合与查找操作
限制
聚合 API
Array API
筛选和分组示例
解释聚合
聚合构建器
筛选和分组示例
展开嵌入式数组示例
单个等值连接示例
更多信息
MongoDB Server 手册
Atlas Search和 Vector Search
API 文档

Overview

在本指南中，您可以学习；了解如何使用MongoDB PHP库执行聚合操作。

聚合操作处理 MongoDB 集合中的数据并返回计算结果。 MongoDB 聚合框架是 Query API 的一部分，以数据处理管道的概念为模型。文档进入包含一个或多个阶段的管道，该管道将文档转换为聚合结果。

聚合操作类似于汽车工厂。汽车工厂有一条装配线，其中包含配备专用工具的装配站，用于完成特定的工作，例如钻机和焊机。毛坯零件会进入工厂，然后装配线将其转换并组装为成品。

聚合管道是装配线，聚合阶段是装配站，操作符表达式则是专用工具。

比较聚合与查找操作

您可以使用查找操作执行以下动作：

选择要返回的文档
选择要返回的字段
对结果进行排序

您可以使用聚合操作执行以下动作：

运行查找操作
重命名字段
计算字段
汇总数据
对值进行分组

限制

执行聚合操作时要考虑以下限制：

返回的文档不能违反16 MB 的BSON文档大小限制。
默认，管道阶段的内存限制为100 MB。您可以创建一个选项大量，将allowDiskUse选项设置为true ，然后将该大量传递给MongoDB\Collection::aggregate()方法，从而超过此限制。
重要
$graphLookup 异常
$graphLookup阶段有100 MB 的严格内存限制，并忽略allowDiskUse选项。

聚合 API

PHP库提供以下 API 来创建聚合管道：

数组API：通过传递指定聚合阶段的数组来创建聚合管道。
聚合构建器：使用工厂方法创建聚合管道，提高应用程序的类型安全性和可调试性。

以下部分介绍了每个API ，并提供了创建聚合管道的示例。

Array API

要执行聚合，请将包含管道阶段的大量作为BSON文档传递给 MongoDB\Collection::aggregate() 方法，如以下代码所示：

$pipeline = [
    ['<stage>' => <parameters>],
    ['<stage>' => <parameters>],
    ...
];
$cursor = $collection->aggregate($pipeline);

本部分中的示例使用Atlas示例数据集的sample_restaurants数据库中的restaurants集合。要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅Atlas入门指南。

筛选和分组示例

以下代码示例计算纽约每个区的面包店数量。为此，它使用包含以下阶段的聚合管道：

$match阶段，用于过滤cuisine字段包含值'Bakery'的文档
$ 群组阶段按borough字段对匹配文档进行群组，并累积每个不同值的文档计数

$pipeline = [
    ['$match' => ['cuisine' => 'Bakery']],
    ['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]],
];
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":"Brooklyn","count":173}
{"_id":"Queens","count":204}
{"_id":"Bronx","count":71}
{"_id":"Staten Island","count":20}
{"_id":"Missing","count":2}
{"_id":"Manhattan","count":221}

解释聚合

要查看有关MongoDB如何执行您的操作的信息，您可以指示MongoDB查询规划器对其进行解释。 MongoDB解释操作时，会返回执行计划和性能统计信息。执行计划是MongoDB完成操作的一种潜在方式。当您指示MongoDB解释一个操作时，它会返回MongoDB执行的计划和任何被拒绝的执行计划。

要解释聚合操作，请构造一个MongoDB\Operation\Aggregate对象并将数据库阶段、集合阶段和管道阶段作为参数传递。然后，将MongoDB\Operation\Aggregate对象传递给MongoDB\Collection::explain()方法。

以下示例指示MongoDB解释上一节中的聚合操作：

$pipeline = [
    ['$match' => ['cuisine' => 'Bakery']],
    ['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]],
];
$aggregate = new MongoDB\Operation\Aggregate(
    $collection->getDatabaseName(),
    $collection->getCollectionName(),
    $pipeline
);
$result = $collection->explain($aggregate);
echo json_encode($result), PHP_EOL;

{"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants",
"indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3",
"planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false,
"maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{
... }

聚合构建器

要使用聚合构建器创建聚合管道，请执行以下操作：

创建一个大量来存储管道阶段。
对于每个阶段，从 Stage 中调用与所需聚合阶段同名的工厂方法。示例，要创建 $unwind 阶段，请调用 Stage::unwind() 方法。
在 Stage 方法的主体中，使用其他构建器类（例如 Query、Expression 或 Accumulator）中的方法来Express您的聚合规范。

以下代码演示了用于构建聚合管道的模板：

$pipeline = [
    Stage::<factory method>(
        <stage specification>
    ),
    Stage::<factory method>(
        <stage specification>
    ),
    ...
];
$cursor = $collection->aggregate($pipeline);

本节中的示例改编自MongoDB Server手册。每个示例都提供了示例数据的链接，您可以将其插入数据库以测试聚合操作。

提示

与构建者合作

您可以使用构建者来支持非聚合操作，例如查找和更新操作。要学习；了解更多信息，请参阅《Operations with Builders》指南。

筛选和分组示例

此示例使用服务器手册中 $group 阶段参考的计算计数、总和和平均值部分中给出的示例数据。

以下代码示例计算 2014 年每一天的总销售额、平均销售数量和销售计数。为此，它使用包含以下阶段的聚合管道：

$match 阶段，用于过滤包含 date字段且年份为 2014 的文档
$群组阶段，按日期对文档进行群组，并计算群组的总销售额、平均销售数量和销售计数
$sort 阶段，用于按群组的总销售额降序对结果进行排序

$pipeline = [
    MongoDB\Builder\Stage::match(
        date: [
            MongoDB\Builder\Query::gte(new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2014-01-01'))),
            MongoDB\Builder\Query::lt(new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2015-01-01'))),
        ],
    ),
    MongoDB\Builder\Stage::group(
        _id: MongoDB\Builder\Expression::dateToString(MongoDB\Builder\Expression::dateFieldPath('date'), '%Y-%m-%d'),
        totalSaleAmount: MongoDB\Builder\Accumulator::sum(
            MongoDB\Builder\Expression::multiply(
                MongoDB\Builder\Expression::numberFieldPath('price'),
                MongoDB\Builder\Expression::numberFieldPath('quantity'),
            ),
        ),
        averageQuantity: MongoDB\Builder\Accumulator::avg(
            MongoDB\Builder\Expression::numberFieldPath('quantity'),
        ),
        count: MongoDB\Builder\Accumulator::sum(1),
    ),
    MongoDB\Builder\Stage::sort(
        totalSaleAmount: MongoDB\Builder\Type\Sort::Desc,
    ),
];
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":"2014-04-04","totalSaleAmount":{"$numberDecimal":"200"},"averageQuantity":15,"count":2}
{"_id":"2014-03-15","totalSaleAmount":{"$numberDecimal":"50"},"averageQuantity":10,"count":1}
{"_id":"2014-03-01","totalSaleAmount":{"$numberDecimal":"40"},"averageQuantity":1.5,"count":2}

展开嵌入式数组示例

此示例使用服务器手册中 $unwind 阶段参考的展开嵌入式数组部分中给出的示例数据。

以下代码示例按标签对售出的商品进行分组，并计算每个标签的总销售额。为此，它使用包含以下阶段的聚合管道：

$unwind 阶段，为大量中的每个元素输出单独的文档items
$unwind 阶段为 items.tags 数组中的每个元素输出单独的文档
$ 群组阶段，按标签值对文档群组，并计算具有每个标签的商品的总销售额

$pipeline = [
    MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items')),
    MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items.tags')),
    MongoDB\Builder\Stage::group(
        _id: MongoDB\Builder\Expression::fieldPath('items.tags'),
        totalSalesAmount: MongoDB\Builder\Accumulator::sum(
            MongoDB\Builder\Expression::multiply(
                MongoDB\Builder\Expression::numberFieldPath('items.price'),
                MongoDB\Builder\Expression::numberFieldPath('items.quantity'),
            ),
        ),
    ),
];
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":"office","totalSalesAmount":{"$numberDecimal":"1019.60"}}
{"_id":"school","totalSalesAmount":{"$numberDecimal":"104.85"}}
{"_id":"stationary","totalSalesAmount":{"$numberDecimal":"264.45"}}
{"_id":"electronics","totalSalesAmount":{"$numberDecimal":"800.00"}}
{"_id":"writing","totalSalesAmount":{"$numberDecimal":"60.00"}}

单个等值连接示例

此示例使用服务器手册中 $lookup 阶段引用的“使用 $lookup 执行单个等值连接”部分中给出的示例数据。

以下代码示例使用 orders集合中的 item字段和 inventory集合中的 sku字段，将 orders集合中的文档与 inventory集合中的文档连接起来。

为此，该示例使用的聚合管道包含$lookup阶段，该阶段指定要从中检索数据的集合以及本地和外部字段名称。

$pipeline = [
    MongoDB\Builder\Stage::lookup(
        from: 'inventory',
        localField: 'item',
        foreignField: 'sku',
        as: 'inventory_docs',
    ),
];
/* Performs the aggregation on the orders collection */
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":1,"item":"almonds","price":12,"quantity":2,"inventory_docs":[{"_id":1,"sku":"almonds","description":"product 1","instock":120}]}
{"_id":2,"item":"pecans","price":20,"quantity":1,"inventory_docs":[{"_id":4,"sku":"pecans","description":"product 4","instock":70}]}
{"_id":3,"inventory_docs":[{"_id":5,"sku":null,"description":"Incomplete"},{"_id":6}]}

通过聚合转换数据

Overview

比较聚合与查找操作

限制

重要

$graphLookup 异常

聚合 API

Array API

筛选和分组示例

解释聚合

聚合构建器

提示

与构建者合作

筛选和分组示例

展开嵌入式数组示例

单个等值连接示例

更多信息

MongoDB Server 手册

Atlas Search和 Vector Search

API 文档