diff --git a/source/reference/command/addShard-field.yaml b/source/reference/command/addShard-field.yaml new file mode 100644 index 00000000000..fe13994e165 --- /dev/null +++ b/source/reference/command/addShard-field.yaml @@ -0,0 +1,40 @@ +object: + name: addShard + type: dbcommand +field: + optional: false + type: field +name: addShard +type: string +position: 1 +description: | + The hostname and port of the :program:`mongod` instance to be added + as a shard. To add a replica set as a shard, specify the name + of the replica set and the hostname and port of a member of the replica set. +--- +object: + name: addShard + type: dbcommand +field: + optional: true + type: field +name: maxSize +type: integer +position: 2 +description: | + The maximum size in megabytes of the shard. If you set ``maxSize`` + to ``0``, MongoDB does not limit the size of the shard. +--- +object: + name: addShard + type: dbcommand +field: + optional: true + type: field +name: name +type: string +position: 3 +description: | + A name for the shard. If this is not specified, MongoDB + automatically provides a unique name. +... diff --git a/source/reference/command/addShard.txt b/source/reference/command/addShard.txt index ec8afbc1347..c69f59074cb 100644 --- a/source/reference/command/addShard.txt +++ b/source/reference/command/addShard.txt @@ -9,29 +9,29 @@ Definition .. dbcommand:: addShard - The :dbcommand:`addShard` command adds a database instance or - :term:`replica set` to a :term:`sharded cluster`. The optimal - configuration is to deploy shards across replica sets. + Adds either a database instance or a :term:`replica set` to a + :term:`sharded cluster`. The optimal configuration is to deploy + shards across replica sets. - You run this command when connected a :program:`mongos` instance. The - command takes the following form when adding a database instance: + Run this command when connected a :program:`mongos` instance. The + command takes the following form when adding a single database + instance as a shard: .. code-block:: javascript - { addShard: "<:port>", maxSize:, name: "" } + { addShard: "<:port>", maxSize: , name: "" } - The command takes the following form when adding a replica set as a - shard: + When adding a replica set as a shard, use the following form: .. code-block:: javascript - { addShard: "/:", maxSize:, name: "" } + { addShard: "/<:port>", maxSize: , name: "" } The command contains the following fields: - .. include:: /reference/command/addShard-param.rst + .. include:: /reference/command/addShard-field.rst - The :dbcommand:`addShard` command adds stores shard configuration + The :dbcommand:`addShard` command stores shard configuration information in the :term:`config database`. Specify a ``maxSize`` when you have machines with different disk diff --git a/source/reference/command/captrunc-field.yaml b/source/reference/command/captrunc-field.yaml new file mode 100644 index 00000000000..3bddad3a7b8 --- /dev/null +++ b/source/reference/command/captrunc-field.yaml @@ -0,0 +1,33 @@ +object: + name: captrunc + type: dbcommand +field: + optional: false + type: field +name: captrunc +type: string +position: 1 +description: "The name of the collection to truncate." +--- +object: + name: captrunc + type: dbcommand +field: + optional: false + type: field +name: n +type: integer +position: 2 +description: "The number of documents to remove from the collection." +--- +object: + name: captrunc + type: dbcommand +field: + optional: false + type: field +name: inc +type: boolean +position: 3 +description: "Specifies whether to truncate the nth document." +... diff --git a/source/reference/command/captrunc.txt b/source/reference/command/captrunc.txt index bca88cec585..53614671801 100644 --- a/source/reference/command/captrunc.txt +++ b/source/reference/command/captrunc.txt @@ -4,34 +4,41 @@ captrunc .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: captrunc - The :dbcommand:`captrunc` command is an internal command that - truncates capped collections. + Truncates capped collections. - :param string collection: The name of the collection to truncate. + .. |dbcommand| replace:: :dbcommand:`captrunc` + .. include:: /includes/note-enabletestcommands.rst - :param integer n: An integer that specifies the number of documents - to remove from the collection + The command takes the following form: - :param boolean inc: Specifies whether to truncate the ``n``\ th document. + .. code-block:: javascript - .. example:: + { captrunc: "", n: , inc: }. - Truncate 10 older documents from the collection ``records``: + The command contains the following fields: - .. code-block:: javascript + .. include:: /reference/command/captrunc-field.rst - db.runCommand({captrunc: "records" , n:10}) +Examples +-------- - Truncate 100 documents and the 101st document: +The following command truncates 10 older documents from the collection +``records``: - .. code-block:: javascript +.. code-block:: javascript - db.runCommand({captrunc: "records", n:100, inc:true}) + db.runCommand({captrunc: "records" , n:10}) - .. |dbcommand| replace:: :dbcommand:`captrunc` - .. include:: /includes/note-enabletestcommands.rst +The following command truncates 100 documents and the 101st document: + +.. code-block:: javascript + + db.runCommand({captrunc: "records", n:100, inc:true}) - .. write-lock - .. testcommand +.. write-lock +.. testcommand diff --git a/source/reference/command/cloneCollection-field.yaml b/source/reference/command/cloneCollection-field.yaml new file mode 100644 index 00000000000..f4e33d38de3 --- /dev/null +++ b/source/reference/command/cloneCollection-field.yaml @@ -0,0 +1,51 @@ +object: + name: cloneCollection + type: dbcommand +field: + optional: false + type: field +name: cloneCollection +type: string +position: 1 +description: "The name of the collection to clone." +--- +object: + name: cloneCollection + type: dbcommand +field: + optional: false + type: field +name: from +type: string +position: 2 +description: | + Specify a resolvable hostname and optional port number of the remote + server where the specified collection resides." +--- +object: + name: cloneCollection + type: dbcommand +field: + optional: true + type: field +name: query +type: document +position: 3 +description: | + A query that filters the documents in the remote collection that + :dbcommand:`cloneCollection` will copy to the current database. +--- +object: + name: cloneCollection + type: dbcommand +field: + optional: true + type: field +name: copyIndexes +type: boolean +position: 4 +description: | + If set to ``false`` the indexes on the originating server are not + copied with the documents in the collection. This is set to ``true`` + by default. +... \ No newline at end of file diff --git a/source/reference/command/cloneCollection.txt b/source/reference/command/cloneCollection.txt index 503e37e50b9..37fd3e8c68b 100644 --- a/source/reference/command/cloneCollection.txt +++ b/source/reference/command/cloneCollection.txt @@ -4,48 +4,42 @@ cloneCollection .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: cloneCollection - The :dbcommand:`cloneCollection` command copies a collection from a - remote server to the server where you run the - command. :dbcommand:`cloneCollection` does not allow you to clone a - collection through a :program:`mongos`: you must connect directly - to the :program:`mongod` instance. + Copies a collection from a remote server to the server where you run + the command. You cannot clone a collection through a + :program:`mongos` but must connect directly to the :program:`mongod` + instance. + + The command takes the following form: - :param from: + .. code-block:: javascript - Specify a resolvable hostname, and optional port number - of the remote server where the specified collection resides. + { cloneCollection: "", from: "", query: { }, copyIndexes: } - :param query: + The command uses the following fields: - Optional. A query document, in the form of a :term:`document`, - that filters the documents in the remote collection that - :dbcommand:`cloneCollection` will copy to the current - database. See :method:`db.collection.find()`. + .. include:: /reference/command/cloneCollection-field.rst - :param Boolean copyIndexes: +Example +------- - Optional. ``true`` by default. When set to ``false`` the indexes - on the originating server are *not* copied with the documents in - the collection. +.. code-block:: javascript - Consider the following example: + { cloneCollection: "users.profiles", from: "mongodb.example.net:27017", query: { active: true }, copyIndexes: false } - .. code-block:: javascript +This operation copies the ``profiles`` collection from the ``users`` +database on the server at ``mongodb.example.net``. The operation only +copies documents that satisfy the query ``{ active: true }`` and does +not copy indexes. :dbcommand:`cloneCollection` copies indexes by +default, but you can disable this behavior by setting ``{ copyIndexes: +false }``. The ``query`` and ``copyIndexes`` arguments are optional. - { cloneCollection: "users.profiles", from: "mongodb.example.net:27017", query: { active: true }, copyIndexes: false } - - This operation copies the ``profiles`` collection from the - ``users`` database on the server at ``mongodb.example.net``. The operation only - copies documents that satisfy the query ``{ active: true }`` and - does not copy indexes. :dbcommand:`cloneCollection` copies indexes - by default, but you can disable this behavior by setting ``{ - copyIndexes: false }``. The ``query`` and ``copyIndexes`` - arguments are optional. - - :dbcommand:`cloneCollection` creates a collection on the current - database with the same name as the origin collection. If, in the - above example, the ``profiles`` collection already exists in the local - database, then MongoDB appends documents in the remote collection - to the destination collection. +:dbcommand:`cloneCollection` creates a collection on the current +database with the same name as the origin collection. If, in the above +example, the ``profiles`` collection already exists in the local +database, then MongoDB appends documents in the remote collection to the +destination collection. diff --git a/source/reference/command/compact-field.yaml b/source/reference/command/compact-field.yaml new file mode 100644 index 00000000000..040c97eace9 --- /dev/null +++ b/source/reference/command/compact-field.yaml @@ -0,0 +1,62 @@ +object: + name: compact + type: dbcommand +field: + optional: false + type: field +name: compact +type: string +position: 1 +description: "The name of the collection." +--- +object: + name: compact + type: dbcommand +field: + optional: true + type: field +name: force +type: boolean +position: 2 +description: | + If ``true``, :dbcommand:`compact` can run on the + :term:`primary` in a :term:`replica set`. If ``false``, + :dbcommand:`compact` returns an error when run on a + primary, because the command blocks all other activity. + Beginning with version 2.2, :dbcommand:`compact` blocks + activity only for the database it is compacting. +--- +object: + name: compact + type: dbcommand +field: + optional: true + type: field +name: paddingFactor +type: number +position: 3 +description: | + Describes the :term:`record size` allocated for each + document as a factor of the document size for all records + compacted during the :dbcommand:`compact` operation. The + ``paddingFactor`` does not affect the padding of subsequent + record allocations after :dbcommand:`compact` completes. + For more information, see :ref:`compact-paddingFactor`. +--- +object: + name: compact + type: dbcommand +field: + optional: true + type: field +name: paddingBytes +type: integer +position: 4 +description: | + Sets the padding as an absolute number of bytes for all + records compacted during the :dbcommand:`compact` + operation. After :dbcommand:`compact` completes, + ``paddingBytes`` does not affect the padding of subsequent + record allocations. For more information, see + :ref:`compact-paddingBytes`. +... diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index 0b209cc8b6e..5dc30c9a56e 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -6,16 +6,18 @@ compact .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: compact .. versionadded:: 2.0 - The :dbcommand:`compact` command rewrites and defragments a single - collection. Additionally, the command drops all indexes at the - beginning of compaction and rebuilds the indexes at the end. - :dbcommand:`compact` is conceptually similar to - :dbcommand:`repairDatabase`, but works on a single collection rather - than an entire database. + Rewrites and defragments a single + collection. The command drops all indexes at the beginning of + compaction and rebuilds the indexes at the end. :dbcommand:`compact` + is conceptually similar to :dbcommand:`repairDatabase` but works on a + single collection rather than an entire database. The command has the following syntax: @@ -23,194 +25,177 @@ compact { compact: } - You may also specify the following options: + The command uses the following fields: + + .. include:: /reference/command/compact-field.rst + +.. _compact-paddingFactor: + +paddingFactor +~~~~~~~~~~~~~ + +.. versionadded:: 2.2 + +The ``paddingFactor`` field takes the following range of values: + +- Default: ``1.0`` + +- Minimum: ``1.0`` (no padding) + +- Maximum: ``4.0`` + +If your updates increase the size of the documents, padding will +increase the amount of space allocated to each document and avoid +expensive document relocation operations within the data files. + +You can calculate the padding size by subtracting the document size from +the record size or, in terms of the ``paddingFactor``, by subtracting +``1`` from the ``paddingFactor``: + +.. code-block:: none + + padding size = (paddingFactor - 1) * . + +For example, a ``paddingFactor`` of ``1.0`` specifies a padding size of +``0`` whereas a ``paddingFactor`` of ``1.2`` specifies a padding size of +``0.2`` or 20 percent (20%) of the document size. + +With the following command, you can use the ``paddingFactor`` option of +the :dbcommand:`compact` command to set the record size to ``1.1`` of +the document size, or a padding factor of 10 percent (10%): + +.. code-block:: javascript + + db.runCommand ( { compact: '', paddingFactor: 1.1 } ) + +:dbcommand:`compact` compacts existing documents but does not reset +``paddingFactor`` statistics for the collection. After the +:dbcommand:`compact` MongoDB will use the existing ``paddingFactor`` +when allocating new records for documents in this collection. + +.. _compact-paddingBytes: + +paddingBytes +~~~~~~~~~~~~ + +.. versionadded:: 2.2 - :param boolean force: +Specifying ``paddingBytes`` can be useful if your documents start small +but then increase in size significantly. For example, if your documents +are initially 40 bytes long and you grow them by 1KB, using +``paddingBytes: 1024`` might be reasonable since using ``paddingFactor: +4.0`` would specify a record size of 160 bytes (``4.0`` times the +initial document size), which would only provide a padding of 120 bytes +(i.e. record size of 160 bytes minus the document size). - .. versionchanged:: 2.2 - :dbcommand:`compact` blocks activities only for the database - it is compacting. +With the following command, you can use the ``paddingBytes`` option of +the :dbcommand:`compact` command to set the padding size to ``100`` +bytes on the collection named by ````: - The ``force`` specifies whether the :dbcommand:`compact` command - can run on the primary node in a :term:`replica set`. Set to - ``true`` to run the :dbcommand:`compact` command on the primary - node in a :term:`replica set`. Otherwise, the - :dbcommand:`compact` command returns an error when invoked on a - :term:`replica set` primary because the command blocks all other - activity. +.. code-block:: javascript - :param number paddingFactor: + db.runCommand ( { compact: '', paddingBytes: 100 } ) - .. versionadded:: 2.2 +.. warning:: Always have an up-to-date backup before performing server + maintenance such as the :dbcommand:`compact` operation. - *Default:* ``1.0`` +Behaviors +--------- - *Minimum:* ``1.0`` (no padding.) +The :dbcommand:`compact` has the behaviors described here. - *Maximum:* ``4.0`` +Blocking +~~~~~~~~ - The ``paddingFactor`` describes the :term:`record size` - allocated for each document as a factor of the document size, - for all records compacted during the :dbcommand:`compact` - operation. ``paddingFactor`` does not affect the padding of - subsequent record allocations after :dbcommand:`compact` - completes. +In MongoDB 2.2, :dbcommand:`compact` blocks activities only for its +database. Prior to 2.2, the command blocked all activities. - If your updates increase the size of the documents, - padding will increase the amount of space allocated to each - document and avoid expensive document relocation operations - within the data files. +You may view the intermediate progress either by viewing the +:program:`mongod` log file or by running the :method:`db.currentOp()` +in another shell instance. - You can calculate the padding size by subtracting the document - size from the record size or, in terms of the ``paddingFactor``, - by subtracting ``1`` from the ``paddingFactor``: +Operation Termination +~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: none +If you terminate the operation with the :method:`db.killOp() +` method or restart the server before the +:dbcommand:`compact` operation has finished: - padding size = (paddingFactor - 1) * . +- If you have journaling enabled, the data remains consistent and + usable, regardless of the state of the :dbcommand:`compact` operation. + You may have to manually rebuild the indexes. - For example, a ``paddingFactor`` of ``1.0`` specifies a padding - size of ``0`` whereas a ``paddingFactor`` of ``1.2`` specifies a - padding size of ``0.2`` or 20 percent (20%) of the document - size. +- If you do not have journaling enabled and the :program:`mongod` or + :dbcommand:`compact` terminates during the operation, it is impossible + to guarantee that the data is in a consistent state. - With the following command, you can use the ``paddingFactor`` - option of the :dbcommand:`compact` command to set the record - size to ``1.1`` of the document size, or a padding factor of 10 - percent (10%): +- In either case, much of the existing free space in the collection may + become un-reusable. In this scenario, you should rerun the compaction + to completion to restore the use of this free space. - .. code-block:: javascript +Size and Number of Data Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - db.runCommand ( { compact: '', paddingFactor: 1.1 } ) +:dbcommand:`compact` may increase the total size and number of your data +files, especially when run for the first time. However, this will not +increase the total collection storage space since storage size is the +amount of data allocated within the database files, and not the +size/number of the files on the file system. - :dbcommand:`compact` compacts existing documents, but does not - reset ``paddingFactor`` statistics for the collection. After the - :dbcommand:`compact` MongoDB will use the existing - ``paddingFactor`` when allocating new records for documents in - this collection. +Disk Space +~~~~~~~~~~ - :param integer paddingBytes: +:dbcommand:`compact` generally uses less disk space than +:dbcommand:`repairDatabase` and is faster. However, the +:dbcommand:`compact` command is still slow and blocks other database +use. Only use :dbcommand:`compact` during scheduled maintenance periods. - .. versionadded:: 2.2 +:dbcommand:`compact` requires a small amount of additional disk space +while running but unlike :dbcommand:`repairDatabase` it does *not* free +space on the file system. - The ``paddingBytes`` sets the padding as an absolute number of - bytes, for all records compacted during the :dbcommand:`compact` - operation. After running :dbcommand:`compact`, ``paddingBytes`` - does not affect the padding of subsequent record allocations. +To see how the storage space changes for the collection, run the +:dbcommand:`collStats` command before and after compaction. - Specifying ``paddingBytes`` can be useful if your - documents start small but then increase in size - significantly. For example, if your documents are initially - 40 bytes long and you grow them by 1KB, using - ``paddingBytes: 1024`` might be reasonable since using - ``paddingFactor: 4.0`` would specify a record size of 160 - bytes (``4.0`` times the initial document size), which would - only provide a padding of 120 bytes (i.e. record size of - 160 bytes minus the document size). +Replica Sets +~~~~~~~~~~~~ - With the following command, you can use the ``paddingBytes`` - option of the :dbcommand:`compact` command to set the - padding size to ``100`` bytes on the collection named by - ````: +:dbcommand:`compact` commands do not replicate to secondaries in a +:term:`replica set`: - .. code-block:: javascript +- Compact each member separately. - db.runCommand ( { compact: '', paddingBytes: 100 } ) +- Ideally run :dbcommand:`compact` on a secondary. See option + ``force:true`` above for information regarding compacting the primary. - .. warning:: Always have an up-to-date backup before performing - server maintenance such as the :dbcommand:`compact` operation. +.. warning:: - Note the following behaviors: + If you run :dbcommand:`compact` on a secondary, the secondary will + enter a ``RECOVERING`` state to prevent clients from sending read + operations during compaction. Once the operation finishes the + secondary will automatically return to ``SECONDARY`` state. See + :data:`~replSetGetStatus.members.state` for more information about + replica set member states. Refer to the "`partial script for + automating step down and compaction`_" for an example of this + procedure. - - :dbcommand:`compact` blocks all other activity. In MongoDB 2.2, - :dbcommand:`compact` blocks activities only for its database. You - may view the intermediate progress either by viewing the - :program:`mongod` log file, or by running the - :method:`db.currentOp()` in another shell instance. - - - :dbcommand:`compact` compacts existing documents in the - collection. However, unlike :dbcommand:`repairDatabase`, - :dbcommand:`compact` does not reset ``paddingFactor`` statistics - for the collection. MongoDB will use the existing - ``paddingFactor`` when allocating new records for documents in - this collection. +Sharded Clusters +~~~~~~~~~~~~~~~~ - - :dbcommand:`compact` generally uses less disk space than - :dbcommand:`repairDatabase` and is faster. However, the - :dbcommand:`compact` command is still slow and blocks other - database use. Only use :dbcommand:`compact` during scheduled - maintenance periods. +:dbcommand:`compact` is a command issued to a :program:`mongod`. In a +sharded environment, run :dbcommand:`compact` on each shard separately +as a maintenance operation. - - If you terminate the operation with the - :method:`db.killOp() ` method or restart the - server before the :dbcommand:`compact` operation has finished: +.. important:: You cannot issue :dbcommand:`compact` against a + :program:`mongos` instance. - - If you have journaling enabled, the data remains consistent and - usable, regardless of the state of the :dbcommand:`compact` - operation. You may have to manually rebuild the indexes. - - - If you do not have journaling enabled and the :program:`mongod` - or :dbcommand:`compact` terminates during the operation, it is - impossible to guarantee that the data is in a consistent - state. - - - In either case, much of the existing free space in the - collection may become un-reusable. In this scenario, you should - rerun the compaction to completion to restore the use of this free - space. - - - :dbcommand:`compact` may increase the total size and number of your - data files, especially when run for the first time. However, this - will not increase the total collection storage space since storage - size is the amount of data allocated within the database files, - and not the size/number of the files on the file system. +Capped Collections +~~~~~~~~~~~~~~~~~~ - - :dbcommand:`compact` requires a small amount of additional disk - space while running but unlike :dbcommand:`repairDatabase` it does - *not* free space on the file system. - - - You may also wish to run the :dbcommand:`collStats` command before and - after compaction to see how the storage space changes for the - collection. - - - :dbcommand:`compact` commands do not replicate to secondaries in - a :term:`replica set`: - - - Compact each member separately. - - - Ideally run :dbcommand:`compact` on a secondary. See option - ``force:true`` above for information regarding compacting the - primary. - - .. warning:: - - If you run :dbcommand:`compact` on a secondary, the secondary - will enter a ``RECOVERING`` state to prevent clients from - sending read operations during compaction. Once the operation - finishes the secondary will automatically return to - ``SECONDARY`` state. See :data:`~replSetGetStatus.members.state` - for more information about replica set member states. Refer to the - "`partial script for automating step down and compaction`_" - for an example of this procedure. - - - :dbcommand:`compact` is a command issued to a :program:`mongod`. - In a sharded environment, run :dbcommand:`compact` on each shard - separately as a maintenance operation. - - .. important:: You cannot issue :dbcommand:`compact` against a - :program:`mongos` instance. - - - It is not possible to compact :term:`capped collections ` because they don't have padding, and documents cannot - grow in these collections. However, the documents of a - :term:`capped collection` are not subject to - fragmentation. - - - :dbcommand:`compact` removes extra padding added to collections - that have the :collflag:`usePowerOf2Sizes` flag set. See - :issue:`SERVER-4018` for more information. - - .. seealso:: :dbcommand:`repairDatabase` +It is not possible to compact :term:`capped collections ` because they don't have padding, and documents cannot grow +in these collections. However, the documents of a :term:`capped +collection` are not subject to fragmentation. .. _`partial script for automating step down and compaction`: https://github.com/mongodb/mongo-snippets/blob/master/js/compact-example.js