DOCSP-41145: Aggregation landing page

snooty.toml

@@ -13,7 +13,8 @@ toc_landing_pages = [
     "/connect",
     "/indexes",
     "work-with-indexes",
-    "/data-formats"
+    "/data-formats",
+    "/aggregation"
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/aggregation.txt

@@ -0,0 +1,220 @@
+.. _kotlin-sync-aggregation:
+
+====================================
+Transform Your Data with Aggregation
+====================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, transform, computed, pipeline
+   :description: Learn how to use the Kotlin Sync driver to perform aggregation operations.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. .. toctree::
+..    :titlesonly:
+..    :maxdepth: 1
+
+..    /aggregation/aggregation-tutorials
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to perform
+**aggregation operations**.
+
+You can use aggregation operations to 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 a data processing
+pipeline. Documents enter a pipeline that contains one or more stages,
+and each stage transforms the documents to output a final aggregated result.
+
+You can think of an aggregation operation as 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.
+
+Compare Aggregation and 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:
+
+- Perform find operations
+- Rename fields
+- Calculate fields
+- Summarize data
+- Group values
+
+Limitations
+~~~~~~~~~~~
+
+The following limitations apply when using aggregation operations:
+
+- Returned documents must not 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 using the ``allowDiskUse()`` method from ``AggregateIterable`` class. 
+
+.. important:: $graphLookup exception
+
+   The :manual:`$graphLookup
+   </reference/operator/aggregation/graphLookup/>` stage has a strict
+   memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
+
+Aggregation Example
+-------------------
+
+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.
+
+The following {+language+} data class models the documents in this collection:
+
+.. literalinclude:: /includes/aggregation/aggregation.kt
+   :start-after: start-data-class
+   :end-before: end-data-class
+   :language: kotlin
+   :copyable:
+
+Build and Execute an Aggregation Pipeline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To perform an aggregation on the documents in a collection, pass a list of aggregation
+stages to the ``aggregate()`` method.
+
+This example outputs a count of the number of bakeries in each borough
+of New York City. The following code creates aggregation pipeline that contains the
+following stages:
+
+- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
+  in which the value of the ``cuisine`` field is ``"Bakery"``.
+
+- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
+  documents by the ``borough`` field, producing a count of documents for each distinct
+  value of that field.
+
+.. TODO: uncomment when Aggregates Builder page is created
+
+.. .. note::
+
+..    The following example uses the builders pattern to implement the stages of an
+..    aggregation pipeline. To learn more about how to use the builders pattern, see
+..    :ref:`<aggregates-builders>`
+
+.. io-code-block::
+
+   .. input:: /includes/aggregation/aggregation.kt
+      :language: kotlin
+      :start-after: start-aggregation-pipeline
+      :end-before: end-aggregation-pipeline
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Document{{_id=Bronx, count=71}}
+      Document{{_id=Manhattan, count=221}}
+      Document{{_id=Brooklyn, count=173}}
+      Document{{_id=Queens, count=204}}
+      Document{{_id=Staten Island, count=20}}
+      Document{{_id=Missing, count=2}}
+
+.. tip::
+
+   When specifying a group key for the ``$group`` aggregation stage, ensure that you
+   escape any ``$`` characters by using the ``\`` character. 
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, you can
+include the ``$explain`` aggregation stage in your pipeline. 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 selected for the operation and any rejected execution plans.
+
+The following code example runs the same aggregation shown in the preceding section
+and adds the ``$explain`` stage to output the operation details:
+
+.. io-code-block::
+
+   .. input:: /includes/aggregation/aggregation.kt
+      :language: kotlin
+      :start-after: start-aggregation-explain
+      :end-before: end-aggregation-explain
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {
+        "explainVersion": "2", 
+        "queryPlanner": {
+            "namespace": "sample_restaurants.restaurants"
+            "indexFilterSet": false,
+            "parsedQuery": {
+              "cuisine": {"$eq": "Bakery"}
+            }, 
+            "queryHash": "865F14C3", 
+            "planCacheKey": "0697561B", 
+            "optimizedPipeline": true,
+            "maxIndexedOrSolutionsReached": false,
+            "maxIndexedAndSolutionsReached": false,
+            "maxScansToExplodeReached": false,
+            "winningPlan": { ... }
+            ...
+        }
+        ...
+      }
+
+Additional Information
+----------------------
+
+To view a full list of expression operators, see :manual:`Aggregation
+Operators </reference/operator/aggregation/>` in the {+mdb-server+} manual.
+
+To learn about assembling an aggregation pipeline and view examples, see
+:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the {+mdb-server+} manual.
+
+To learn more about creating pipeline stages, see :manual:`Aggregation
+Stages </reference/operator/aggregation-pipeline/>` in the {+mdb-server+} manual.
+
+To learn more about explaining MongoDB operations, see
+:manual:`Explain Output </reference/explain-results/>` and
+:manual:`Query Plans </core/query-plans/>` in the {+mdb-server+} manual.
+
+.. Aggregation Tutorials
+.. ~~~~~~~~~~~~~~~~~~~~~
+
+.. To view step-by-step explanations of common aggregation tasks, see
+.. :ref:`kotlin-sync-aggregation-tutorials`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information about executing aggregation operations with the {+driver-short+},
+see the following API documentation:
+
+- `aggregate() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/aggregate.html>`__
+- `AggregateIterable <{+api+}/com.mongodb.kotlin.client/-aggregate-iterable/index.html>`__

source/includes/aggregation/aggregation.kt

@@ -0,0 +1,46 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.Accumulators
+import com.mongodb.client.model.Aggregates
+import com.mongodb.client.model.Filters
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.Document
+
+// start-data-class
+data class Restaurant(
+    val name: String,
+    val cuisine: String,
+    val borough: String
+)
+// end-data-class
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("sample_restaurants")
+    val collection = database.getCollection<Restaurant>("restaurants")
+
+    // start-aggregation-pipeline
+    val pipeline = listOf(
+        Aggregates.match(Filters.eq(Restaurant::cuisine.name, "Bakery")),
+        Aggregates.group("\$borough", Accumulators.sum("count", 1))
+    )
+
+    val results = collection.aggregate<Document>(pipeline)
+
+    results.forEach { result ->
+        println(result)
+    }
+    // end-aggregation-pipeline
+
+    // start-aggregation-explain
+    print(collection.aggregate(pipeline).explain())
+    // end-aggregation-explain
+}
+

source/index.txt

@@ -18,6 +18,7 @@
    /write-operations
    /read
    /indexes
+   /aggregation
    /data-formats
    /faq
    /connection-troubleshooting
@@ -78,6 +79,12 @@ Optimize Queries with Indexes
 Learn how to work with common types of indexes in the :ref:`kotlin-sync-indexes`
 section.
 
+Transform Your Data with Aggregation
+------------------------------------
+
+Learn how to use the {+driver-short+} to perform aggregation operations in the
+:ref:`kotlin-sync-aggregation` section.
+
 Specialized Data Formats
 ------------------------