DOCSP-47276-reshard-to-same-shard-key (#11328)

jmd-mongo · web-flow · commit cb5ec8157dc2 · 2025-04-23T17:09:59.000-04:00
* DOCSP-47276-reshard-to-same-shard-key * adds page * adds tutorial * adds monitor resharding operation step * external review * external review; * external review * ex rev * internal review
diff --git a/source/administration/sharded-cluster-administration.txt b/source/administration/sharded-cluster-administration.txt
@@ -29,6 +29,9 @@ Sharded Cluster Administration
    Drop Hashed Shard Key Index </tutorial/drop-a-hashed-shard-key-index>
    Config Shard </core/config-shard>
    Start with a Config Shard </tutorial/start-a-sharded-cluster-with-config-shard>
+   Reshard to the Same Shard Key </core/reshard-to-same-key>
+   Reshard a Collection back to the Same Shard Key </tutorial/resharding-back-to-same-key>
+   Resharding for Adding and Removing Shards </tutorial/resharding-for-adding-and-removing-shards>
 
 :doc:`/tutorial/view-sharded-cluster-configuration`
    View status information about the cluster's databases, shards, and
@@ -57,4 +60,13 @@ Sharded Cluster Administration
    *and* the usual sharded cluster metadata.
 
 :doc:`/tutorial/start-a-sharded-cluster-with-config-shard`
-   Start a Sharded Cluster with a Config Shard.
+   Start a Sharded Cluster with a Config Shard.
+
+:doc:`/core/reshard-to-same-key`
+   Reshard to the Same Shard Key.
+
+:doc:`/tutorial/resharding-back-to-same-key`
+   Reshard a Collection back to the Same Shard Key.
+
+:doc:`/tutorial/resharding-for-adding-and-removing-shards`
+   Resharding for Adding and Removing Shards.
diff --git a/source/core/reshard-to-same-key.txt b/source/core/reshard-to-same-key.txt
@@ -0,0 +1,94 @@
+.. _reshard-to-same-key:
+
+=============================
+Reshard to the Same Shard Key
+=============================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta:: 
+   :description: Reshard to the Same Shard Key to Shard a Collection, Add or Remove Shards Concept 
+
+Starting in MongoDB 8.0, you can reshard to the same shard key to move 
+data with no downtime or impact on workload. This enables you to: 
+
+.. include:: /includes/resharding-about.rst
+
+Starting in MongoDB 8.0, resharding reads data using natural order scan. 
+Resharding first clones all the data and then builds relevant indexes,
+resulting in orders of magnitude speed improvement of the resharding 
+process.
+
+Command Syntax
+--------------
+
+You can reshard to the same key using the ``reshardCollection`` command
+with ``forceRedistribution`` set to ``true``. 
+
+The ``reshardCollection`` command has the following syntax:
+
+.. include:: /includes/reshardCollection-syntax.rst
+
+For details, see :dbcommand:`reshardCollection`.
+
+Use Cases
+---------
+
+Resharding is a strategy to move data with no downtime or impact on 
+workload. Use the :ref:`<reshard-to-shard-def>` technique to shard a 
+collection and distribute data across all shards.
+
+Use resharding to distribute your collections across all relevant shards 
+faster than :ref:`chunk migrations <migrate-chunks-sharded-cluster>`. 
+Resharding writes to all shards in parallel while each shard can only 
+participate in one chunk migration at a time. Resharding drops the old 
+collection at the end of the process. There are no orphan documents at 
+the end of resharding.
+
+.. _reshard-to-shard-def:
+
+Reshard to Shard
+~~~~~~~~~~~~~~~~
+
+The **Reshard to Shard** technique lets you use resharding to shard a
+collection and distribute the data to all of the shards in a cluster.
+
+Consider using **Reshard to Shard** when you are initially sharding a 
+collection of any size across any number of shards. If your deployment
+meets the :ref:`resource requirements <reshard-to-same-key-behavior>`, 
+use **Reshard to Shard** no matter how large the collection you want to
+shard.
+
+.. _reshard-to-same-key-behavior:
+
+Behavior
+--------
+
+Storage
+~~~~~~~
+
+.. include:: /includes/reshard-to-same-key/storage.rst
+
+Latency
+~~~~~~~
+
+.. include:: /includes/reshard-to-same-key/latency.rst
+
+Additional Resource Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/reshard-to-same-key/addl-resource-reqs.rst
+
+Get Started
+-----------
+
+- :ref:`<resharding-a-collection-back-to-same-key>`
+- :ref:`<resharding-for-adding-and-removing-shards-tutorial>`
+
+Learn More
+----------
+
+- :method:`sh.reshardCollection()`
+- :ref:`<sharding-resharding>`
diff --git a/source/includes/remainingOperationTimeEstimatedSecs-details.rst b/source/includes/remainingOperationTimeEstimatedSecs-details.rst
@@ -3,26 +3,14 @@ seconds for the current :ref:`resharding operation
 <sharding-resharding>`. It is returned as ``-1`` when a new resharding
 operation starts.
 
-Starting in:
+Starting in MongoDB 7.0, ``remainingOperationTimeEstimatedSecs`` is also 
+available on the coordinator during a resharding operation. 
 
-- MongoDB 5.0, but before MongoDB 7.0,
-  ``remainingOperationTimeEstimatedSecs`` is only available on a
-  :ref:`recipient shard <resharding-process-details>` during a
-  resharding operation.
-- MongoDB 7.0, ``remainingOperationTimeEstimatedSecs`` is also available
-  on the coordinator during a resharding operation.
+``remainingOperationTimeEstimatedSecs`` 
+is set to a pessimistic time estimate:
 
-The resharding operation performs these phases in order:
-
-#. The clone phase duplicates the current collection data.
-#. The building indexes phase builds indexes on the resharded collection.
-#. The catch-up phase applies any pending write operations to the
-   resharded collection.
-
-``remainingOperationTimeEstimatedSecs`` is set to a pessimistic time
-estimate:
-
-- The catch-up phase time estimate is set to the clone phase time, which
+- The catch-up phase time estimate is set to the clone phase time, which 
   is a relatively long time.
-- In practice, if there are only a few pending write operations, the
+- In practice, if there are only a few pending write operations, the 
   actual catch-up phase time is relatively short.
+
diff --git a/source/includes/reshard-to-same-key/addl-resource-reqs.rst b/source/includes/reshard-to-same-key/addl-resource-reqs.rst
@@ -0,0 +1,5 @@
+Your cluster must meet these additional requirements:
+
+- A minimum oplog window of 24 hours.
+- I/O capacity below 50%.
+- CPU load below 80%.
diff --git a/source/includes/reshard-to-same-key/latency.rst b/source/includes/reshard-to-same-key/latency.rst
@@ -0,0 +1,5 @@
+You must ensure that your application can tolerate two seconds where 
+the collection being resharded blocks writes. When writes are blocked, 
+your application experiences an increase in latency. If your workload 
+cannot tolerate this requirement, use chunk migrations to balance your 
+cluster.
diff --git a/source/includes/reshard-to-same-key/storage.rst b/source/includes/reshard-to-same-key/storage.rst
@@ -0,0 +1,26 @@
+Calculate the required storage space for the resharding operation by 
+adding your collection size and index size, assuming a minimum oplog 
+window of 24 hours by using this formula:
+
+.. code-block:: none
+ 
+   Available storage required on each shard = [(collection size + index size) *2 ] / number of shards the collection will be distributed across.
+
+For example, a 2TB collection and 400GB of indexes distributed across 
+4 shards will need a minimum of 1.2TB of available storage per shard:
+
+.. code-block:: none
+    
+   [ (2 TB + 400GB) * 2 ] / 4 shards = 1.2 TB / shard
+
+You must confirm that you have the available storage space in your 
+cluster.
+
+If there is insufficient space or I/O headroom available, you must 
+increase the storage size. If there is insufficient CPU headroom, you 
+must scale up the cluster by selecting a higher instance size.
+
+.. tip:: 
+
+   If your MongoDB cluster is hosted on Atlas, you can use the Atlas UI to 
+   review storage, CPU, and I/O headroom metrics.
diff --git a/source/includes/reshardCollection-procedure-syntax.rst b/source/includes/reshardCollection-procedure-syntax.rst
@@ -0,0 +1,16 @@
+.. code-block:: javascript
+
+   db.adminCommand(
+      {
+        reshardCollection: "<database>.<collection>",
+        key: { "<shardkey>" },
+        zones: [
+            {
+                min: { "<document with same shape as shardkey>" },
+                max: { "<document with same shape as shardkey>" },
+                zone: <string> | null
+            },
+        ],
+        forceRedistribution: <bool>
+      }
+   )
diff --git a/source/includes/reshardCollection-syntax.rst b/source/includes/reshardCollection-syntax.rst
@@ -0,0 +1,19 @@
+.. code-block:: javascript
+
+   db.adminCommand(
+      {
+        reshardCollection: "<database>.<collection>",
+        key: { "<shardkey>" },
+        unique: <boolean>,
+        numInitialChunks: <integer>,
+        collation: { locale: "simple" },
+        zones: [
+            {
+                min: { "<document with same shape as shardkey>" },
+                max: { "<document with same shape as shardkey>" },
+                zone: <string> | null
+            },
+        ],
+        forceRedistribution: <bool>
+      }
+   )
diff --git a/source/includes/resharding-about.rst b/source/includes/resharding-about.rst
@@ -0,0 +1,4 @@
+- Use the :ref:`Reshard to Shard <reshard-to-shard-def>` technique to shard a collection and distribute its data across all relevant shards
+- Add new shards faster
+- Remove shards faster 
+- Rewrite collections to reclaim disk space
diff --git a/source/includes/resharding-operation-phases.rst b/source/includes/resharding-operation-phases.rst
@@ -0,0 +1,8 @@
+The resharding operation performs these phases in order:
+
+#. The clone phase duplicates the current collection data.
+#. The building indexes phase builds indexes on the resharded collection.
+#. The catch-up phase applies any pending write operations to the 
+   resharded collection.
+#. The commit phase renames the temporary collection and drops the old 
+   collection to perform a cut-over.
diff --git a/source/reference/command/reshardCollection.txt b/source/reference/command/reshardCollection.txt
@@ -43,26 +43,7 @@ Syntax
 
 The command has the following syntax:
 
-.. code-block:: javascript
-
-   db.adminCommand(
-      {
-        reshardCollection: "<database>.<collection>",
-        key: <shardkey>,
-        unique: <boolean>,
-        numInitialChunks: <integer>,
-        collation: { locale: "simple" },
-        zones: [
-            {
-                min: <document with same shape as shardkey>,
-                max: <document with same shape as shardkey>,
-                zone: <string> | null
-            },
-            ...
-        ],
-        forceRedistribution: <bool>
-      }
-   )
+.. include:: /includes/reshardCollection-syntax.rst
 
 Command Fields
 --------------
diff --git a/source/reference/command/shardCollection.txt b/source/reference/command/shardCollection.txt
@@ -329,9 +329,11 @@ in the ``records`` database and uses the ``zipcode`` field as the
    db.adminCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )
    
 
