Merge branch 'master' into DOCSP-41139-cursor

snooty.toml

@@ -13,7 +13,9 @@ toc_landing_pages = [
     "/connect",
     "/indexes",
     "work-with-indexes",
-    "/data-formats"
+    "/data-formats",
+    "/builders",
+    "/aggregation"
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -27,7 +29,7 @@ full-version = "{+version-number+}.2"
 version = "v{+version-number+}"
 mdb-server = "MongoDB Server"
 stable-api = "Stable API"
-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
+api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync"
 java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
-core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
+core-api = "{+java-api+}/apidocs/mongodb-driver-core"
 kotlin-docs = "https://kotlinlang.org"

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/builders.txt

@@ -0,0 +1,115 @@
+.. _kotlin-sync-builders:
+
+=========================
+Use Builders Code Pattern
+=========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. .. toctree::
+
+..    /fundamentals/builders/aggregates
+..    /fundamentals/builders/filters
+..    /fundamentals/builders/indexes
+..    /fundamentals/builders/projections
+..    /fundamentals/builders/sort
+..    /fundamentals/builders/updates
+
+Overview
+--------
+
+This page describes how to use the various available builders in your code and describes
+benefits of using the provided builders.
+
+The {+driver-short+} provides type-safe builder classes and methods that enable developers to
+efficiently build queries and aggregations.
+
+Why Use Builders?
+-----------------
+
+If you use only plain {+language+} to construct BSON query documents, you are not
+able to identify syntax errors until runtime. The builders help ensure the corretness of
+syntax and can be less verbose than constructing BSON documents.
+
+Example
+-------
+
+This section provides three equivalent ways to fetch the ``email`` field values of documents
+in the ``users`` collection that meet the following criteria:
+
+- ``gender`` value is ``"female"``
+- ``age`` value is greater than ``29``
+
+The following data class models the documents in the ``users`` collection:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-user-class
+   :end-before: end-user-class
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+The following data class models the results returned by our query:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-result-class
+   :end-before: end-result-class
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+MongoDB Query API
+~~~~~~~~~~~~~~~~~
+
+The following sample performs the query by using the MongoDB Query API:
+
+.. code-block:: js
+
+   collection.find(
+       { "gender": "female", "age" : { "$gt": 29 }},
+       { "_id": 0, "email": 1 }
+   )
+
+Document Class Filter
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example performs the query by using the ``Document`` class to construct the
+query filter:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-find
+   :end-before: end-find
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Builders
+~~~~~~~~
+
+The following example performs the query by using the builder helpers:
+
+.. literalinclude:: /includes/builders/builders.kt
+   :start-after: start-find-builders
+   :end-before: end-find-builders
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: Uncomment as pages get built
+
+.. Available Builders
+.. ------------------
+
+.. The following pages describe how to implement the different classes of builders
+.. available in the {+driver-short+}.
+
+.. - :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
+.. - :ref:`Filters <filters-builders>` for building query filters.
+.. - :ref:`Indexes <indexes-builders>` for creating index keys.
+.. - :ref:`Projections <projections-builders>` for building projections. 
+.. - :ref:`Sorts <sorts-builders>` for building sort criteria.
+.. - :ref:`Updates <updates-builders>` for building updates.