merge upstream

mongodb · rustagir · Mar 31, 2025 · Mar 20, 2025 · Mar 20, 2025 · Mar 20, 2025
commit 50af85d5ab885795fc01e6513b6f10206ad406d7
diff --git a/config/redirects b/config/redirects
@@ -14,61 +14,61 @@ raw: ${prefix}/master -> ${base}/upcoming/
 [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/
 [*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/
 [*-v4.8]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/
-[master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/read-operations/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/read-operations/retrieve/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/read-operations/cursor/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/read-operations/sort/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/read-operations/skip/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/read-operations/limit/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/read-operations/project/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/read-operations/geo/
-[master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/read-operations/text/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/write-operations/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/write-operations/insert/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/write-operations/delete/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/write-operations/modify/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/write-operations/embedded-arrays/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/write-operations/upsert/
-[master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/write-operations/bulk/
-[master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-document/
-[master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/
-[master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/
-[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/
-[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/
-[master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/
-[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/
-[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/
-[master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/
-[master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/
-[master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/
-[master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/mongoclient
-[master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/
-[master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/
-[master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/
-[master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/
-[master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/
-[master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/
-[master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/crud/builders/
-[master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/crud/builders/aggregates/
-[master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/crud/builders/filters/
-[master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/crud/builders/indexes/
-[master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/crud/builders/projections/
-[master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/crud/builders/sort/
-[master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/crud/builders/updates/
-[master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/
-[master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/crud/aggregation/
-[master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/crud/aggregation-expression-operations/
-[master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/
-[master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/
-[master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/
-[master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/
-[master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/
-[master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/
-[master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/
-[master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/
-[master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/
-[master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/
-[master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/
-[master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/
+[*-master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/query-documents/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query-documents/find/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/query-documents/cursor/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/query-documents/sort/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/query-documents/skip/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/query-documents/limit/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query-documents/project/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query-documents/geo/
+[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/query-documents/text/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/insert/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/insert/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/update-documents/delete/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/update-documents/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/update-documents/embedded-arrays/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/update-documents/upsert/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/bulk/
+[*-master]: ${prefix}
F438
/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-documents/specify-query/
+[*-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/
+[*-master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/
+[*-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/
+[*-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/mongoclient
+[*-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/
+[*-master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/
+[*-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/
+[*-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/
+[*-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/
+[*-master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/
+[*-master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/builders/
+[*-master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/builders/aggregates/
+[*-master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/builders/filters/
+[*-master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/builders/indexes/
+[*-master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/builders/projections/
+[*-master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/builders/sort/
+[*-master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/builders/updates/
+[*-master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/
+[*-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/aggregation/
+[*-master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/aggregation/aggregation-expression-operations/
+[*-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/
+[*-master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/
+[*-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/
+[*-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/
+[*-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/
+[*-master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/
+[*-master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/
+[*-master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/
+[*-master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/
+[*-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/
+[*-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/
+[*-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/
diff --git a/snooty.toml b/snooty.toml
@@ -7,12 +7,14 @@ intersphinx = [
 ]
 
 toc_landing_pages = [
-    "/get-started",
     "/connection",
     "/connection/specify-connection-options",
-    "/crud",
-    "/crud/builders",
+    "/crud/update-documents",
+    "/aggregation",
+    "/builders",
     "/data-formats",
+    "/references",
+    "/logging-monitoring",
     "/api-documentation",
     "/security",
     "/security/auth"

diff --git a/source/aggregation.txt b/source/aggregation.txt
@@ -0,0 +1,91 @@
+.. _java-aggregation:
+
+===========
+Aggregation
+===========
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, transform, computed
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. toctree::
+   :caption: Aggregation
+
+   Aggregation Expressions </aggregation/aggregation-expression-operations>
+   Aggregation Examples </aggregation/aggregation-examples>
+
+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 comprised of 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.
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use find operations to perform the following actions:
+
+- Select *what* documents to return
+- Select *what* 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
+
+Aggregation operations have some :manual:`limitations </core/aggregation-pipeline-limits/>` you must keep in mind:
+
+- 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. If required, you can exceed this limit by using
+  the `allowDiskUse <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html#allowDiskUse(java.lang.Boolean)>`__
+  method.
+
+  .. important:: ``$graphLookup`` exception
+
+     The :manual:`$graphLookup </reference/operator/aggregation/graphLookup/>` stage has a strict memory limit of 100 megabytes
+     and will ignore ``allowDiskUse``.
+
+Useful References
+~~~~~~~~~~~~~~~~~
+
+- :manual:`Aggregation pipeline </core/aggregation-pipeline/>`
+- :manual:`Aggregation stages </meta/aggregation-quick-reference/#stages>`
+- :manual:`Operator expressions </meta/aggregation-quick-reference/#operator-expressions>`
+- :ref:`Aggregation Builders <aggregates-builders>`
diff --git a/source/crud/aggregation.txt → source/aggregation/aggregation-examples.txt b/source/crud/aggregation.txt → source/aggregation/aggregation-examples.txt
@@ -1,8 +1,8 @@
-.. _java-aggregation:
+.. _java-aggregation-examples:
 
-===========
-Aggregation
-===========
+====================
+Aggregation Examples
+====================
 
 .. facet::
    :name: genre
@@ -20,66 +20,7 @@ Aggregation
 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 comprised of 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can use find operations to perform the following actions:
-
-- Select *what* documents to return
-- Select *what* 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
-
-Aggregation operations have some :manual:`limitations </core/aggregation-pipeline-limits/>` you must keep in mind:
-
-- 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. If required, you can exceed this limit by using
-  the `allowDiskUse <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html#allowDiskUse(java.lang.Boolean)>`__
-  method.
-
-  .. important:: ``$graphLookup`` exception
-
-     The :manual:`$graphLookup </reference/operator/aggregation/graphLookup/>` stage has a strict memory limit of 100 megabytes
-     and will ignore ``allowDiskUse``.
-
-Useful References
-~~~~~~~~~~~~~~~~~
-
-- :manual:`Aggregation pipeline </core/aggregation-pipeline/>`
-- :manual:`Aggregation stages </meta/aggregation-quick-reference/#stages>`
-- :manual:`Operator expressions </meta/aggregation-quick-reference/#operator-expressions>`
-- :ref:`Aggregation Builders <aggregates-builders>`
-
-Runnable Examples
------------------
+This page demonstrates how to use aggregation pipelines.
 
 Import Classes
 ~~~~~~~~~~~~~~

diff --git a/...rud/aggregation-expression-operations.txt → ...ion/aggregation-expression-operations.txt b/...rud/aggregation-expression-operations.txt → ...ion/aggregation-expression-operations.txt