Skip to content

DOCS-1492 db.collection.group, hashBSONElement, moveChunk, text #1143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DOCS-1492 db.collection.group, hashBSONElement, moveChunk, text #1143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions source/reference/command/hashBSONElement-field.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
object:
name: hashBSONElement
type: command
field:
optional: false
type: field
name: key
type: BSONElement
position: 1
description: The BSON element to hash.
---
object:
name: hashBSONElement
type: command
field:
optional: false
type: field
name: seed
type: integer
position: 2
description: A seed to use to compute the hash.
...
100 changes: 59 additions & 41 deletions source/reference/command/hashBSONElement.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,69 +4,87 @@ _hashBSONElement

.. default-domain:: mongodb

Description
-----------

.. dbcommand:: _hashBSONElement

.. versionadded:: 2.4

:dbcommand:`_hashBSONElement` is an internal command that computes
the MD5 hash of a BSON element. :dbcommand:`_hashBSONElement`
returns 8 bytes from the 16 byte MD5 hash.

:param BSONElement key: Specifies the BSON element to hash.
An internal command that computes the MD5 hash of a BSON element. The
:dbcommand:`_hashBSONElement` command returns 8 bytes from the 16
byte MD5 hash.

:param integer seed: Specifies a seed to use to compute the hash.
The :dbcommand:`_hashBSONElement` command has the following fields:

:returns: A document consisting of ``key``, ``seed``, ``out``
and ``ok`` fields.

:field BSONType key: The original BSON element.
:field integer seed: The seed used for the hash, defaults to ``0``.
:field NumberLong out: The decimal result of the hash.
:field integer ok: Holds the ``1`` if the function returns
successfully, and ``0`` if the operation
encountered an error.
.. include:: /reference/command/hashBSONElement-field.rst

.. |dbcommand| replace:: :dbcommand:`_hashBSONElement`
.. include:: /includes/note-enabletestcommands.rst

.. example::
Output
------

The :dbcommand:`_hashBSONElement` command returns a document
consisting of the following fields:

.. data:: _hashBSONElement.key

The original BSON element.

.. data:: _hashBSONElement.seed

The seed used for the hash, defaults to ``0``.

.. data:: _hashBSONElement.out

The decimal result of the hash.

.. data:: _hashBSONElement.ok

Holds the ``1`` if the function returns successfully, and ``0`` if
the operation encountered an error.

Example
-------

.. code-block:: sh
Invoke a :program:`mongod` instance with test commands enabled:

mongod --setParameter=enableTestCommands=1
.. code-block:: sh

.. example::
mongod --setParameter enableTestCommands=1

Hash an ISODate string:
Run the following to compute the hash of an ISODate string:

.. code-block:: javascript
.. code-block:: javascript

db.runCommand({_hashBSONElement: ISODate("2013-02-12T22:12:57.211Z")})
db.runCommand({_hashBSONElement: ISODate("2013-02-12T22:12:57.211Z")})

Which returns the following document:
The command returns the following document:

.. code-block:: javascript
.. code-block:: javascript

{
"key" : ISODate("2013-02-12T22:12:57.211Z"),
"seed" : 0,
"out" : NumberLong("-4185544074338741873"),
"ok" : 1
}
{
"key" : ISODate("2013-02-12T22:12:57.211Z"),
"seed" : 0,
"out" : NumberLong("-4185544074338741873"),
"ok" : 1
}

Hash the same ISODate string but specify a seed value:
Run the following to hash the same ISODate string but this time to
specify a seed value:

.. code-block:: javascript
.. code-block:: javascript

db.runCommand({_hashBSONElement: ISODate("2013-02-12T22:12:57.211Z"), seed:2013})
db.runCommand({_hashBSONElement: ISODate("2013-02-12T22:12:57.211Z"), seed:2013})

Which returns the following document:
The command returns the following document:

.. code-block:: javascript
.. code-block:: javascript

