sh.reshardCollection.txt

======================
sh.reshardCollection()
======================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: sh.reshardCollection(namespace, key, unique, options)

   .. versionadded:: 5.0

   The :method:`sh.reshardCollection()` method changes the shard key for
   a collection and changes the distribution of your data.

   Before you reshard a collection, read the the :ref:`reshard
   requirements <reshard-requirements>` and :ref:`reshard limitations
   <resharding-limitations>`.

   .. |dbcommand| replace:: :dbcommand:`reshardCollection` command
   .. include:: /includes/fact-mongosh-shell-method-alt.rst

   ``sh.reshardCollection()`` takes the following fields:

   .. list-table::
      :header-rows: 1
      :widths: 20 20 80

      * - Field
        - Type
        - Description

      * - ``namespace``
        - string
        - The :term:`namespace` of the collection to shard in the form
          ``"<database>.<collection>"``.

      * - ``key``
        - document
        - The document that specifies the new field or fields to use as the
          :ref:`shard key <sharding-shard-key>`.

          ``{ <field1>: <1|"hashed">, ... }``

          Set the field values to either:

          - ``1`` for :ref:`range-based sharding <sharding-ranged>`
          - ``"hashed"`` to specify a
            :ref:`hashed shard key <hashed-shard-keys>`.

          See also :ref:`sharding-shard-key-indexes`

      * - ``unique``
        - boolean
        - Optional. Specify whether there is a :doc:`uniqueness
          </core/index-unique>` constraint on the shard key. Only
          ``false`` is supported. Defaults to ``false``.

      * - ``options``
        - document
        - Optional. A document containing optional fields, including
          ``numInitialChunks``, ``collation``, ``zones`` and
          ``forceRedistribution``.

   The ``options`` field supports the following fields:

   .. list-table::
      :header-rows: 1
      :widths: 20 20 80

      * - Field
        - Type
        - Description

      * - ``numInitialChunks``
        - integer
        - Optional. Specifies the initial number of chunks to create
          across all shards in the cluster when resharding a collection.
          The default value is ``90``. MongoDB will then create and balance 
          chunks across the cluster. The ``numInitialChunks`` must result 
          in less than ``8192`` per shard.
 
          .. include:: /includes/initial-chunks-recommendation.rst

      * - ``collation``
        - document
        - Optional. If the collection specified to ``reshardCollection``
          has a default :ref:`collation <collation>`, you *must* include a 
          collation document with ``{ locale : "simple" }``, or the 
          ``reshardCollection`` command fails.

      * - ``zones``
        - array
        - Optional. Specifies the zones for the collection.
          
          To maintain or add :ref:`zones <zone-sharding>`,
          specify the zones for your collection in an array:

          .. code-block:: javascript
              :copyable: false

              [
                {s
                    min: <document with same shape as shardkey>,
                    max: <document with same shape as shardkey>,
                    zone: <string> | null
                },
                ...
              ]

      * - ``forceRedistribution``
        - boolean
        - .. _forceRedistribution-option:
          
          .. include:: /includes/fact-forceRedistribution-desc.rst

Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-no-free.rst

.. include:: /includes/fact-environments-onprem-only.rst

Considerations
--------------

.. include:: /includes/sharding/reshard-build-indexes-consideration.rst

.. _resharding-process-details:

Resharding Process
------------------

.. include:: /includes/reshard-collection-introduction.rst

Initialization Phase
~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/reshard-collection-initialization.rst

Clone Phase
~~~~~~~~~~~

.. include:: /includes/reshard-collection-clone.rst

Index Phase
~~~~~~~~~~~

.. include:: /includes/reshard-collection-index.rst

Apply and Catch-up Phase
~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/reshard-collection-apply-and-catchup.rst

.. note::

   If required, you can manually force the resharding operation to
   complete by issuing the :method:`sh.commitReshardCollection()`
   method. This is useful if the current time estimate to complete the
   resharding operation is an acceptable duration for your collection
   to block writes. The :method:`sh.commitReshardCollection()` method
   blocks writes early and forces the resharding operation to
   complete. During the time period where writes are blocked your
   application experiences an increase in latency.

.. _resharding-commit-phase-method:

Commit Phase
~~~~~~~~~~~~

.. include:: /includes/reshard-collection-commit.rst

.. note:: 

   Once the resharding process reaches the commit phase, the process
   cannot be ended with :method:`sh.abortReshardCollection()`.
   
Examples
--------

Reshard a Collection
~~~~~~~~~~~~~~~~~~~~

The following example reshards the ``sales.orders`` collection with the
new shard key ``{ order_id: 1 }``:

.. code-block:: javascript

   sh.reshardCollection( "sales.orders", { order_id: 1 } )

Example output:

.. code-block:: javascript
   :copyable: false

   {
     ok: 1,
     '$clusterTime': {
       clusterTime: Timestamp(1, 1624887954),
       signature: {
         hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
         keyId: 0
       }
     },
     operationTime: Timestamp(1, 1624887947)
   }

.. _reshardCollection-to-same-key:

Reshard a Collection to the Same Shard Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order to reshard to the same shard key, set :ref:`forceRedistribution 
<forceRedistribution-option>` to ``true``. The following example 
reshards the ``sales.orders`` collection to the same shard key
``{ order_id: 1 }`` and redistributes data. 

.. code-block:: javascript

   sh.reshardCollection( 
     "sales.orders", 
     { order_id: 1 }, 
     { forceRedistribution: true } 
   )

Example output:

.. code-block:: javascript
   :copyable: false

   {
     ok: 1,
     '$clusterTime': {
       clusterTime: Timestamp({ t: 1733502241, i: 20 }),
       signature: {
         hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
         keyId: Long('0')
       }
     },
     operationTime: Timestamp({ t: 1733502241, i: 20 })
   }

Reshard a Collection with Zones
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Reshard a collection with zones when you need to adjust the distribution 
of data across the shards in your cluster to meet changing requirements or 
to improve performance. 

In the following example, the ``test.scores`` collection resides on ``shard0`` 
and ``shard1``. The current shard key is ``{ _id: 1}``. 

.. procedure::
   :style: normal

   .. step:: Add shards to a new zone

      In this example, this zone is called ``NewZone``.

      .. code-block:: javascript

         sh.addShardToZone( "shard2", "NewZone" )
         sh.addShardToZone( "shard3", "NewZone" )

   .. step:: Run ``sh.reshardCollection`` with the new zone information

      .. code-block:: javascript

         sh.reshardCollection(
           "test.scores", 
           { "studentId": 1, "testId": 1}, 
           { zones: [ {
             min: { "studentId": MinKey(), "testId": MinKey() },
             max: { "studentId": MaxKey(), "testId": MaxKey() },
             zone: "NewZone" }
             ]
         } )

      The resharding operation adds the shards in zone ``NewZone`` as recipients. 
      The database primary shard is added as a recipient as a backstop for any
      missing ranges in the zone definition. If there are no missing ranges, the 
      collection is cloned on shards in the "NewZone", such as ``shard2`` and 
      ``shard3`` in this example. ``sh.reshardCollection`` returns the following:

      .. code-block:: javascript
         :copyable: false 

         {
            ok: 1,
            '$clusterTime': {
            clusterTime: Timestamp( { t: 1699484530, i: 54 } ),
            signature: {
            hash: Binary.createFromBase64( "90ApBDrSSi4XnCpV3OWIH4OGO0Y=", 0 ),
            keyId: Long( "7296989036055363606" )
            } },
            operationTime: Timestamp( { t: 1699484530, i: 54 } )
         }


Learn More
----------

- :ref:`<sharding-resharding>`