-.. seealso::
+Learn More
+----------
 
-   - :dbcommand:`refineCollectionShardKey`
-   - :method:`sh.balancerCollectionStatus()`
-   - :method:`sh.shardCollection()`
-   - :doc:`/sharding`
+- :dbcommand:`refineCollectionShardKey`
+- :method:`sh.balancerCollectionStatus()`
+- :method:`sh.shardCollection()`
+- :doc:`/sharding`
+- :ref:`reshard-to-same-key`
diff --git a/source/reference/method/sh.reshardCollection.txt b/source/reference/method/sh.reshardCollection.txt
@@ -222,7 +222,7 @@ Example output:
 
 .. _reshardCollection-to-same-key:
 
-Reshard a Collection to the Same Shard Key
+Reshard a Collection to the same Shard Key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to reshard to the same shard key, set :ref:`forceRedistribution 
@@ -255,6 +255,8 @@ Example output:
      operationTime: Timestamp({ t: 1733502241, i: 20 })
    }
 
+For details, see :ref:`<resharding-a-collection-back-to-same-key>`.
+
 Reshard a Collection with Zones
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/tutorial/remove-shards-from-cluster.txt b/source/tutorial/remove-shards-from-cluster.txt
@@ -138,7 +138,10 @@ Steps
          waiting for the balancer to migrate chunks. The cluster ensures
          that data is not placed on any draining shards. You can't run
          ``moveCollection`` and ``reshardCollection`` operations
-         simultaneously.
+         simultaneously. 
+
+         For the full procedure, see 
+         :ref:`resharding-for-adding-and-removing-shards-tutorial`.
 
    .. step:: Move unsharded collections to another shard
 
diff --git a/source/tutorial/resharding-back-to-same-key.txt b/source/tutorial/resharding-back-to-same-key.txt
diff --git a/source/tutorial/resharding-for-adding-and-removing-shards.txt b/source/tutorial/resharding-for-adding-and-removing-shards.txt
