From 56230ee474137cfcf838467b13ffa952dacd60cc Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 5 Sep 2012 11:06:15 -0400 Subject: [PATCH 1/3] adding in line to link with Chunk Migration and Create Chunk section --- source/administration/sharding.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index 30a193987a2..94bcb68d416 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -626,6 +626,11 @@ However, you may want to migrate chunks manually in a few cases: - If the balancer in an active cluster cannot distribute chunks within the balancing window, then you will have to migrate chunks manually. +To further understand the chunk migration process in detail, see the +:ref:`sharding-chunk-migration` section, and how to improve throughput +for a shard cluster, see the +:ref:`sharding-administration-create-chunks` section. + To migrate chunks, use the :dbcommand:`moveChunk` command. .. note:: From c5fb9c02ecdbde55fb102eea9a35bda195a3bcd4 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Wed, 5 Sep 2012 16:17:30 -0400 Subject: [PATCH 2/3] added more content to the moveChunk command page. --- source/administration/sharding.txt | 13 +++-- source/faq/sharding.txt | 2 +- source/reference/command/moveChunk.txt | 72 ++++++++++++++++++++------ 3 files changed, 66 insertions(+), 21 deletions(-) diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index 94bcb68d416..96ce6b36cbf 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -619,17 +619,16 @@ 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. -To further understand the chunk migration process in detail, see the -:ref:`sharding-chunk-migration` section, and how to improve throughput -for a shard cluster, see the -:ref:`sharding-administration-create-chunks` section. +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. @@ -659,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 :ref:`create chunks ` to +understand how to use :term:`pre-splitting` to 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..88d5915c71b 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -6,22 +6,64 @@ 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 + uses the following syntax: + + .. code-block:: javascript + + db.runCommand( { moveChunk : , + find : , + to : , + } ) + + :param 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" }`` + + :param to: the shard ID where the chunk will be moved to, for + example: ``"shard1"`` + :option _secondaryThrottle: 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`, - the :program:`mongod` will wait until the :term:`secondary` members - replicate the migration operations continuing to migrate chunk - data. In the balancer configuration, the ``replThrottle`` - configuration provides ``_secondaryThrottle`` behavior. - - For details on chunk migrations see the :ref:`Chunk Migration - ` section. + :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`, + the :program:`mongod` will wait until the :term:`secondary` + members replicate the migration operations continuing to migrate + chunk data. In the balancer configuration, the ``replThrottle`` + configuration provides ``_secondaryThrottle`` behavior. + + Use the :method:`sh.moveChunk()` helper in the :program:`mongo` + shell for manual chunk migrations. + + For details on how chunks move within MongoDB see the :ref:`chunk + migration ` section. + + :dbcommand:`moveChunk` will return the following ``errmsg`` if the + :term:`chunk` to be moved is in use by another :term:`cursor`: + + .. code-block:: none + + 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:: + + This command should not be used except in special circumstances + such as preparing your :term:`shard cluster` for an initial + ingest of data. + + .. seealso:: ":ref:`Create chunk `" + .. admin-only From b18005d3670d419921539b457025118d3e710442 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Thu, 6 Sep 2012 10:55:16 -0400 Subject: [PATCH 3/3] additional revisions for clarity and style --- source/administration/sharding.txt | 4 +- source/reference/command/moveChunk.txt | 56 ++++++++++++++------------ 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index 96ce6b36cbf..45452567b72 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -658,8 +658,8 @@ 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 :ref:`create chunks ` to -understand how to use :term:`pre-splitting` to improve initial data +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 diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 88d5915c71b..4d46ad990d7 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -8,7 +8,7 @@ moveChunk :dbcommand:`moveChunk` is an internal command that moves :term:`chunks ` between :term:`shards `. The command - uses the following syntax: + has the following prototype form: .. code-block:: javascript @@ -17,40 +17,44 @@ moveChunk to : , } ) - :param 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 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" }`` + :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 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. - :option _secondaryThrottle: 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`, - the :program:`mongod` will wait until the :term:`secondary` - members replicate the migration operations continuing to migrate - chunk data. In the balancer configuration, the ``replThrottle`` - configuration provides ``_secondaryThrottle`` behavior. + If ``_secondaryThrottle`` is set to ``true``, during chunk + migrations when a :term:`shard` hosted by a :term:`replica set`, + the :program:`mongod` will wait until the :term:`secondary` members + replicate the migration operations continuing to migrate chunk + data. In the balancer configuration, the ``replThrottle`` + configuration provides ``_secondaryThrottle`` behavior. Use the :method:`sh.moveChunk()` helper in the :program:`mongo` - shell for manual chunk migrations. + shell to migrate chunks manually. - For details on how chunks move within MongoDB see the :ref:`chunk - migration ` section. + The :ref:`chunk migration ` section + describes how chunks move between shards on MongoDB. - :dbcommand:`moveChunk` will return the following ``errmsg`` if the - :term:`chunk` to be moved is in use by another :term:`cursor`: + :dbcommand:`moveChunk` will return the following if the + chunk to be moved is in use by another :term:`cursor`: .. code-block:: none - The collection's metadata lock is already taken. + 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 @@ -59,9 +63,9 @@ moveChunk .. note:: - This command should not be used except in special circumstances + The :dbcommand:`moveChunk` command should be used in special circumstances such as preparing your :term:`shard cluster` for an initial - ingest of data. + ingestion of data. .. seealso:: ":ref:`Create chunk `"