From 93decd9b11534c5f41d2f2e4d98bd066d1e65ba5 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 18 Sep 2012 10:12:53 -0400 Subject: [PATCH 1/4] DOCS-524 explain paddingFactor equation --- source/reference/command/compact.txt | 41 ++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index 792ddd77a7d..9f6e2dc0b90 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -39,20 +39,37 @@ compact .. versionadded:: v2.2 - *Default:* ``1.0`` + *Default:* ``1.0`` specifies no padding *Possible values:* ``1.0`` to ``4.0`` - If you do updates that 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. To set the padding factor to ``1.1`` on a - collection named ````, use the following operation: + The ``paddingFactor`` describes the record size (i.e. the sum of + the document size and the padding) allocated for each document as + a factor of the document size. 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:: javascript - + + 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%`` 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 (i.e. padding size of ``10%``): + + .. code-block:: javascript + db.runCommand ( { compact: '', paddingFactor: 1.1 } ) - + - ``paddingBytes: `` .. versionadded:: 2.2 @@ -62,11 +79,13 @@ compact 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 only add 120 bytes (i.e. ``40 * (4.0 - 1)``) - of padding. + ``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). With the following command, you can use the ``paddingBytes`` - option for the :dbcommand:`compact` command to set the padding + option of the :dbcommand:`compact` command to set the padding size to ``100`` bytes on the collection named by ````: From 277a5787861710c33574aeff2d5d440bf87bcad2 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 18 Sep 2012 10:34:40 -0400 Subject: [PATCH 2/4] DOCS-534: edits and style updating --- source/reference/command/compact.txt | 159 ++++++++++++++------------- 1 file changed, 81 insertions(+), 78 deletions(-) diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index 9f6e2dc0b90..5e3553dfe5a 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -7,70 +7,72 @@ compact .. 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. - + The command has the following syntax: .. code-block:: javascript { compact: } - + You may also specify one of the following options: - .. TODO use the :option: syntax for these. + .. TODO use the :option: syntax for these. - - ``force: true`` + - ``force: true`` .. versionchanged:: 2.2 :dbcommand:`compact` blocks activities only for its database. - + To run 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. - + - ``paddingFactor: `` .. versionadded:: v2.2 - - *Default:* ``1.0`` specifies no padding - - *Possible values:* ``1.0`` to ``4.0`` - - The ``paddingFactor`` describes the record size (i.e. the sum of - the document size and the padding) allocated for each document as - a factor of the document size. 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. - + + *Default:* ``1.0`` + + *Minimum:* ``1.0`` (no padding.) + + *Maximum:* ``4.0`` + + The ``paddingFactor`` describes the :term:`record size` allocated + for each document as a factor of the document size. 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:: javascript - + 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%`` of the document size. - + 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 (i.e. padding size of ``10%``): - + to ``1.1`` of the document size, or a padding factor of 10 + percent (10%): + .. code-block:: javascript - + db.runCommand ( { compact: '', paddingFactor: 1.1 } ) - - ``paddingBytes: `` + - ``paddingBytes: `` .. versionadded:: 2.2 @@ -88,47 +90,51 @@ compact option of the :dbcommand:`compact` command to set the padding size to ``100`` bytes on the collection named by ````: - + .. code-block:: javascript - + db.runCommand ( { compact: '', paddingBytes: 100 } ) .. warning:: Always have an up-to-date backup before performing server - maintenance such as the :dbcommand:`compact` operation. + maintenance such as the :dbcommand:`compact` operation. Note the following behaviors: - - :dbcommand:`compact` blocks all other activity (in v2.2, blocks - activities only for its database.) You may view the intermediate - progress either by viewing the the :program:`mongod` log file, or - by running the :method:`db.currentOp()` in another shell instance. - + - :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 the + :program:`mongod` log file, or by running the + :method:`db.currentOp()` in another shell instance. + - :dbcommand:`compact` removes any :term:`padding factor` in the collection when issued without either the ``paddingFactor`` option or the ``paddingBytes`` option. This may impact performance if the documents grow regularly. However, - :dbcommand:`compact` retains + :dbcommand:`compact` retains existing paddingFactor statistics for the collection that MongoDB will use to calculate the padding factor for future inserts. - + - :dbcommand:`compact` generally uses less disk space than :dbcommand:`repairDatabase` and is faster. However,the - :dbcommand:`compact` command is still slow and does block database - activities, so you should run the command during scheduled - maintenance. - - - If you kill the operation by running the :method:`db.killOp(opid) ` or - restart the server before it has finished: - - - If you have journaling enabled, your data will - be safe. However, you may have to manually rebuild the indexes. - - - If you do not have journaling enabled, the :dbcommand:`compact` - command is much less safe, and there are no guarantees made about - the safety of your data in the event of a shutdown or a kill. - + :dbcommand:`compact` command is still slow and does block other + database use. Only use :dbcommand:`compact` during scheduled + maintenance periods. + + - If you terminate the operation with the + :method:`db.killOp() ` method or restart the + server before it has finished: + + - 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's + 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 @@ -139,38 +145,37 @@ compact will not increase the total colletion 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` requires a small amount of additional disk space while running but unlike :dbcommand:`repairDatabase` it does - *not* free space on the file system. - + *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. When running - compact on a :term:`replica set`: - - - Compact each member separately. - - - Ideally, compaction runs on a secondary. (See option + + - :dbcommand:`compact` commands do not replicate to secondaries in + a :term:`replica set`: + + - Compact each member separately. + + - Ideally, compaction runs on a secondary. See option ``force:true`` above for information regarding compacting the - primary.) - - - If :dbcommand:`compact` runs on a secondary, the secondary will - enter a "recovering" state to prevent clients from directing - treads to it during compaction. Once the compaction - finishes the secondary will automatically return to secondary state. - + primary. + + - If you run :dbcommand:`compact` on a secondary, the secondary + will enter a "recovering" state to prevent clients from + directing treads to it during compaction. Once the compaction + finishes the secondary will automatically return to secondary + state. + You may refer to the "`partial script for automating step down - and compaction - `_") for an example. - + and compaction `_") + for an example. + - :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. (This will likely change in - the future with other enhancements.) + separately as a maintenance operation. - It is not possible to compact :term:`capped collections ` because they don't have padding, and documents cannot @@ -178,6 +183,4 @@ compact :term:`capped collections ` are not subject o fragmentation. - .. seealso:: - - :dbcommand:`repairDatabase` + .. seealso:: :dbcommand:`repairDatabase` From 6020e67032497c7cc7794d850b680fb7bc1d6ec2 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 18 Sep 2012 15:41:21 -0400 Subject: [PATCH 3/4] DOCS-524 compact method equation use option directives --- source/reference/command/compact.txt | 99 ++++++++++++++-------------- source/reference/glossary.txt | 3 + 2 files changed, 51 insertions(+), 51 deletions(-) diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index 5e3553dfe5a..4bba520d052 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -21,79 +21,76 @@ compact { compact: } - You may also specify one of the following options: + You may also specify the following options: - .. TODO use the :option: syntax for these. + .. option:: force: true - - ``force: true`` - - .. versionchanged:: 2.2 :dbcommand:`compact` blocks activities only + .. versionchanged:: 2.2 :dbcommand:`compact` blocks activities only for its database. - To run 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. + To run 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. - - ``paddingFactor: `` + .. option:: paddingFactor: - .. versionadded:: v2.2 + .. versionadded:: v2.2 - *Default:* ``1.0`` + *Default:* ``1.0`` - *Minimum:* ``1.0`` (no padding.) + *Minimum:* ``1.0`` (no padding.) - *Maximum:* ``4.0`` + *Maximum:* ``4.0`` - The ``paddingFactor`` describes the :term:`record size` allocated - for each document as a factor of the document size. 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. + The ``paddingFactor`` describes the :term:`record size` allocated + for each document as a factor of the document size. 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``: + 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:: javascript + .. code-block:: javascript - padding size = (paddingFactor - 1) * . + 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. + 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%): + 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 + .. code-block:: javascript - db.runCommand ( { compact: '', paddingFactor: 1.1 } ) + db.runCommand ( { compact: '', paddingFactor: 1.1 } ) - - ``paddingBytes: `` + .. option:: paddingBytes: - .. versionadded:: 2.2 + .. versionadded:: 2.2 - To specify a padding as an absolute number of bytes. 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). + To specify a padding as an absolute number of bytes. 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). - 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 - ````: + 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 ````: - .. code-block:: javascript + .. code-block:: javascript - db.runCommand ( { compact: '', paddingBytes: 100 } ) + db.runCommand ( { compact: '', paddingBytes: 100 } ) .. warning:: @@ -123,7 +120,7 @@ compact maintenance periods. - If you terminate the operation with the - :method:`db.killOp() ` method or restart the + :method:`db.killOp() ` method or restart the server before it has finished: - If you have journaling enabled, the data remains consistent and diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 2da7a889d80..da567550ba3 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -351,6 +351,9 @@ Glossary moving a document when it grows as the result of :method:`update` operations. + record size + The space allocated for a document including the padding. + read-lock In the context of a reader-writer lock, a lock that while held allows concurrent readers, but no writers. From da26da0fc4a3922d2b8a5e8f53066e1a80160b08 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 18 Sep 2012 19:56:51 -0400 Subject: [PATCH 4/4] DOC-524 compact document use parameter directives --- source/reference/command/compact.txt | 35 +++++++++++++----------- themes/mongodb/static/mongodb-docs.css_t | 8 +++++- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index 4bba520d052..78b6ae1929c 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -23,17 +23,20 @@ compact You may also specify the following options: - .. option:: force: true + :param force: .. versionchanged:: 2.2 :dbcommand:`compact` blocks activities only for its database. - To run 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. + 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. - .. option:: paddingFactor: + :param paddingFactor: .. versionadded:: v2.2 @@ -70,19 +73,19 @@ compact db.runCommand ( { compact: '', paddingFactor: 1.1 } ) - .. option:: paddingBytes: + :param paddingBytes: .. versionadded:: 2.2 - To specify a padding as an absolute number of bytes. 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). + The ``paddingBytes`` sets the padding as an absolute number + of bytes. 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). With the following command, you can use the ``paddingBytes`` option of the :dbcommand:`compact` command to set the padding diff --git a/themes/mongodb/static/mongodb-docs.css_t b/themes/mongodb/static/mongodb-docs.css_t index 506b96422e1..707e1ebc52c 100644 --- a/themes/mongodb/static/mongodb-docs.css_t +++ b/themes/mongodb/static/mongodb-docs.css_t @@ -110,7 +110,7 @@ div.sphinxsidebar h3 a { div.sphinxsidebar p { color: #333333; margin: 12px 0 5px 12px; - padding: 0 12p; + padding: 0 12px; } div.sphinxsidebar form { @@ -305,6 +305,12 @@ table.docutils td { padding: 1px 8px 1em 5px; } +table.docutils.field-list ul.first.last.simple>li { + padding-top: 1em; +} +table.docutils.field-list ul.first.last.simple>li>p { + padding-top: 1em; +} /* for main page to knock out the bullets & padding for main columns */ div#mongodb ul{