Skip to content

Commit 4190cb6

Browse files
kay-kimkay-kim
committed
DOCS-281 Redirect Compact Command page
1 parent 8950a13 commit 4190cb6

File tree

1 file changed

+139
-45
lines changed

1 file changed

+139
-45
lines changed

‎source/reference/command/compact.txt‎

Lines changed: 139 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -6,52 +6,146 @@ compact
66

77
.. dbcommand:: compact
88

9+
.. versionadded:: 2.0
10+
911
The :dbcommand:`compact` command rewrites and defragments a single
10-
collection. Additionally, the command forces all indexes on the collection
11-
to be rebuilt. The command has the following syntax:
12+
collection. Additionally, the command drops all indexes at the
13+
beginning of compaction and rebuilds the indexes at the end.
14+
:dbcommand:`compact` is conceptually similar to
15+
:dbcommand:`repairDatabase`, but works on a single collection rather
16+
than an entire database.
17+
18+
The command has the following syntax:
1219

1320
.. code-block:: javascript
1421

15-
{ compact: "users" }
16-
17-
This command compacts the collection named ``users``. Note the
18-
following command behaviors:
19-
20-
- During a :dbcommand:`compact`, the database blocks all other activity.
21-
22-
- In a :term:`replica set`, :dbcommand:`compact` will refuse to run on the
23-
primary node unless you also specify ``{ force: true }``.
24-
For example:
25-
26-
.. code-block:: javascript
27-
28-
{ compact: "collection", force: true }
29-
30-
- If you have journaling enabled, your data will be safe even
31-
if you kill the operation or restart the server before it has
32-
finished. However, you may have to manually rebuild the indexes.
33-
Without journaling enabled, the :dbcommand:`compact` command is much less safe,
34-
and there are no guarantees made about the safety of your data in the
35-
event of a shutdown or a kill.
36-
37-
.. warning::
38-
39-
Always have an up-to-date backup before performing server
40-
maintenance such as the :dbcommand:`compact` operation.
41-
42-
- :dbcommand:`compact` requires a small amount of additional disk space while
43-
running but unlike :dbcommand:`repairDatabase` it does *not* free
44-
space equal to the total size of the collection.
45-
46-
- the :dbcommand:`compact` command blocks until the operation is
47-
complete.
48-
49-
- :dbcommand:`compact` removes any :term:`padding factor` in the collection,
50-
which may impact performance if documents grow regularly.
51-
52-
- :dbcommand:`compact` commands do not replicate. They must be run on slaves
53-
and replica set members independently.
54-
55-
- It is not possible to compact :term:`capped collections <capped collection>`
56-
because they don't have padding, and documents
57-
cannot grow in these collections.
22+
{ compact: <collection name> }
23+
24+
You may also specify one of the following options:
25+
26+
- ``force: true``
27+
28+
To run on the primary node in a :term:`replica set`. Otherwise,
29+
the :dbcommand:`compact` command returns an error when invoked on
30+
a :term:`replica set` primary because the command blocks all other
31+
activity.
32+
33+
.. versionchanged:: 2.2 :dbcommand:`compact` blocks activities only
34+
for its database.
35+
36+
- ``paddingFactor: <factor>``
37+
38+
To specify a :term:`padding factor` ranging from 1.0 to 4.0 for
39+
the compacted documents. Default factor is 1.0, specifying no
40+
padding and the maximum padding factor is 4.0. If you do updates
41+
that increase the size of the documents, you will want some
42+
padding, especially if you have several indexes for the collection.
43+
44+
.. versionadded:: v2.2
45+
46+
- ``paddingBytes: <bytes>``
47+
48+
To specify a padding as an absolute number of bytes. Specifying
49+
``paddingBytes`` can be useful if your documents start small but
50+
then increase in size significantly. For example,if your documents
51+
are initially 40 bytes long and you grow them by 1KB, using
52+
``paddingBytes: 1024`` might be reasonable since using
53+
``paddingFactor: 4.0`` would only add 40 * (4.0 - 1) = 120 bytes
54+
of padding.
55+
56+
.. versionadded:: v2.2
57+
58+
It is recommended that you always add at least 100 bytes of padding,
59+
and at least 10% of the doc size.
60+
61+
.. code-block:: javascript
62+
63+
db.runCommand ( { compact: 'collection name', paddingBytes: 100, paddingFactor: 1.1 } )
64+
65+
.. warning::
66+
67+
Always have an up-to-date backup before performing server
68+
maintenance such as the :dbcommand:`compact` operation.
69+
70+
Note the following command behaviors:
71+
72+
- :dbcommand:`compact` blocks all other activity (in v2.2, blocks
73+
activities only for its database.) You may view the intermediate
74+
progress either by viewing the the :program:`mongod` log file, or
75+
by running the :method:`db.currentOp()` in another shell instance.
76+
77+
- :dbcommand:`compact` removes any :term:`padding factor` in the
78+
collection if the command is run without either the
79+
``paddingFactor`` option or the ``paddingByte`` option. This may
80+
impact performance if the documents grow regularly. However, the
81+
existing paddingFactor statistics is kept for the collection and
82+
will be used for future inserts.
83+
84+
- :dbcommand:`compact` generally uses less disk space than
85+
:dbcommand:`repairDatabase` and is faster. However,the
86+
:dbcommand:`compact` command is still slow and does block database
87+
activities, so you should run the command during scheduled
88+
maintenance.
89+
90+
- If you kill the operation by running the :method:`db.killOp(opid) <db.killOP()>` or
91+
restart the server before it has finished:
92+
93+
+ If you have journaling enabled, your data will
94+
be safe. However, you may have to manually rebuild the indexes.
95+
96+
+ If you do not have journaling enabled, the :dbcommand:`compact`
97+
command is much less safe, and there are no guarantees made about
98+
the safety of your data in the event of a shutdown or a kill.
99+
100+
+ In either case, much of the existing free space in the
101+
collection may become un-reusable. In this scenario, you should
102+
rerun the compaction to completion to restore the use of this free
103+
space.
104+
105+
- :dbcommand:`compact` may increase the total size and number of our
106+
data files, expecially when run for the first time. However, this
107+
will not increase the total colletion storage space since storage
108+
size is the amount of data allocated within the database files,
109+
and not the size/number of the files on the file system.
110+
111+
- :dbcommand:`compact` requires a small amount of additional disk
112+
space while running but unlike :dbcommand:`repairDatabase` it does
113+
*not* free space on the file system.
114+
115+
- You may also wish to run the :dbcommand:`collstats` command before and
116+
after compaction to see how the storage space changes for the
117+
collection.
118+
119+
- :dbcommand:`compact` commands do not replicate. When running
120+
compact on a :term:`replica set`:
121+
122+
+ Compact each member separately.
123+
124+
+ Ideally, compaction runs on a secondary. (See option
125+
``force:true`` above for information regarding compacting the
126+
primary.)
127+
128+
+ If :dbcommand:`compact` runs on a secondary, the secondary will
129+
go into "recovering" state automatically to prevent reads from
130+
being routed to it during compation. Once the compaction is
131+
finished, it will automatically return to secondary state.
132+
133+
You may refer to the "`partial script for automating step down
134+
and compaction
135+
<https://github.com/mongodb/mongo-snippets/blob/master/js/compact
136+
-example.js>`_") for an example.
137+
138+
- :dbcommand:`compact` is a command issued to a :program:`mongod`.
139+
In a sharded environment, run :dbcommand:`compact` on each shard
140+
separately as a maintenance operation. (This will likely change in
141+
the future with other enhancements.)
142+
143+
- It is not possible to compact :term:`capped collections <capped
144+
collection>` because they don't have padding, and documents cannot
145+
grow in these collections. However, the documents of a
146+
:term:`capped collections <capped collection>` are not subject o
147+
fragmentation.
148+
149+
.. seealso::
150+
151+
:dbcommand:`repairDatabase`

0 commit comments

Comments
 (0)