DOCS-15363 documents moveRange (#1947) (#1985)

* documents moveRange

* review feedback

* restores moveChunk() method

* cleanup

* toShard

* removes moveChunk

* updates

* revert 2.6

* revert

* review feedback

* review feedback

Author: jmd-mongo

source/core/sharding-balancer-administration.txt

@@ -138,10 +138,10 @@ All chunk migrations use the following procedure:
 #. The balancer process sends the :dbcommand:`moveChunk` command to
    the source shard.
 
-#. The source starts the move with an internal :dbcommand:`moveChunk`
-   command. During the migration process, operations to the chunk
-   route to the source shard. The source shard is responsible for
-   incoming write operations for the chunk.
+#. The source starts the move when it receives an internal 
+   :dbcommand:`moveRange` command. During the migration process, 
+   operations to the chunk are sent to the source shard. The source 
+   shard is responsible for incoming write operations for the chunk.
 
 #. The destination shard builds any indexes required by the source
    that do not exist on the destination.
@@ -235,8 +235,8 @@ This queuing behavior allows shards to unload chunks more quickly in
 cases of heavily imbalanced cluster, such as when performing initial
 data loads without pre-splitting and when adding new shards.
 
-This behavior also affects the :dbcommand:`moveChunk` command, and
-migration scripts that use the :dbcommand:`moveChunk` command may
+This behavior also affects the :dbcommand:`moveRange` command, and
+migration scripts that use the :dbcommand:`moveRange` command may
 proceed more quickly.
 
 In some cases, the delete phases may persist longer. Starting in MongoDB
@@ -245,7 +245,7 @@ a failover during the delete phase. Orphaned documents are cleaned up
 even if a replica set's primary crashes or restarts during this phase.
 
 The ``_waitForDelete``, available as a setting for the balancer as well
-as the :dbcommand:`moveChunk` command, can alter the behavior so that
+as the :dbcommand:`moveRange` command, can alter the behavior so that
 the delete phase of the current migration blocks the start of the next
 chunk migration. The ``_waitForDelete`` is generally for internal
 testing purposes. For more information, see

source/core/sharding-data-partitioning.txt

@@ -159,6 +159,7 @@ chunks across shards. See :ref:`sharding-internals-balancing` for more
 details on balancing chunks across shards.
 
 .. _sharding-chunk-migration:
+.. _sharding-range-migration:
 
 Chunk Migration
 ---------------

source/reference/command/moveRange.txt

@@ -0,0 +1,234 @@
+=========
+moveRange
+=========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. dbcommand:: moveRange
+
+   Moves :term:`ranges <range>` between :term:`shards <shard>`. Run
+   the :dbcommand:`moveRange` command with a :binary:`~bin.mongos` 
+   instance while using the :term:`admin database`.
+   
+Syntax
+------
+
+The command has the following syntax:
+
+.. code-block:: javascript
+
+   db.adminCommand( 
+     { 
+       toShard: <ID of the recipient shard>,
+       min: <min key of the range to move>,
+       max: <max key of the range to move>, // optional
+       forceJumbo: <bool>, // optional
+       waitForDelete: <bool>, // optional
+       writeConcern: <write concern>, // optional
+       secondaryThrottle: <bool> // optional
+     } 
+   )
+
+Command Fields
+--------------
+
+The command takes the following fields:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - Field
+     - Type
+     - Description
+
+   * - ``toShard``
+     - string
+     - ID of the recipient shard.
+
+   * - ``min``
+     - key
+     - Minimum key of the range to move.
+
+   * - ``max``
+     - key
+     - Optional.
+
+       Maximum key of the range to move. If you do not specify 
+       ``max``, given a chunk ``C`` including the shard key ``min``, 
+       ``max`` is determined in the following way:
+
+       - If the data size of the range between ``min`` and ``max(C)`` 
+         is less than the per-collection chunk size or the default 
+         chunk size, the chunk's max is selected as 
+         ``max`` = ``max(C)``.
+
+       - Otherwise, key ``max`` < ``max(C)`` where ``max`` depends 
+         on the configured chunk size.
+
+   * - :ref:`forceJumbo <moverange-forceJumbo>`
+     - boolean
+     - .. _moverange-forceJumbo:
+    
+       Optional. 
+
+       Flag that determines if the command can move a range that is 
+       :ref:`too large to migrate <migration-chunk-size-limit>`. The 
+       range may or may not be labeled as :ref:`jumbo <jumbo-chunk>`.
+
+       - If ``true``, the command can move the range.
+       - If ``false``, the command cannot move the range.
+
+       The default is ``false``.
+
+   * - ``writeConcern``
+     - document
+     - Optional. 
+
+       Document with the :ref:`write concern <write-concern>`.
+
+       The default is :writeconcern:`w: majority <"majority">`.
+
+   * - ``secondaryThrottle``
+     - boolean
+     - Optional. 
+
+       - If ``true``, each document move during chunk migration 
+         propagates to at least one secondary before the balancer 
+         proceeds with the next document. This is equivalent to a write 
+         concern of :writeconcern:`{ w: 2 } <\<number\>>`. 
+          
+         Use the ``writeConcern`` option to specify a different write 
+         concern.
+          
+       - If ``false``, the balancer does not wait for replication to a
+         secondary and instead continues with the next document.
+
+       For more information, see
+       :ref:`sharded-cluster-config-secondary-throttle`.
+       
+The :ref:`range migration <sharding-chunk-migration>` section
+describes how ranges move between shards on MongoDB.
+
+Considerations
+--------------
+
+Only use the :dbcommand:`moveRange` in scenarios like:
+
+- an initial ingestion of data
+- a large bulk import operation  
+
+Allow the balancer to create and balance ranges in sharded clusters in
+most cases.
+
+.. seealso::
+
+   :ref:`<create-chunks-in-a-sharded-cluster>`
+
+Examples
+--------
+
+The following examples use a collection with:
+
+- Shard key ``x``
+- Configured chunk size of 128MB
+- A chunk with boundaries: ``[x: 0, x: 100)``
+
+Specify both ``min`` and ``max``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following table lists the results of setting ``min`` and ``max``
+to various values:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - ``min``
+     - ``max``
+     - Result
+
+   * - ``0``
+     - ``100``
+     - Moves all the documents in the range to the recipient shard.
+
+   * - ``10``
+     - ``30``
+     - Creates three sub-ranges: 
+
+       - ``[x: 0, x: 10)``
+       - ``[x: 10, x: 30)`` 
+       - ``[x: 30, x: 100)``
+
+       Moves all the documents in ``[x: 10, x: 30)`` to the recipient
+       shard.
+
+   * - ``0``
+     - ``20`` 
+     - Creates two sub-ranges:
+
+       - ``[x: 0, x: 20)``
+       - ``[x: 20, x: 100)``
+       
+       Moves all the documents in ``[x: 0, x: 20)`` to the recipient
+       shard.
+   
+   * - ``40``
+     - ``100``
+     - Creates two sub-ranges:
+
+       - ``[x: 0, x: 40)``
+       - ``[x: 40, x: 100)``
+
+       Moves all the documents in ``[x: 40, x: 100)`` to the recipient
+       shard.
+
+Specify ``min`` but not ``max``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following table lists the results of setting ``min`` to various 
+values:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - ``min``
+     - Amount of Data in Key Range
+     - Result
+
+   * - ``0``
+     - Less than 128 MB contained between keys ``x: 0`` and ``x: 100``.
+     - Moves all the documents in the range to the recipient shard.
+   
+   * - ``10``
+     - Less than 128 MB contained between keys ``x: 0`` and ``x: 100``.
+     - Creates two sub-ranges:
+
+       - ``[x: 0, x: 10)``
+       - ``[x : 10, x: 100)``
+
+       Moves all documents in ``[x: 10, x: 100)`` to the recipient 
+       shard.
+
+   * - ``10``
+     - 128 MB contained between keys ``x: 10`` and ``x: 30``.
+     - Creates three sub-ranges:
+
+       - ``[x: 0, x: 10)``
+       - ``[x: 10, x: 30)`` 
+       - ``[x: 30, x: 100)``
+
+       Moves all documents in ``[x: 10, x: 30)`` to the recipient
+       shard.
+
+.. admin-only

source/reference/command/nav-sharding.txt

@@ -113,7 +113,7 @@ Sharding Commands
    * - :dbcommand:`medianKey`
 
      - Deprecated internal command. See :dbcommand:`splitVector`.
-
+   
    * - :dbcommand:`moveChunk`
 
      - Internal command that migrates chunks between shards.
@@ -122,6 +122,10 @@ Sharding Commands
 
      - Reassigns the :term:`primary shard` when removing a shard from a sharded cluster.
 
+   * - :dbcommand:`moveRange`
+
+     - Migrates ranges between shards.
+
    * - :dbcommand:`mergeChunks`
 
      - Provides the ability to combine chunks on a single shard.
@@ -210,6 +214,7 @@ Sharding Commands
    /reference/command/medianKey
    /reference/command/moveChunk
    /reference/command/movePrimary
+   /reference/command/moveRange
    /reference/command/mergeChunks
    /reference/command/refineCollectionShardKey
    /reference/command/removeShard

source/reference/command/serverStatus.txt

@@ -4284,10 +4284,10 @@ shardingStatistics
 .. serverstatus:: shardingStatistics.countDonorMoveChunkStarted
 
    The total number of times that the :dbcommand:`moveChunk` command
-   has started on the shard, of which this node is a member, as part of
-   a :ref:`chunk migration process <chunk-migration-procedure>`. This
-   increasing number does not consider whether the chunk migrations
-   succeed or not.
+   or :dbcommand:`moveRange` have started on the shard, of which this 
+   node is a member, as part of a :ref:`chunk migration process 
+   <chunk-migration-procedure>`. This increasing number does not 
+   consider whether the chunk migrations succeed or not.
 
    *Only present when run on a shard.*
 
@@ -4297,9 +4297,10 @@ shardingStatistics
    of the chunk migrations <chunk-migration-procedure>` from this
    shard, of which this node is a member. Specifically, for each
    migration from this shard, the tracked time starts with the
-   :dbcommand:`moveChunk` command and ends before the destination shard
-   enters a catch-up phase to apply changes that occurred during the
-   :ref:`chunk migrations <chunk-migration-procedure>`.
+   :dbcommand:`moveRange` and :dbcommand:`moveChunk` commands and ends 
+   before the destination shard enters a ``catchup`` phase to apply 
+   changes  that occurred during the :ref:`chunk migrations 
+   <chunk-migration-procedure>`.
 
    *Only present when run on a shard.*
 

source/reference/command/split.txt

@@ -132,6 +132,7 @@ this purpose.
 .. seealso::
 
    - :dbcommand:`moveChunk`
+   - :dbcommand:`moveRange`
    - :method:`sh.moveChunk()`
    - :method:`sh.splitAt()`
    - :method:`sh.splitFind()`

source/reference/glossary.txt

@@ -874,6 +874,15 @@ Glossary
 
       .. include:: /includes/extracts/4.2-changes-query-shapes.rst
 
+   range                                                                    
+      A contiguous range of :term:`shard key` values within a               
+      chunk. Data ranges include the lower boundary and             
+      exclude the upper boundary. MongoDB migrates data when a              
+      shard contains :ref:`too much data of a collection                    
+      <sharding-migration-thresholds>` relative to other shards.            
+      See :ref:`sharding-data-partitioning` and                             
+      :ref:`sharding-balancing`.  
+
    read concern
       Specifies a level of isolation for read operations. For example,
       you can use read concern to only read data that has propagated to

source/reference/parameters.txt

@@ -3202,10 +3202,10 @@ Sharding Parameters
 
    |mongod-only|
 
-   For :dbcommand:`moveChunk` operations, specifies the maximum
-   percentage of untrasferred data allowed by the migration protocol
-   (expressed in percentage of the total chunk size) to
-   transition from the ``catchup`` phase to the ``commit`` phase.
+   For :dbcommand:`moveChunk` and :dbcommand:`moveRange` operations, 
+   specifies the maximum percentage of untrasferred data allowed by the 
+   migration protocol (expressed in percentage of the total chunk size) 
+   to transition from the ``catchup`` phase to the ``commit`` phase.
 
    Setting a higher catchup percentage can decrease the amount of time
    it takes for the migration to complete at the cost of increased

source/tutorial/create-chunks-in-sharded-cluster.txt

@@ -1,3 +1,5 @@
+.. _create-chunks-in-a-sharded-cluster:
+
 ==================================
 Create Chunks in a Sharded Cluster
 ==================================