Navigation
This version of the documentation is archived and no longer supported.

compact

compact

New in version 2.0.

The 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. compact is conceptually similar to repairDatabase, but works on a single collection rather than an entire database.

The command has the following syntax:

{ compact: <collection name> }

You may also specify the following options:

Parameters:
  • force

    Changed in version 2.2: compact blocks activities only for the database it is compacting.

    The force specifies whether the compact command can run on the primary node in a replica set. Set to true to run the compact command on the primary node in a replica set. Otherwise, the compact command returns an error when invoked on a replica set primary because the command blocks all other activity.

  • paddingFactor

    New in version 2.2.

    Default: 1.0

    Minimum: 1.0 (no padding.)

    Maximum: 4.0

    The paddingFactor describes the record size allocated for each document as a factor of the document size, for all records compacted during the compact operation. paddingFactor does not affect the padding of subsequent record allocations after compact completes.

    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:

    padding size = (paddingFactor - 1) * <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 compact command to set the record size to 1.1 of the document size, or a padding factor of 10 percent (10%):

    db.runCommand ( { compact: '<collection>', paddingFactor: 1.1 } )
    

    compact compacts existing documents, but does not reset paddingFactor statistics for the collection. After the compact MongoDB will use the existing paddingFactor when allocating new records for documents in this collection.

  • paddingBytes

    New in version 2.2.

    The paddingBytes sets the padding as an absolute number of bytes, for all records compacted during the compact operation. After running compact, paddingBytes does not affect the padding of subsequent record allocations.

    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 compact command to set the padding size to 100 bytes on the collection named by <collection>:

    db.runCommand ( { compact: '<collection>', paddingBytes: 100 } )
    

Warning

Always have an up-to-date backup before performing server maintenance such as the compact operation.

Note the following behaviors:

  • compact blocks all other activity. In MongoDB 2.2, compact blocks activities only for its database. You may view the intermediate progress either by viewing the mongod log file, or by running the db.currentOp() in another shell instance.

  • compact compacts existing documents in the collection. However, unlike repairDatabase, compact does not reset paddingFactor statistics for the collection. MongoDB will use the existing paddingFactor when allocating new records for documents in this collection.

  • compact generally uses less disk space than repairDatabase and is faster. However,the compact command is still slow and does block other database use. Only use compact during scheduled maintenance periods.

  • If you terminate the operation with the 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 compact operation. You may have to manually rebuild the indexes.
    • If you do not have journaling enabled and the mongod or 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 space.
  • compact may increase the total size and number of our 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.

  • compact requires a small amount of additional disk space while running but unlike repairDatabase it does not free space on the file system.

  • You may also wish to run the collStats command before and after compaction to see how the storage space changes for the collection.

  • compact commands do not replicate to secondaries in a replica set:

    • Compact each member separately.
    • Ideally, compaction runs on a secondary. See option force:true above for information regarding compacting the primary.

    Warning

    If you run 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 state for more information replica set member states. Refer to the “partial script for automating step down and compaction” for an example of this procedure.

  • compact is a command issued to a mongod. In a sharded environment, run compact on each shard separately as a maintenance operation.

    Important

    You cannot issue compact against a mongos instance.

  • It is not possible to compact capped collections because they don’t have padding, and documents cannot grow in these collections. However, the documents of a capped collections are not subject to fragmentation.

  • compact removes extra padding added to collections that have the usePowerOf2Sizes flag set. See SERVER-4018 for more information.

See also

repairDatabase

←   collStats connPoolStats  →