mongodb
diff --git a/‎snooty.toml
Lines changed: 1 addition & 0 deletions b/‎snooty.toml
Lines changed: 1 addition & 0 deletions
diff --git a/‎source/core/defragment-sharded-collections.txt
Lines changed: 117 additions & 0 deletions b/‎source/core/defragment-sharded-collections.txt
Lines changed: 117 additions & 0 deletions
diff --git a/‎source/core/defragment-sharded-collections/monitor-defragmentation-sharded-collection.txt
Lines changed: 174 additions & 0 deletions b/‎source/core/defragment-sharded-collections/monitor-defragmentation-sharded-collection.txt
Lines changed: 174 additions & 0 deletions
diff --git a/‎source/core/defragment-sharded-collections/start-defragmenting-sharded-collection.txt
Lines changed: 80 additions & 0 deletions b/‎source/core/defragment-sharded-collections/start-defragmenting-sharded-collection.txt
Lines changed: 80 additions & 0 deletions
@@ -87,6 +87,7 @@ toc_landing_pages = [
    "/core/sharded-cluster-components",
    "/core/sharding-change-a-shard-key",
    "/core/sharding-balancer-administration",
+   "/core/defragment-sharded-collections",
    "/core/sharding-data-partitioning",
    "/core/sharding-shard-key",
    "/core/storage-engines",
 
@@ -0,0 +1,117 @@
+.. _defragment-sharded-collections:
+
+==============================
+Defragment Sharded Collections
+==============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. include:: /includes/defragment-sharded-collections-conditions.rst
+
+To defragment a sharded collection, use the
+:dbcommand:`configureCollectionBalancing` command's
+``defragmentCollection`` option. The option is available starting in
+MongoDB 6.0.
+
+Before you Begin
+----------------
+
+Consider these issues before you defragment collections:
+
+- Defragmentation might cause many metadata updates on the shards. If
+  your CRUD operations are already taking longer than usual during
+  migrations, you should only run defragmentation during a :ref:`shard
+  balancing window <sharding-schedule-balancing-window>` to reduce the
+  system workload.
+- If defragmentation is impacting workload and CRUD latency on the
+  cluster, you can reduce the impact using the
+  :parameter:`chunkDefragmentationThrottlingMS` parameter.
+- Merged chunks lose their placement history.
+
+  - This means that while defragmentation is running, snapshot reads and
+    indirectly, transactions, could fail with stale chunk history
+    errors.
+  - Placement history records the shards that a chunk was stored on.
+    Defragmentation erases the placement history and some operations
+    could fail, but will typically resolve after around five minutes.
+
+- Defragmentation affects the locality of the documents in a collection
+  by moving data between shards. If a collection has ranges of data that
+  are frequently accessed, after defragmenting the collection it is
+  possible that the frequently accessed data will be on one shard. This
+  might decrease the performance of CRUD operations by placing the
+  workload on one shard instead of multiple shards.
+
+Tasks
+-----
+
+- :ref:`Manually start defragmenting a sharded collection
+  <start-defragmenting-sharded-collection>`
+- :ref:`Monitor defragmentation of a sharded collection
+  <monitor-defragmentation-sharded-collection>`
+- :ref:`Manually stop defragmenting a sharded collection
+  <stop-defragmenting-sharded-collection>`
+
+.. note::
+
+   Typically, you should use a :ref:`shard balancing window
+   <sharding-schedule-balancing-window>` to specify when the balancer
+   runs instead of manually starting and stopping defragmentation.
+
+Details
+-------
+
+This section describes additional details related to defragmenting
+sharded collections.
+
+Configure Collection Balancing Status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``defragmentCollection`` field returned by the
+:dbcommand:`configureCollectionBalancing` command is only ``true`` when
+defragmentation is running.
+
+After defragmentation automatically ends or you manually stop
+defragmentation, the ``defragmentCollection`` field is removed from the
+returned document.
+
+Operations
+~~~~~~~~~~
+
+Secondary node reads are permitted during defragmentation, but might
+take longer to complete until metadata updates on the primary node are
+replicated to the secondary nodes.
+
+Chunk Size, Balancing, and Defragmentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For details about the MongoDB balancer, see :ref:`sharding-balancing`.
+
+.. include:: /includes/chunk-size-and-balancing.rst
+
+Learn More
+----------
+
+- Introduction to sharding, see :ref:`sharding-introduction`
+- Partition data with chunks, see :ref:`sharding-data-partitioning`
+- Configure collection balancing, see
+  :dbcommand:`configureCollectionBalancing`
+- Examine balancer collection status, see
+  :dbcommand:`balancerCollectionStatus`
+- Configure shard balancing windows, see
+  :ref:`sharding-schedule-balancing-window`
+- Monitor shards using MongoDB Atlas, see `Review Sharded Clusters
+  <https://www.mongodb.com/docs/atlas/review-sharded-cluster-metrics/#review-sharded-clusters/>`__
+
+.. toctree::
+   :titlesonly:
+
+   /core/defragment-sharded-collections/start-defragmenting-sharded-collection
+   /core/defragment-sharded-collections/monitor-defragmentation-sharded-collection
+   /core/defragment-sharded-collections/stop-defragmenting-sharded-collection
@@ -0,0 +1,174 @@
+.. _monitor-defragmentation-sharded-collection:
+
+===============================================
+Monitor Defragmentation of a Sharded Collection
+===============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+To monitor defragmentation of a sharded collection, use the
+:dbcommand:`balancerCollectionStatus` command.
+
+You can see the current defragmentation state and the number of
+remaining chunks to process. This shows you the defragmentation
+progress.
+
+About this Task
+---------------
+
+.. include:: /includes/defragment-sharded-collections-status.rst
+
+.. include:: /includes/defragment-sharded-collections-example.rst
+
+In the procedure for this task, you monitor the phases and see the
+defragmentation progress.
+
+Before you Begin
+----------------
+
+- Start defragmenting a sharded collection. For details, see
+  :ref:`start-defragmenting-sharded-collection`.
+- Connect to :binary:`~bin.mongos`.
+
+Procedure
+---------
+
+.. procedure::
+   :style: normal
+
+   .. step:: Monitor defragmentation
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.adminCommand(
+            {
+               balancerCollectionStatus: "test.ordersShardedCollection"
+            }
+         )
+
+   .. step:: Examine output document
+
+      The previous command returns a document with information about
+      defragmentation status, current phase, and the defragmentation
+      work remaining. For example:
+
+      .. code-block:: javascript
+         :copyable: false
+
+         {
+            "balancerCompliant": false,
+            "firstComplianceViolation": "defragmentingChunks",
+            "details": {
+               "currentPhase": "moveAndMergeChunks",
+               "progress": { "remainingChunksToProcess": 1 }
+            }
+         }
+
+      The following table describes the document fields.
+
+      .. list-table::
+         :header-rows: 1
+         :widths: 20 20 60
+
+         * - Field
+           - Type
+           - Description
+
+         * - ``balancerCompliant``
+           - Boolean
+           - ``false`` if collection chunks must be moved. Otherwise,
+             ``true``.
+
+         * - ``firstComplianceViolation``
+           - String
+           - Indicates the reason that chunks for the namespace must be
+             moved or merged. Only returned if ``balancerCompliant`` is
+             ``false``.
+
+         * - ``details``
+           - Object
+           - Addtional information about the current defragmentation
+             state. Only returned if ``firstComplianceViolation`` is
+             ``defragmentingChunks``.
+
+         * - ``currentPhase``
+           - String
+           - Current defragmentation phase:
+
+             - For phase one, ``currentPhase`` is
+               ``mergeAndMeasureChunks``.
+
+               Phase one merges contiguous chunks located on the same
+               shard and calculates the data size for those chunks.
+
+             - For phase two, ``currentPhase`` is
+               ``moveAndMergeChunks``.
+
+               After phase one is complete, there might be some small
+               chunks remaining. Phase two migrates those small chunks
+               to other shards and merges the chunks on those shards.
+
+         * - ``remainingChunksToProcess``
+           - Integer
+           - Number of remaining chunks to process in the current phase.
+                  
+      For additional information about the returned document fields, see
+      the :ref:`balancer collection status output document
+      <cmd-balancer-CollectionStatus-output>`.
+
+   .. step:: Confirm that defragmentation is complete
+
+      After defragmentation completes, the command returns either:
+
+      - ``balancerCompliant: true`` if your collection is balanced.
+      - ``balancerCompliant: false`` with ``firstComplianceViolation``
+        set to a string other than ``defragmentingChunks`` if
+        your collection is not balanced.
+      
+      Example output for a balanced collection after defragmentation
+      completes:
+
+      .. code-block:: javascript
+         :copyable: false
+         :emphasize-lines: 3
+
+         {
+            chunkSize: 0.2,
+            balancerCompliant: true,
+            ok: 1,
+            '$clusterTime': {
+               clusterTime: Timestamp({ t: 1677543079, i: 1 }),
+               signature: {
+                  hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
+                  keyId: Long("0")
+               }
+            },
+            operationTime: Timestamp({ t: 1677543079, i: 1 })
+         }
+
+Next Steps
+----------
+
+If defragmentation has not yet completed, you can stop it. For details,
+see :ref:`stop-defragmenting-sharded-collection`.
+
+Learn More
+----------
+
+- :ref:`Start defragmenting a sharded collection
+  <start-defragmenting-sharded-collection>`
+- :ref:`Stop defragmenting a sharded collection
+  <stop-defragmenting-sharded-collection>`
+- To view the balancer collection status output document, see
+  :ref:`Balancer collection status output document
+  <cmd-balancer-CollectionStatus-output>`
+
+.. include:: /includes/defragment-sharded-collections-learn-more.rst
@@ -0,0 +1,80 @@
+.. _start-defragmenting-sharded-collection:
+
+========================================
+Start Defragmenting a Sharded Collection
+========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+To start defragmenting a sharded collection, use the
+:dbcommand:`configureCollectionBalancing` command with the
+``defragmentCollection`` option set to ``true``.
+
+About this Task
+---------------
+
+.. include:: /includes/defragment-sharded-collections-conditions.rst
+
+.. include:: /includes/defragment-sharded-collections-example.rst
+
+Before you Begin
+----------------
+
+Connect to :binary:`~bin.mongos`.
+
+Procedure
+---------
+
+.. procedure::
+   :style: normal
+
+   .. step:: Start defragmenting the collection
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.adminCommand(
+            {
+               configureCollectionBalancing: "test.ordersShardedCollection",
+               defragmentCollection: true
+            }
+         )
+
+   .. step:: Ensure defragmentation started
+
+      Ensure ``ok`` is ``1`` in the command output, which indicates the
+      command execution was successful:
+
+      .. code-block:: javascript
+         :copyable: false
+         :emphasize-lines: 2
+
+         {
+            ok: 1,
+            '$clusterTime': {
+               clusterTime: Timestamp({ t: 1677616966, i: 8 }),
+               signature: {
+                  hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
+                  keyId: Long("0")
+               }
+            },
+            operationTime: Timestamp({ t: 1677616966, i: 8 })
+         }
+
+Next Steps
+----------
+
+You can monitor the collection's defragmentation progress. For details,
+see :ref:`monitor-defragmentation-sharded-collection`.
+
+Learn More
+----------
+
+.. include:: /includes/defragment-sharded-collections-learn-more.rst