DOCSP-41988: Aggregation

source/aggregation.txt

@@ -0,0 +1,197 @@
+.. _php-aggregation:
+
+====================================
+Transform Your Data with Aggregation
+====================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, transform, computed, pipeline
+   :description: Learn how to use the PHP library to perform aggregation operations.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. TODO:
+ .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    /aggregation/aggregation-tutorials
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+php-library+} to perform
+**aggregation operations**.
+
+Aggregation operations process data in your MongoDB collections and
+return computed results. The MongoDB Aggregation framework, which is
+part of the Query API, is modeled on the concept of data processing
+pipelines. Documents enter a pipeline that contains one or more stages,
+and this pipeline transforms the documents into an aggregated result.
+
+An aggregation operation is similar to a car factory. A car factory has
+an assembly line, which contains assembly stations with specialized
+tools to do specific jobs, like drills and welders. Raw parts enter the
+factory, and then the assembly line transforms and assembles them into a
+finished product.
+
+The **aggregation pipeline** is the assembly line, **aggregation stages** are the
+assembly stations, and **operator expressions** are the
+specialized tools.
+
+Aggregation Versus Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use find operations to perform the following actions:
+
+- Select which documents to return
+- Select which fields to return
+- Sort the results
+
+You can use aggregation operations to perform the following actions:
+
+- Run find operations
+- Rename fields
+- Calculate fields
+- Summarize data
+- Group values
+
+Limitations
+~~~~~~~~~~~
+
+Keep the following limitations in mind when using aggregation operations:
+
+- Returned documents cannot violate the
+  :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
+  of 16 megabytes.
+- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
+  limit by creating an options array that sets the ``allowDiskUse`` option to ``true``
+  and passing the array to the ``MongoDB\Collection::aggregate()`` method.
+
+.. important:: $graphLookup Exception
+
+   The :manual:`$graphLookup
+   </reference/operator/aggregation/graphLookup/>` stage has a strict
+   memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
+
+.. _php-aggregation-example:
+
+Aggregation Example
+-------------------
+
+.. note::
+
+   The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+   database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+   free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas
+   </getting-started>` guide.
+
+To perform an aggregation, pass an array containing the aggregation pipeline
+stages to the ``MongoDB\Collection::aggregate()`` method.
+
+The following code example produces a count of the number of bakeries in each borough
+of New York. To do so, it uses an aggregation pipeline that contains the following stages:
+
+- :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
+  in which the ``cuisine`` field contains the value ``'Bakery'``
+
+- :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
+  documents by the ``borough`` field, accumulating a count of documents for each distinct
+  value
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.php
+      :start-after: start-match-group
+      :end-before: end-match-group
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_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}
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, you can
+instruct the MongoDB query planner to **explain** it. When MongoDB explains
+an operation, it returns **execution plans** and performance statistics.
+An execution plan is a potential way MongoDB can complete an operation.
+When you instruct MongoDB to explain an operation, it returns both the
+plan MongoDB executed and any rejected execution plans.
+
+To explain an aggregation operation, run the ``explain`` database command by passing
+the command information to the ``MongoDB\Database::command()`` method. You must set the
+``aggregate``, ``pipeline``, and ``cursor`` fields of the ``explain`` command document
+to explain the aggregation.
+
+The following example instructs MongoDB to explain the aggregation operation from the
+preceding :ref:`php-aggregation-example`:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.php
+      :start-after: start-explain
+      :end-before: end-explain
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"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":{
+      ... }
+
+
+Additional Information
+----------------------
+
+MongoDB Server Manual
+~~~~~~~~~~~~~~~~~~~~~
+
+To view a full list of expression operators, see :manual:`Aggregation
+Operators. </reference/operator/aggregation/>`
+
+To learn about assembling an aggregation pipeline and view examples, see
+:manual:`Aggregation Pipeline. </core/aggregation-pipeline/>`
+
+To learn more about creating pipeline stages, see :manual:`Aggregation
+Stages. </reference/operator/aggregation-pipeline/>`
+
+To learn more about explaining MongoDB operations, see
+:manual:`Explain Output </reference/explain-results/>` and
+:manual:`Query Plans. </core/query-plans/>`
+
+.. TODO:
+ Aggregation Tutorials
+ ~~~~~~~~~~~~~~~~~~~~~
+
+.. To view step-by-step explanations of common aggregation tasks, see
+.. :ref:`php-aggregation-tutorials-landing`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information about executing aggregation operations by using the {+php-library+},
+see `MongoDB\\Collection::aggregate() <{+api+}/method/MongoDBCollection-aggregate/>`__ in
+the API documentation.

source/includes/aggregation.php

@@ -0,0 +1,43 @@
+<?php
+require 'vendor/autoload.php';
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+$db = $client->sample_restaurants;
+$collection = $db->restaurants;
+
+// Retrieves documents with a cuisine value of "Bakery", groups them by "borough", and
+// counts each borough's matching documents
+// start-match-group
+$pipeline = [
+    ['$match' => ['cuisine' => 'Bakery']],
+    ['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]]
+];
+
+$cursor = $collection->aggregate($pipeline);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-match-group
+
+// Performs the same aggregation operation as above but asks MongoDB to explain it
+// start-explain
+$pipeline = [
+    ['$match' => ['cuisine' => 'Bakery']],
+    ['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]]
+];
+
+$command = [
+    'explain' => [
+        'aggregate' => 'restaurants',
+        'pipeline' => $pipeline,
+        'cursor' => new stdClass()
+    ]
+];
+
+$result = $db->command($command)->toArray();
+echo json_encode($result[0]) . PHP_EOL;
+// end-explain
+

source/index.txt

@@ -12,6 +12,7 @@ MongoDB PHP Library
 
    Get Started </get-started>
    /read
+   /aggregation
    /tutorial
    /upgrade
    /reference