aggregation

Author: rachel-mack

source/aggregation.txt

@@ -45,6 +45,12 @@ The **aggregation pipeline** is the assembly line, **aggregation
 stages** are the assembly stations, and **operator expressions** are the
 specialized tools.
 
+For more information about aggregation in the {+driver-short+}, see the
+following pages:
+
+- :ref:`<java-aggregation-expression-operations>`
+- :ref:`<java-aggregation-examples>`
+
 Compare Aggregation and Find Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -83,213 +89,3 @@ Useful References
 - :manual:`Aggregation stages </meta/aggregation-quick-reference/#stages>`
 - :manual:`Operator expressions </meta/aggregation-quick-reference/#operator-expressions>`
 - :ref:`Aggregation Builders <aggregates-builders>`
-
-Runnable Examples
------------------
-
-Import Classes
-~~~~~~~~~~~~~~
-
-Create a new Java file called ``AggTour.java`` and include the following import statements:
-
-.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java
-   :language: java
-   :dedent:
-   :start-after: begin imports
-   :end-before: end imports
-
-Connect to a MongoDB Deployment
-+++++++++++++++++++++++++++++++
-
-.. code-block:: java
-
-   public class AggTour {
-
-       public static void main(String[] args) {
-           // Replace the uri string with your MongoDB deployment's connection string
-           String uri = "<connection string>";
-
-           MongoClient mongoClient = MongoClients.create(uri);
-           MongoDatabase database = mongoClient.getDatabase("aggregation");
-           MongoCollection<Document> collection = database.getCollection("restaurants");
-
-           // Paste the aggregation code here
-       }
-   }
-
-.. tip::
-
-   To learn more about connecting to MongoDB, see the :ref:`Connection
-   Guide <java-connect-to-mongodb>`.
-
-Insert Sample Data
-++++++++++++++++++
-
-.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java
-   :language: java
-   :dedent:
-   :start-after: begin insert
-   :end-before: end insert
-
-Basic Aggregation Example
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To perform an aggregation, pass a list of aggregation stages to the
-``MongoCollection.aggregate()`` method.
-
-The Java driver provides the
-`Aggregates <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html>`__
-helper class that contains builders for aggregation stages.
-
-In the following example, the aggregation pipeline:
-
-- Uses a :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents whose
-  ``categories`` array field contains the element ``Bakery``. The example uses
-  ``Aggregates.match`` to build the ``$match`` stage.
-
-- Uses a :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching documents by the ``stars``
-  field, accumulating a count of documents for each distinct value of ``stars``.
-
-.. note::
-
-   You can build the expressions used in this example using the :ref:`aggregation builders <aggregates-builders>`.
-
-.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java
-   :language: java
-   :dedent:
-   :start-after: begin aggregation basic
-   :end-before: end aggregation basic
-
-The preceding aggregation produces the following results:
-
-.. code-block:: none
-   :copyable: false
-
-   {"_id": 4, "count": 2}
-   {"_id": 5, "count": 1}
-
-For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
-
-- `MongoCollection.aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__
-- `Aggregates.match <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#match(org.bson.conversions.Bson)>`__
-
-Explain Aggregation Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To view information about how MongoDB executes your operation, use the
-``explain()`` method of the ``AggregateIterable`` class. The ``explain()``
-method returns **execution plans** and performance statistics. An execution
-plan is a potential way MongoDB can complete an operation.
-The ``explain()`` method provides both the winning plan, which is the plan MongoDB
-executed, and any rejected plans.
-
-.. tip::
-   
-   To learn more about query plans and execution statistics, see
-   :manual:`Explain Results </reference/explain-results/>` in the Server manual.
-
-.. include:: /includes/fundamentals/explain-verbosity.rst
-
-The following example prints the JSON representation of the
-winning plans for any aggregation stages that produce execution plans:
-
-.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java
-   :language: java
-   :dedent:
-   :start-after: begin aggregation explain
-   :end-before: end aggregation explain
-
-The example produces the following output as the ``$group`` stage
-is the only stage that produces an execution plan:
-
-.. code-block:: none
-   :copyable: false
-
-   {
-     "stage": "GROUP",
-     "planNodeId": 2,
-     "inputStage": {
-       "stage": "COLLSCAN",
-       "planNodeId": 1,
-       "filter": {
-         "categories": {
-           "$eq": "Bakery"
-         }
-       },
-       "direction": "forward"
-     }
-   }
-
-For more information about the topics mentioned in this section, see the
-following resources:
-
-- :manual:`Explain Output </reference/explain-results/>` Server Manual Entry
-- :manual:`Query Plans </core/query-plans/>` Server Manual Entry
-- `ExplainVerbosity <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ExplainVerbosity>`__ API Documentation
-- `explain() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#explain()>`__ API Documentation
-- `AggregateIterable <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html>`__ API Documentation
-
-Aggregation Expression Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The {+driver-short+} provides builders for accumulator expressions for use with
-``$group``. You must declare all other expressions in JSON format or
-compatible document format.
-
-.. tip::
-
-   The syntax in either of the following examples will define an :manual:`$arrayElemAt </reference/operator/aggregation/arrayElemAt/>`
-   expression.
-
-   The ``$`` in front of "categories" tells MongoDB that this is a :manual:`field path </meta/aggregation-quick-reference/#expressions>`,
-   using the ``categories`` field from the input document.
-
-   .. code-block:: java
-      :copyable: false
-
-      new Document("$arrayElemAt", Arrays.asList("$categories", 0))
-
-   .. code-block:: java
-      :copyable: false
-
-      Document.parse("{ $arrayElemAt: ['$categories', 0] }")
-
-   Alternatively, you can construct expressions by using the Aggregation
-   Expression Operations API. To learn more, see
-   :ref:`java-aggregation-expression-operations`.
-
-In the following example, the aggregation pipeline uses a
-``$project`` stage and various ``Projections`` to return the ``name``
-field and the calculated field ``firstCategory`` whose value is the
-first element in the ``categories`` field.
-
-.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java
-   :language: java
-   :dedent:
-   :start-after: begin aggregation expression
-   :end-before: end aggregation expression
-
-The preceding aggregation produces the following results:
-
-.. code-block:: none
-   :copyable: false
-
-   {"name": "456 Cookies Shop", "firstCategory": "Bakery"}
-   {"name": "Sun Bakery Trattoria", "firstCategory": "Pizza"}
-   {"name": "456 Steak Restaurant", "firstCategory": "Steak"}
-   {"name": "Blue Bagels Grill", "firstCategory": "Bagels"}
-   {"name": "XYZ Steak Buffet", "firstCategory": "Steak"}
-   {"name": "Hot Bakery Cafe", "firstCategory": "Bakery"}
-   {"name": "Green Feast Pizzeria", "firstCategory": "Pizza"}
-   {"name": "ZZZ Pasta Buffet", "firstCategory": "Pasta"}
-   {"name": "XYZ Coffee Bar", "firstCategory": "Coffee"}
-   {"name": "XYZ Bagels Restaurant", "firstCategory": "Bagels"}
-
-For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
-
-- `Accumulators <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Accumulators.html>`__
-- `$group <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#group(TExpression,java.util.List)>`__
-- `$project <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__
-- `Projections <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html>`__