diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index 30a193987a2..45452567b72 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -619,13 +619,17 @@ In most circumstances, you should let the automatic balancer migrate :term:`chunks ` between :term:`shards `. However, you may want to migrate chunks manually in a few cases: -- If you create chunks by presplitting the data in your collection, +- If you create chunks by :term:`pre-splitting` the data in your collection, you will have to migrate chunks manually to distribute chunks evenly across the shards. - If the balancer in an active cluster cannot distribute chunks within the balancing window, then you will have to migrate chunks manually. +See the :ref:`chunk migration ` section to +understand the internal process of how :term:`chunks ` move +between :term:`shards `. + To migrate chunks, use the :dbcommand:`moveChunk` command. .. note:: @@ -654,6 +658,10 @@ This command moves the chunk that includes the shard key value "smith" to the :term:`shard` named ``mongodb-shard3.example.net``. The command will block until the migration is complete. +See the :ref:`create chunks ` section +for an overview of how :term:`pre-splitting` can improve initial data +load on a :term:`shard cluster`. + .. versionadded:: 2.2 :dbcommand:`moveChunk` command has the: ``_secondaryThrottle`` paramenter. When set to ``true``, MongoDB ensures that diff --git a/source/faq/sharding.txt b/source/faq/sharding.txt index 31b50180344..8cb135e8f58 100644 --- a/source/faq/sharding.txt +++ b/source/faq/sharding.txt @@ -342,7 +342,7 @@ Consider the following error message: ERROR: moveChunk commit failed: version is at | instead of |" and "ERROR: TERMINATING" :program:`mongod` procudes this message if, during a :ref:`chunk -migration `, the term:`shard` could not +migration `, the :term:`shard` could not connect to the :term:`config database` to update chunk information. If the shard cannot update the config database after :dbcommand:`moveChunk`, the shard cluster will have an inconsistent diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 9a83260efe4..4d46ad990d7 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -6,13 +6,35 @@ moveChunk .. dbcommand:: moveChunk - :dbcommand:`moveChunk` is an internal command that supports the - sharding. Use the :method:`sh.moveChunk()` helper in the - :program:`mongo` shell for manual chunk migrations. + :dbcommand:`moveChunk` is an internal command that moves + :term:`chunks ` between :term:`shards `. The command + has the following prototype form: - :option _secondaryThrottle: Set to ``false`` by default. Provides - :ref:`write concern ` - support for chunk migrations. + .. code-block:: javascript + + db.runCommand( { moveChunk : , + find : , + to : , + } ) + + :param command moveChunk: The name of the :term:`collection` which + the :term:`chunk` exists. The + collection's full namespace must be + given, including the database name, for + example: ``"test.blog.posts"``. + + :param find: A query expression that specifies a document of the + chunk to be moved, for example: ``{ author: "eliot" + }``. The query does not have to be related to the + :term:`shard key`. + + :param to: The shard ID where the chunk will be moved to, for + example: ``"shard1"``. + + :param _secondaryThrottle: Optional. Set to ``false`` by + default. Provides :ref:`write concern + ` support for chunk + migrations. If ``_secondaryThrottle`` is set to ``true``, during chunk migrations when a :term:`shard` hosted by a :term:`replica set`, @@ -21,7 +43,31 @@ moveChunk data. In the balancer configuration, the ``replThrottle`` configuration provides ``_secondaryThrottle`` behavior. - For details on chunk migrations see the :ref:`Chunk Migration - ` section. + Use the :method:`sh.moveChunk()` helper in the :program:`mongo` + shell to migrate chunks manually. + + The :ref:`chunk migration ` section + describes how chunks move between shards on MongoDB. + + :dbcommand:`moveChunk` will return the following if the + chunk to be moved is in use by another :term:`cursor`: + + .. code-block:: none + + errmsg: "The collection's metadata lock is already taken." + + These errors usually occur when there are too many open + :term:`cursors ` accessing the chunk you are migrating. You + can either wait until the cursors complete their operation or close + the cursors manually. + + .. note:: + + The :dbcommand:`moveChunk` command should be used in special circumstances + such as preparing your :term:`shard cluster` for an initial + ingestion of data. + + .. seealso:: ":ref:`Create chunk `" + .. admin-only