DOCS-990 document bounds parameter to split/movechunk/sh.moveChunk

source/administration/security.txt

@@ -403,7 +403,7 @@ and secure sensitive data within MongoDB. The solution encrypts data in
 real time and Gazzang provides advanced key management that ensures
 only authorized processes and can access this data. The Gazzang
 software ensures that the cryptographic keys remain safe and ensures
-compliance with standards including HIPPA, PCI-DSS, and FERPA. For
+compliance with standards including HIPAA, PCI-DSS, and FERPA. For
 more information consider the following resources:
 
 - `Datasheet`_

source/reference/command/moveChunk.txt

@@ -10,29 +10,44 @@ moveChunk
    moves :term:`chunks <chunk>` between :term:`shards <shard>`.
    You must issue the
    :dbcommand:`moveChunk`
-   command against the :term:`admin database` in the form:
+   command against the :term:`admin database` of a
+   :program:`mongos` instance in the form:
 
    .. code-block:: javascript
 
       db.runCommand( { moveChunk : <namespace> ,
-                       find : <query> ,
+                       find : <document> ,
                        to : <destination>,
                        <options> } )
 
-   :param namespace moveChunk:
+   :param string moveChunk:
 
       The name of the :term:`collection` where the :term:`chunk`
       exists. Specify the collection's full namespace, including the
       database name.
 
    :param document find:
 
-      A document including the :term:`shard key`.
+      A document contained in the chunk that will be selected for splitting.
 
-   :param host to:
+      Do not use ``find`` on a collection with a :term:`hashed shard key`.
 
-      The identifier of the shard, that you want to migrate the chunk
-      to.
+      You may specify either ``bounds`` or ``find`` but not both.
+
+   :param array bounds:
+
+      Specify the bounds of a specific chunk to move.  The array must
+      consist of two documents specifying the lower and upper shard key
+      values of a chunk to move.
+
+      You may specify either ``bounds`` or ``find`` but not both.
+
+      Use this option to move chunks in collections partitioned using
+      a hashed shard key.
+
+   :param string to:
+
+      The name of the destination shard for the chunk.
 
    :param boolean _secondaryThrottle:
 
@@ -42,29 +57,34 @@ moveChunk
       migrations. For details, see
       :ref:`sharded-cluster-config-secondary-throttle`.
 
-   Use the :method:`sh.moveChunk()` helper in the :program:`mongo`
-   shell to migrate chunks manually.
-
    The :ref:`chunk migration <sharding-chunk-migration>` section
    describes how chunks move between shards on MongoDB.
 
-   :dbcommand:`moveChunk` will return the following if another cursor
-   is using the chunk you are moving:
+   :dbcommand:`moveChunk` return the following if another
+   metadata operation is taking place on the chunk's collection:
 
    .. code-block:: none
 
       errmsg: "The collection's metadata lock is already taken."
 
-   These errors usually occur when there are too many open
-   :term:`cursors <cursor>` accessing the chunk you are migrating. You
-   can either wait until the cursors complete their operation or close
-   the cursors manually.
+   If another process, such as a balancer process, changes meta data while
+   ``moveChunk`` is running, you may see this error. You may retry the
+   ``moveChunk`` operation without side effects
 
    .. note::
 
       Only use the :dbcommand:`moveChunk` in special circumstances
       such as preparing your :term:`sharded cluster` for an initial
-      ingestion of data, or a large bulk import operation. See
+      ingestion of data, or a large bulk import operation.
+      In most cases allow the balancer to create and balance chunks
+      in sharded clusters.
+      See
       :ref:`sharding-administration-create-chunks` for more information.
 
    .. admin-only
+
+   .. seealso:: :dbcommand:`split`,
+                :method:`sh.moveChunk()`,
+                :method:`sh.splitAt()`,
+                :method:`sh.splitFind()`
+

source/reference/command/split.txt

@@ -15,31 +15,115 @@ split
    In most clusters, MongoDB will manage all chunk creation and
    distribution operations without manual intervention.
 
-   .. include:: /includes/warning-splitting-chunks.rst
-
-   Consider the following example:
+   You must issue the :dbcommand:`split` command while connected
+   to the ``admin`` database of a :program:`mongos` instance.
 
    .. code-block:: javascript
 
-      db.runCommand( { split : "test.people" , find : { _id : 99 } } )
+      db.runCommand( { split: <database>.<collection>, find: <document> } )
+
+   Or:
 
-   This command inserts a new split in the collection named
-   ``people`` in the ``test`` database. This will split the chunk
-   that contains the document that matches the query ``{ _id : 99
-   }`` in half. If the document specified by the query does not (yet)
-   exist, the :dbcommand:`split` will divide the chunk where that
-   document *would* exist.
+   .. code-block:: javascript
+
+      db.runCommand( { split: <database>.<collection>, middle: <document key> } )
 
-   The split divides the chunk in half, and does *not* split the chunk
-   using the identified document as the middle. To define an arbitrary split
-   point, use the following form:
+   Or:
 
    .. code-block:: javascript
 
