DOCSP-38214: aggregation (#16)

* DOCSP-38214: aggregation

* CC fix

Author: rustagir

source/tutorials.txt

@@ -12,9 +12,9 @@ Tutorials
    /tutorials/read-ops/
    /tutorials/encrypt/
    /tutorials/write-ops/
+   /tutorials/aggregation/
 
 .. 
-   /tutorials/aggregation/
    /tutorials/change-stream/
    /tutorials/text-search/
    /tutorials/geo/
@@ -27,9 +27,9 @@ Tutorials
 - :ref:`scala-read-operations`
 - :ref:`scala-encrypt`
 - :ref:`scala-write-ops`
+- :ref:`scala-aggregation`
 
 .. 
-  - :ref:`scala-aggregation`
   - :ref:`scala-changestream`
   - :ref:`scala-text-search`
   - :ref:`scala-geo`

source/tutorials/aggregation.txt

@@ -0,0 +1,118 @@
+.. _scala-aggregation:
+
+=====================
+Aggregation Framework
+=====================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, create insights, change data
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+The aggregation pipeline is a framework for data aggregation,
+modeled on the concept of data processing pipelines.
+
+To learn more about aggregation, see :manual:`Aggregation Pipeline
+</core/aggregation-pipeline/>` in the Server manual.
+
+Prerequisites
+-------------
+
+.. include:: /includes/prereq-restaurants.rst
+
+.. code-block:: scala
+
+   import org.mongodb.scala._
+
+   import org.mongodb.scala.model.Aggregates._
+   import org.mongodb.scala.model.Accumulators._
+   import org.mongodb.scala.model.Filters._
+   import org.mongodb.scala.model.Projections._
+
+.. include:: /includes/obs-note.rst
+
+Connect to a MongoDB Deployment
+-------------------------------
+
+.. include:: /includes/connect-section.rst
+
+Perform Aggregation
+-------------------
+
+To perform aggregation, pass a list of aggregation stages to the
+``MongoCollection.aggregate()`` method. The driver provides the
+``Aggregates`` helper class that contains builders for aggregation
+stages.
+
+In this example, the aggregation pipeline performs the
+following tasks:
+
+- Uses a ``$match`` stage to filter for documents in which the
+  ``categories`` array field contains the element ``"Bakery"``. The example
+  uses ``Aggregates.filter()`` to build the ``$match`` stage.
+
++ Uses a ``$group`` stage to group the matching documents by
+  the ``stars`` field, accumulating a count of documents for each distinct
+  value of ``stars``. The example uses ``Aggregates.group()`` to build the
+  ``$group`` stage and ``Accumulators.sum()`` to build the accumulator
+  expression. For the accumulator expressions for use within the
+  ``$group`` stage, the driver provides ``Accumulators`` helper
+  class.
+
+.. code-block:: scala
+
+   collection.aggregate(Seq(
+       Aggregates.filter(Filters.equal("categories", "Bakery")),
+       Aggregates.group("$stars", Accumulators.sum("count", 1))
+   )).printResults()
+
+Use Aggregation Expressions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For ``$group`` accumulator expressions, the driver provides the
+``Accumulators`` helper class. For other aggregation expressions,
+manually build the expression by using the ``Document`` class.
+
+In the following example, the aggregation pipeline uses a
+``$project`` stage to return only the ``name`` field and the calculated
+field ``firstCategory`` whose value is the first element in the
+``categories`` array. The example uses ``Aggregates.project()`` and
+various ``Projections`` class methods to build the ``$project`` stage:
+
+.. code-block:: scala
+
+   collection.aggregate(
+     Seq(
+       Aggregates.project(
+         Projections.fields(
+           Projections.excludeId(),
+           Projections.include("name"),
+           Projections.computed(
+             "firstCategory",
+             Document("$arrayElemAt"-> Seq("$categories", 0))
+           )
+         )
+       )
+     )
+   ).printResults()
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To ``$explain`` an aggregation pipeline, call the
+``AggregatePublisher.explain()`` method:
+
+.. code-block:: scala
+
+   collection.aggregate(
+     Seq(Aggregates.filter(Filters.eq("categories", "Bakery")),
+         Aggregates.group("$stars", Accumulators.sum("count", 1)))
+   ).explain().printResults()