{
"key" : ISODate("2013-02-12T22:12:57.211Z"),
"seed" : 2013,
"out" : NumberLong("7845924651247493302"),
"ok" : 1
}
{
"key" : ISODate("2013-02-12T22:12:57.211Z"),
"seed" : 2013,
"out" : NumberLong("7845924651247493302"),
"ok" : 1
}
71 changes: 71 additions & 0 deletions source/reference/command/moveChunk-field.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
object:
name: moveChunk
type: command
field:
optional: false
type: field
name: moveChunk
type: string
position: 1
description: |
The :term:`namespace` of the :term:`collection` where the
:term:`chunk` exists. Specify the collection's full namespace,
including the database name.
---
object:
name: moveChunk
type: command
field:
optional: false
type: field
name: find
type: document
position: 2
description: |
An equality match on the shard key that specifies the shard-key value
of the chunk to move. Specify either the ``bounds`` field or the
``find`` field but not both.
---
object:
name: moveChunk
type: command
field:
optional: false
type: field
name: bounds
type: array
position: 3
description: |
The bounds of a specific chunk to move. The array must consist of two
documents that specify the lower and upper shard key values of a chunk
to move. Specify either the ``bounds`` field or the ``find`` field but
not both. Use ``bounds`` to move chunks in collections partitioned
using a :term:`hashed shard key`.
---
object:
name: moveChunk
type: command
field:
optional: false
type: field
name: to
type: string
position: 4
description: |
The name of the destination shard for the chunk.
---
object:
name: moveChunk
type: command
field:
optional: true
type: field
name: _secondaryThrottle
type: Boolean
position: 5
description: |
When this is set to the default value of ``true``, the balancer waits
for replication to :term:`secondaries <secondary>` while copying and
deleting data during migrations. For details, see
:ref:`sharded-cluster-config-secondary-throttle`.
...
96 changes: 34 additions & 62 deletions source/reference/command/moveChunk.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,85 +4,57 @@ moveChunk

.. default-domain:: mongodb

Definition
----------

.. dbcommand:: moveChunk

:dbcommand:`moveChunk` is an internal administrative command that
moves :term:`chunks <chunk>` between :term:`shards <shard>`. You
must issue the :dbcommand:`moveChunk` command via a
:program:`mongos` instance while using the :term:`admin database`
in the following form:
Internal administrative command. Moves :term:`chunks <chunk>` between
:term:`shards <shard>`. Issue the :dbcommand:`moveChunk` command via
a :program:`mongos` instance while using the :term:`admin database`.
Use the following form:

.. code-block:: javascript

db.runCommand( { moveChunk : <namespace> ,
find : <query> ,
to : <destination>,
<options> } )

: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 that specifies an equality match on the shard key
that will move the chunk that contains the specified shard-key
value.

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 ``bounds`` to move chunks in collections partitioned using
a :term:`hashed shard key`.

:param string to:
find|bounds : <query|array> ,
to : <string>,
_secondaryThrottle : <Boolean> } )

The name of the destination shard for the chunk.

:param boolean _secondaryThrottle:
The :dbcommand:`moveChunk` command has the following fields:

Optional; ``true`` by default. When ``true``, the
balancer waits for replication to :term:`secondaries
<secondary>` while copying and deleting data during
migrations. For details, see
:ref:`sharded-cluster-config-secondary-throttle`.
.. include:: /reference/command/moveChunk-field.rst

The :ref:`chunk migration <sharding-chunk-migration>` section
describes how chunks move between shards on MongoDB.

:dbcommand:`moveChunk` returns the following message if another
metadata operation is in progress :data:`~config.chunks` collection:
.. seealso:: :dbcommand:`split`, :method:`sh.moveChunk()`,
:method:`sh.splitAt()`, and :method:`sh.splitFind()`.

.. code-block:: none
Return Messages
---------------

errmsg: "The collection's metadata lock is already taken."
:dbcommand:`moveChunk` returns the following message if another
metadata operation is in progress :data:`~config.chunks` collection:

If another process, such as a balancer process, changes meta data
while :dbcommand:`moveChunk` is running, you may see this
error. You may retry the :dbcommand:`moveChunk` operation without
side effects.
.. code-block:: none

.. note::
errmsg: "The collection's metadata lock is already taken."

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.
In most cases allow the balancer to create and balance chunks
in sharded clusters.
See
:ref:`sharding-administration-create-chunks` for more information.
If another process, such as a balancer process, changes meta data
while :dbcommand:`moveChunk` is running, you may see this
error. You may retry the :dbcommand:`moveChunk` operation without
side effects.

.. admin-only
.. note::

.. seealso:: :dbcommand:`split`, :method:`sh.moveChunk()`,
:method:`sh.splitAt()`, and :method:`sh.splitFind()`.
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.
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
Loading