-      db.runCommand( { split : "test.people" , middle : { _id : 99 } } )
+      db.runCommand( { split: <database>.<collection>, bounds: [ <lower>, <upper> ] } )
+
+
+   :param string split:
+
+      The name of the :term:`collection` where the :term:`chunk`
+      exists. Specify the collection's full namespace, including the
+      database name.
+
+   :param document find:
+
+      A document contained in the chunk that will be selected for splitting.
+
+      Do not use ``find`` on a collection with a :term:`hashed shard key`.
+
+      You must specify only one of: ``find``, ``bounds``, or ``middle``.
+
+
+   :param array bounds:
+
+      .. versionadded:: 2.4
+
+      Specify the bounds of a specific chunk to split in half.  The
+      array must consist of two documents specifying the lower and upper
+      shard key values of a chunk to split.  The values must match the
+      minimum and maximum values of an existing chunk. You must specify
+      only one of: ``find``, ``bounds``, or ``middle``.
+
+      This option is used primarily to support chunks with
+      hashed shard keys.
+
+   :param document middle:
+
+      The document key which will be used as a split point.
+      A document with this key does not need to exist.
+      You must specify only one of: ``find``, ``bounds``, or ``middle``.
+
+   .. include:: /includes/warning-splitting-chunks.rst
+
+   .. example::
+
+      .. code-block:: javascript
+
+         db.runCommand( { split : "test.people" , find : { _id : 99 } } )
+
+      This command splits a chunk of the collection
+      ``people`` in the ``test`` database. This will split the chunk
+      that contains the document that matches the query ``{ _id : 99
+      }`` approximately in half. If the document specified by the query does not
+      exist, the :dbcommand:`split` will divide the chunk in half.
+
+   .. example::
+
+      To define an arbitrary split point, use the following form:
+
+      .. code-block:: javascript
+
+         db.runCommand( { split : "test.people" , middle : { _id : 99 } } )
+
+      This form is typically used when :term:`pre-splitting` data in a
+      collection.
+
+   .. example::
+
+      To split a specific chunk in half using the minimum and maximum values of the
+      :term:`hashed shard key` of that chunk use the following:
+
+      .. code-block:: javascript
+
+         db.runCommand( { split: "test.people" ,
+                        bounds : [ NumberLong("-5838464104018346494"), NumberLong("-5557153028469814163")] } )
+
+   The :ref:`chunk migration <sharding-chunk-migration>` section
+   describes how chunks move between shards on MongoDB.
+
+   :dbcommand:`split` will return the following if another
+   metadata operation is taking place on the chunk's collection:
+
+   .. code-block:: none
+
+      errmsg: "The collection's metadata lock is already taken."
 
-   This form is typically used when :term:`pre-splitting` data in a
-   collection.
 
    :dbcommand:`split` is an administrative command that is only
    available for :program:`mongos` instances.
+
+   If another process, such as a balancer process, changes meta data while
+   ``split`` is running, you may see this error. You may retry the
+   ``split`` operation without side effects
+
+
+   .. seealso:: :dbcommand:`moveChunk`,
+                :method:`sh.moveChunk()`,
+                :method:`sh.splitAt()`,
+                :method:`sh.splitFind()`

source/reference/command/splitChunk.txt

@@ -1,15 +1,51 @@
-==========
-splitChunk
-==========
+=====================
+splitChunk (internal)
+=====================
 
 .. default-domain:: mongodb
 
 .. dbcommand:: splitChunk
 
-   :dbcommand:`splitChunk` is an internal command. Use the
+   :dbcommand:`splitChunk` is an internal administrative command.
+   Use the
    :method:`sh.splitFind()` and :method:`sh.splitAt()` functions in the
    :program:`mongo` shell to access this functionality.
 
    .. include:: /includes/warning-splitting-chunks.rst
 
+   :param string ns:
+
+      A string with the complete namespace of the chunk to split.
+
+   :param document keyPattern:
+
+      Specifies the shard key.
+
+   :param document min:
+
+      Specifies the lower bound of the shard key for the
+      chunk to split.
+
+   :param document max:
+
+      Specifies the upper bound of the shard key for the
+      chunk to split.
+
+   :param string from:
+
+      Specifies the server to split the chunk on.
+
+   :param document splitKeys:
+
+      Specifies the split point for the chunk.
+
+   :param document shardId:
+
+      Specifies the shard id.
+
    .. admin-only.
+
+   .. seealso:: :dbcommand:`moveChunk`,
+                :method:`sh.moveChunk()`,
+                :method:`sh.splitAt()`,
+                :method:`sh.splitFind()`

source/reference/method/sh.moveChunk.txt

@@ -9,20 +9,25 @@ sh.moveChunk()
    :param string collection: Specify the sharded collection containing
                              the chunk to migrate.
 
-   :param query: Specify a query to identify documents in a specific
-                 chunk. Typically specify the :term:`shard key` for a
-                 document as the query.
+   :param document query:
+
+      A document contained in the chunk that will be selected for splitting.
+
+      Do not use :method:`sh.moveChunk` on a collection with a
+      :term:`hashed shard key`, use :dbcommand:`moveChunk` instead.
 
    :param string destination: Specify the name of the shard that you
                               wish to move the designated chunk to.
 
-   Moves the chunk containing the documents specified by the ``query``
+   Moves the chunk containing the document specified by the ``query``
    to the shard described by ``destination``.
 
-   This function provides a wrapper around the
+   This method provides a wrapper around the
    :dbcommand:`moveChunk`. In most circumstances, allow the
    :term:`balancer` to automatically migrate :term:`chunks <chunk>`,
    and avoid calling :method:`sh.moveChunk()` directly.
 
-   .. seealso:: ":dbcommand:`moveChunk`" and ":doc:`/sharding`" for
-      more information.
+   .. seealso:: :dbcommand:`moveChunk`, :method:`sh.splitAt()`,
+                :method:`sh.splitFind()`, :doc:`/sharding`,
+                and :ref:`chunk migration <sharding-chunk-migration>`.
+