Scala standardization

snooty.toml

@@ -10,19 +10,32 @@ intersphinx = [
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
 toc_landing_pages = [
+    "/get-started",
     "/bson",
     "/tutorials/connect",
     "/tutorials/write-ops",
     "/builders",
-    ]
+    "/get-started",
+    "/databases-collections",
+    "/read",
+    "/write",
+    "/indexes",
+    "/security"
+]
 
 [constants]
 driver-short = "Scala driver"
 driver-long = "MongoDB Scala Driver"
 version = "5.2"
 full-version = "{+version+}.1"
+language = "Scala"
+language-version = "2.13.15"
+mdb-server = "MongoDB Server"
 api = "https://mongodb.github.io/mongo-java-driver/{+version+}/apidocs/mongo-scala-driver"
 driver-source-gh = "https://github.com/mongodb/mongo-java-driver"
 rs-docs = "https://www.reactive-streams.org/reactive-streams-1.0.4-javadoc/org/reactivestreams"
 core-api = "https://mongodb.github.io/mongo-java-driver/{+version+}/apidocs/mongodb-driver-core"
 mongocrypt-version = "{+full-version+}"
+java-version = "23"
+mongodb-server = "MongoDB Server"
+stable-api = "Stable API"

source/aggregation.txt

@@ -0,0 +1,285 @@
+.. _scala-aggregation:
+
+====================================
+Transform Your Data with Aggregation
+====================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, transform, computed, pipeline
+   :description: Learn how to use the Scala driver to perform aggregation operations.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. TODO:
+ .. 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.
+
+Compare Aggregation and Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following table lists the different tasks that find
+operations can perform and compares them to what aggregation
+operations can perform. The aggregation framework provides
+expanded functionality that allows you to transform and manipulate
+your data.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Find Operations
+     - Aggregation Operations
+
+   * - | Select *certain* documents to return
+       | Select *which* fields to return
+       | Sort the results
+       | Limit the results
+       | Count the results
+     - | Select *certain* documents to return
+       | Select *which* fields to return
+       | Sort the results
+       | Limit the results
+       | Count the results
+       | Rename fields
+       | Compute new fields
+       | Summarize data
+       | Connect and merge data sets
+
+Limitations
+~~~~~~~~~~~
+
+Consider the following limitations when performing aggregation operations:
+
+- Returned documents cannot 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 passing a value of ``true`` to the ``allowDiskUse()`` method and chaining the
+  method to ``aggregate()``.
+- The :manual:`$graphLookup </reference/operator/aggregation/graphLookup/>`
+  operator has a strict memory limit of 100 megabytes and ignores the
+  value passed to the ``allowDiskUse()`` method.
+
+.. _scala-run-aggregation:
+
+Run Aggregation Operations
+--------------------------
+
+.. note:: Sample Data
+
+   The examples in this guide 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.
+
+To perform an aggregation, pass a list containing the pipeline stages to
+the ``aggregate()`` method. The {+driver-short+} provides the ``Aggregates`` class,
+which includes helper methods for building pipeline stages. 
+
+To learn more about pipeline stages and their corresponding ``Aggregates`` helper
+methods, see the following resources:
+
+- :manual:`Aggregation Stages </reference/operator/aggregation-pipeline/>` in the
+  {+mdb-server+} manual
+- `Aggregates <{+api+}/org/mongodb/scala/model/Aggregates$.html>`__ in the API documentation
+
+.. _scala-aggregation-example:
+
+Filter, Group, and Count Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This code example produces a count of the number of bakeries in each borough
+of New York. To do so, it calls the ``aggregate()`` method and passes an aggregation
+pipeline as a list of stages. The code builds these stages by using the following
+``Aggregates`` helper methods:
+
+- ``filter()``: Builds the :manual:`$match </reference/operator/aggregation/match/>` stage
+  to filter for documents that have a ``cuisine`` value of ``"Bakery"``
+
+- ``group()``: Builds the :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::
+   :copyable:
+
+   .. input:: /includes/aggregation.scala
+      :start-after: start-match-group
+      :end-before: end-match-group
+      :language: scala
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_id": "Brooklyn", "count": 173}
+      {"_id": "Queens", "count": 204}
+      {"_id": "Bronx", "count": 71}
+      {"_id": "Staten Island", "count": 20}
+      {"_id": "Missing", "count": 2}
+      {"_id": "Manhattan", "count": 221}
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, you can
+instruct the MongoDB query planner to **explain** it. When MongoDB explains
+an operation, it returns **execution plans** and performance statistics.
+An execution plan is a potential way in which 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 by default.
+
+To explain an aggregation operation, chain the ``explain()`` method to the
+``aggregate()`` method. You can pass a verbosity level to ``explain()``,
+which modifies the type and amount of information that the method returns. For more
+information about verbosity, see :manual:`Verbosity Modes </reference/command/explain/#verbosity-modes>`
+in the {+mdb-server+} manual.
+
+The following example instructs MongoDB to explain the aggregation operation
+from the preceding :ref:`scala-aggregation-example` example. The code passes a verbosity
+value of ``ExplainVerbosity.EXECUTION_STATS`` to the ``explain()`` method, which
+configures the method to return statistics describing the execution of the winning
+plan:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.scala
+      :start-after: start-explain
+      :end-before: end-explain
+      :language: scala
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"explainVersion": "2", "queryPlanner": {"namespace": "sample_restaurants.restaurants",
+      "indexFilterSet": false, "parsedQuery": {"cuisine": {"$eq": "Bakery"}}, "queryHash": "865F14C3",
+      "planCacheKey": "0FC225DA", "optimizedPipeline": true, "maxIndexedOrSolutionsReached": false, 
+      "maxIndexedAndSolutionsReached": false, "maxScansToExplodeReached": false, "winningPlan":
+      {"queryPlan": {"stage": "GROUP", "planNodeId": 3, "inputStage": {"stage": "COLLSCAN",
+      "planNodeId": 1, "filter": {"cuisine": {"$eq": "Bakery"}}, "direction": "forward"}},
+      ...}
+
+Run an Atlas Full-Text Search
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tip:: Only Available on Atlas for MongoDB v4.2 and later
+
+   This aggregation pipeline operator is only available for collections hosted
+   on :atlas:`MongoDB Atlas </>` clusters running v4.2 or later that are
+   covered by an :atlas:`Atlas Search index </reference/atlas-search/index-definitions/>`.
+
+To specify a full-text search of one or more fields, you can create
+a ``$search`` pipeline stage. The {+driver-short+} provides the
+``Aggregates.search()`` helper method to create this stage. The ``search()``
+method requires the following arguments:
+
+- ``SearchOperator`` instance: Specifies the field and text to search for.
+- ``SearchOptions`` instance: Specifies options to customize the full-text
+  search. You must set the ``index`` option to the name of the Atlas Search
+  index to use.
+
+This example creates pipeline stages to perform the following actions:
+
+- Search the ``name`` field for text that contains the word ``"Salt"``
+- Project only the ``_id`` and ``name`` values of matching documents
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.scala
+      :start-after: start-atlas-search
+      :end-before: end-atlas-search
+      :language: scala
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_id": {"$oid": "..."}, "name": "Fresh Salt"}
+      {"_id": {"$oid": "..."}, "name": "Salt & Pepper"}
+      {"_id": {"$oid": "..."}, "name": "Salt + Charcoal"}
+      {"_id": {"$oid": "..."}, "name": "A Salt & Battery"}
+      {"_id": {"$oid": "..."}, "name": "Salt And Fat"}
+      {"_id": {"$oid": "..."}, "name": "Salt And Pepper Diner"}
+
+.. important::
+
+    To run the preceding example, you must create an Atlas Search index on the ``restaurants``
+    collection that covers the ``name`` field. Then, replace the ``"<search index name>"``
+    placeholder with the name of the index. To learn more about Atlas Search indexes, see
+    the :ref:`scala-atlas-search-index` guide.
+
+Additional Information
+----------------------
+
+MongoDB Server Manual
+~~~~~~~~~~~~~~~~~~~~~
+
+To learn more about the topics discussed in this guide, see the following
+pages in the {+mdb-server+} manual:
+
+- To view a full list of expression operators, see :manual:`Aggregation
+  Operators </reference/operator/aggregation/>`.
+
+- To learn about assembling an aggregation pipeline and to 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/>`.
+
+.. TODO:
+ Aggregation Tutorials
+ ~~~~~~~~~~~~~~~~~~~~~
+
+.. To view step-by-step explanations of common aggregation tasks, see
+.. :ref:`scala-aggregation-tutorials-landing`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods and types discussed in this guide, see the
+following API documentation:
+
+- `aggregate() <{+api+}/org/mongodb/scala/MongoCollection.html#aggregate[C](pipeline:Seq[org.mongodb.scala.bson.conversions.Bson])(implicite:org.mongodb.scala.bson.DefaultHelper.DefaultsTo[C,TResult],implicitct:scala.reflect.ClassTag[C]):org.mongodb.scala.AggregateObservable[C]>`__
+- `Aggregates <{+api+}/org/mongodb/scala/model/Aggregates$.html>`__
+- `explain() <{+api+}/org/mongodb/scala/AggregateObservable.html#explain[ExplainResult](verbosity:com.mongodb.ExplainVerbosity)(implicite:org.mongodb.scala.bson.DefaultHelper.DefaultsTo[ExplainResult,org.mongodb.scala.Document],implicitct:scala.reflect.ClassTag[ExplainResult]):org.mongodb.scala.SingleObservable[ExplainResult]>`__
+