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,210 @@
+.. _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**.
+
+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:
+
+- Perform find operations
+- Rename fields
+- Calculate fields
+- Summarize data
+- Group values
+
+Limitations
+~~~~~~~~~~~
+
+Keep the following limitations in mind 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 of the
+  ``AggregateIterable`` type. 
+
+.. important:: $graphLookup exception
+
+   The :manual:`$graphLookup
+   </reference/operator/aggregation/graphLookup/>` stage has a strict
+   memory limit of 100 megabytes and ignores the ``allowDiskUse`` parameter.
+
+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, pass a list of aggregation stages to the
+``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 with the following stages:
+
+- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
+  whose ``cuisine`` field contains the value ``"Bakery"``.
+
+- A :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::
+
+   .. 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}}
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, you can
+instruct MongoDB 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.
+
+The following code example runs the preceding aggregation example and prints the returned
+explanation:
+
+.. io-code-block::
+
+   .. input:: /includes/aggregation/aggregation.kt
+      :language: kotlin
+      :start-after: start-aggregation-explain
+      :end-before: end-aggregation-explain
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {
+        "explain": {
+          "aggregate": "restaurants",
+          "pipeline": [
+            {
+              "$match": {
+                "cuisine": "Bakery"
+              }
+            },
+            {
+              "$group": {
+                "_id": "$borough",
+                "count": {
+                  "$sum": 1
+                }
+              }
+            }
+          ],
+          "cursor": {}
+        },
+        ...
+      }
+
+Additional Information
+----------------------
+
+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/>`
+
+.. 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 operatoins in the
+:ref:`kotlin-sync-aggregation` section.
+
 Specialized Data Formats
 ------------------------