DOCS-16164 AutoMerger concept (#3304)

* DOCS-16164 AutoMerger concept

* internal review

* external review

* external review

* link to configureCollectionBalancing command

* addresses feedback

* feedback

Author: jmd-mongo

snooty.toml

@@ -256,7 +256,9 @@ fts = "Atlas Search"
 # Automerger Constants
 auto-merge-upper = "AutoMerger"
 auto-merge-lower = "automerger"
+auto-merge-lower-plural = "automerger"
 auto-merge-action = "automerging"
+auto-merge-action-upper = "Automerging"
 # In Use Encryption Constants
 csfle = "Client-Side Field Level Encryption"
 csfle-abbrev = "CSFLE"

source/core/automerger-concept.txt

@@ -0,0 +1,69 @@
+.. _automerger-concept:
+
+========================
+The {+auto-merge-upper+}
+========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Starting in MongoDB 7.0, the balancer can automatically merge chunks
+that meet the :ref:`mergeability requirements <mergeability-concept>`.
+
+Behavior
+--------
+
+The {+auto-merge-upper+} runs in the background as part of balancing
+operations. For most use cases, the default settings perform well. For 
+details on which settings to customize for your deployment, see 
+:ref:`{+auto-merge-upper+} Policy <automerge-policy-settings>`.
+
+When the {+auto-merge-upper+} runs, it squashes together all sequences
+of mergeable chunks for each shard of each collection.
+
+{+auto-merge-upper+} Policy
+```````````````````````````
+
+.. _automerge-policy-settings:
+
+Unless explicitly disabled, the {+auto-merge-upper+} starts the first 
+time the balancer is enabled and pauses for the next 
+:parameter:`autoMergerIntervalSecs` after the routine drains.
+
+When {+auto-merge-upper+} is enabled, {+auto-merge-action+} happens 
+every :parameter:`autoMergerIntervalSecs` seconds.
+
+For a given collection, {+auto-merge-upper+} guarantees that subsequent 
+merges are delayed at least the amount specified by 
+:parameter:`autoMergerThrottlingMS`.
+
+If a :ref:`balancing window <sharding-schedule-balancing-window>` is 
+set, {+auto-merge-upper+} only runs during the window.
+
+Balancing Settings Precedence
+`````````````````````````````
+{+auto-merge-action-upper+} happens as part of balancing operations. 
+In order to decide if and when to execute {+auto-merge-lower-plural+}, 
+the settings are taken into account in this order:
+
+#. Global :ref:`balancing settings <balancer-sharding-params>`
+#. Per-collection balancing settings (configured by :dbcommand:`configureCollectionBalancing`)
+#. Global :ref:`{+auto-merge-upper+} settings <automerger-params>`
+#. Per-collection {+auto-merge-upper+} settings (configured by :dbcommand:`configureCollectionBalancing`)
+
+Details
+-------
+
+.. _mergeability-concept:
+
+.. include:: /includes/mergeability.rst
+
+Example
+-------
+
+.. include:: /includes/mergeAllChunksOnShard-example.rst

source/core/sharding-balancer-administration.txt

@@ -42,6 +42,7 @@ To manage the sharded cluster balancer, see
 
    /tutorial/manage-sharded-cluster-balancer
    /tutorial/migrate-chunks-in-sharded-cluster
+   /core/automerger-concept
 
 
 .. _sharding-balancing-internals:

source/includes/mergeability.rst

@@ -9,7 +9,9 @@ collection are **mergeable** when they meet all of these conditions:
   snapshot reads:
 
   - The last migration involving the chunk happened at least as many
-    seconds ago as the value of ``minSnapshotHistoryWindowInSeconds``.
+    seconds ago as the value of 
+    :parameter:`minSnapshotHistoryWindowInSeconds`.
   - The last migration involving the chunk happened at least as many 
-    seconds ago as the value of ``transactionLifetimeLimitSeconds``.
+    seconds ago as the value of 
+    :parameter:`transactionLifetimeLimitSeconds`.
 

source/reference/parameters.txt

@@ -3090,6 +3090,10 @@ Sharding Parameters
    ``AsyncRequestsSenderUseBaton`` and always enables the performance
    enhancement controlled by the parameter.
 
+
+.. _automerger-params:
+
+
 .. parameter:: autoMergerIntervalSecs
 
    .. versionadded:: 7.0
@@ -3150,6 +3154,10 @@ Sharding Parameters
 
       db.adminCommand( { setParameter: 1, autoMergerThrottlingMS: 60000 } )
 
+
+.. _balancer-sharding-params:
+
+
 .. parameter:: balancerMigrationsThrottlingMs
 
    .. versionadded:: 7.0 (*Also available starting in 6.3.1, 6.0.6, 5.0.18*)