DOCSP-43919: aggregation builder

Author: rustagir

snooty.toml

@@ -41,6 +41,7 @@ php-library = "MongoDB PHP Library"
 [constants]
 php-library = "MongoDB PHP Library"
 version = "1.20"
+source-gh-branch = "v1.x"
 full-version = "{+version+}.0"
 extension-short = "PHP extension"
 mdb-server = "MongoDB Server"

source/aggregation.txt

@@ -47,8 +47,8 @@ The **aggregation pipeline** is the assembly line, **aggregation stages** are th
 assembly stations, and **operator expressions** are the
 specialized tools.
 
-Aggregation Versus Find Operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Compare Aggregation and Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can use find operations to perform the following actions:
 
@@ -82,20 +82,46 @@ Consider the following limitations when performing aggregation operations:
      </reference/operator/aggregation/graphLookup/>` stage has a strict
      memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
 
-.. _php-aggregation-example:
+Aggregation APIs
+----------------
 
-Aggregation Example
--------------------
+The {+library-short+} provides the following APIs to create aggregation
+pipelines:
 
-.. note::
+- :ref:`php-aggregation-array-api`: Create aggregation pipelines by
+  passing arrays that specify the aggregation operators and parameters 
+- :ref:`php-aggregation-builder-api`: Create aggregation pipelines by using native
+  classes and methods to make your application more type-safe and debuggable
+
+The following sections describe each API and provide examples for
+creating aggregation pipelines.
+
+.. _php-aggregation-array-api:
 
-   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.
+Array API
+---------
 
-To perform an aggregation, pass an array containing the pipeline stages to
-the ``MongoDB\Collection::aggregate()`` method.
+To perform an aggregation, pass an array containing the pipeline stages
+as BSON documents to the ``MongoDB\Collection::aggregate()`` method, as
+shown in the following code:
+
+.. code-block:: php
+    
+   $pipeline = [
+       ['<operator>' => <parameters>],
+       ['<operator>' => <parameters>],
+       ...
+   ];
+   
+   $cursor = $collection->aggregate($pipeline);
+  
+The examples in this section 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.
+
+Filter and Group Example
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 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:
@@ -110,9 +136,9 @@ of New York. To do so, it uses an aggregation pipeline that contains the followi
 .. io-code-block::
    :copyable:
 
-   .. input:: /includes/aggregation/aggregation.php
-      :start-after: start-match-group
-      :end-before: end-match-group
+   .. input:: /includes/aggregation.php
+      :start-after: start-array-match-group
+      :end-before: end-array-match-group
       :language: php
       :dedent:
 
@@ -141,14 +167,14 @@ and pass the database, collection, and pipeline stages as parameters. Then, pass
 ``MongoDB\Operation\Aggregate`` object to the ``MongoDB\Collection::explain()`` method.
 
 The following example instructs MongoDB to explain the aggregation operation
-from the preceding :ref:`php-aggregation-example`:
+from the preceding section:
 
 .. io-code-block::
    :copyable:
 
-   .. input:: /includes/aggregation/aggregation.php
-      :start-after: start-explain
-      :end-before: end-explain
+   .. input:: /includes/aggregation.php
+      :start-after: start-array-explain
+      :end-before: end-array-explain
       :language: php
       :dedent:
 
@@ -161,6 +187,162 @@ from the preceding :ref:`php-aggregation-example`:
       "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{
       ... }
 
+.. _php-aggregation-builder-api:
+
+Aggregation Builder
+-------------------
+
+To create an aggregation pipeline by using the Aggregation Builder,
+perform the following actions:
+
+#. Create a ``Pipeline`` class instance to initialize the pipeline
+
+#. Within the ``Pipeline`` instance, call an operator method from the ``Stage``
+   builder class to create that type of aggregation stage
+
+#. Within the body of the ``Stage`` method, use methods from other
+   builder classes such as ``Query``, ``Expression``, or ``Accumulator``
+   to express your aggregation specifications
+
+The following code demonstrates the template for constructing
+aggregation pipelines:
+
+.. code-block:: php
+
+   $pipeline = new Pipeline(
+       Stage::<operator method>(
+           <stage specification>
+       ),
+       Stage::<operator method>(
+           <stage specification>
+       ),
+       ...
+   );
+   
+   $cursor = $collection->aggregate(iterator_to_array($pipeline));
+
+.. note::
+    
+   The preceding code uses the ``iterator_to_array()`` method to
+   convert the ``Pipeline`` instance into an array. You must call this method
+   on your ``Pipeline`` before passing it to the ``aggregate()`` method.
+
+The examples in this section are adapted from the {+mdb-server+} manual.
+Each example provides a link to the sample data that you can insert into
+your database to test the aggregation operation.
+
+Filter and Group Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example uses the sample data given in the :manual:`Calculate Count,
+Sum, and Average </reference/operator/aggregation/group/#calculate-count--sum--and-average>`
+section of the ``$group`` stage reference in the Server manual.
+
+The following code example calculates the total sales amount, average
+sales quantity, and sale count for each day in the year 2014. To do so,
+it uses an aggregation pipeline that contains the following stages:
+
+- :manual:`$match </reference/operator/aggregation/match/>` stage to
+  filter for documents that contain a ``date`` field in which the year is
+  2014
+
+- :manual:`$group </reference/operator/aggregation/group/>` stage to
+  group the documents by date and calculate the total sale amount,
+  average quantity, and total count for each group
+  
+- :manual:`$sort </reference/operator/aggregation/sort/>` stage to
+  sort the results by the total sale amount for each group in descending
+  order
+  
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.php
+      :start-after: start-builder-match-group
+      :end-before: end-builder-match-group
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_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 Embedded Arrays Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example uses the sample data given in the :manual:`Unwind Embedded Arrays
+</reference/operator/aggregation/unwind/#unwind-embedded-arrays>`
+section of the ``$unwind`` stage reference in the Server manual.
+
+The following code example groups sold items by their tags and
+calculates the total sales amount for each tag. To do so,
+it uses an aggregation pipeline that contains the following stages:
+
+- :manual:`$unwind </reference/operator/aggregation/unwind/>` stage to
+  output a separate document for each element in the ``items`` array
+
+- :manual:`$unwind </reference/operator/aggregation/unwind/>` stage to
+  output a separate document for each element in the ``items.tags`` arrays
+  
+- :manual:`$group </reference/operator/aggregation/group/>` stage to
+  group the documents by the tag value and calculates the total sales
+  amount of items that have each tag
+  
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.php
+      :start-after: start-builder-unwind
+      :end-before: end-builder-unwind
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_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"}}
+
+Single Equality Join Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example uses the sample data given in the :manual:`Perform a Single
+Equality Join with $lookup
+</reference/operator/aggregation/lookup/#perform-a-single-equality-join-with--lookup>`
+section of the ``$lookup`` stage reference in the Server manual.
+
+The following code example joins the documents from the ``orders``
+collection with the documents from the ``inventory`` collection by using
+the ``item`` field from the ``orders`` collection and the ``sku`` field
+from the ``inventory`` collection.
+
+To do so, the example uses an aggregation pipeline that contains a 
+:manual:`$lookup </reference/operator/aggregation/lookup/>` stage that
+specifies the collection to retrieve data from and the local and
+foreign field names.
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.php
+      :start-after: start-builder-lookup
+      :end-before: end-builder-lookup
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_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}]}
+
 Additional Information
 ----------------------
 
@@ -169,6 +351,11 @@ pipelines, see `Complex Aggregation Pipelines with Vanilla PHP and MongoDB
 <https://www.mongodb.com/developer/products/mongodb/aggregations-php-mongodb/>`__
 in the MongoDB Developer Center.
 
+To view more examples of aggregation pipelines built by using the Aggregation
+Builder, see the :github:`Stage class test suite
+<mongodb/mongo-php-library/tree/{+source-gh-branch+}/tests/Builder/Stage>` in the
+{+library-short+} source code on GitHub.
+
 MongoDB Server Manual
 ~~~~~~~~~~~~~~~~~~~~~