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

Record Padding

Update operations can increase the size of the document [1]. If a document outgrows its current allocated record space, MongoDB must allocate a new space and move the document to this new location.

To reduce the number of moves, MongoDB includes a small amount of extra space, or padding, when allocating the record space. This padding reduces the likelihood that a slight increase in document size will cause the document to exceed its allocated record size.

[1]Documents in MongoDB can grow up to the full maximum BSON document size.

Padding Factor

To minimize document movements and their impact, MongoDB employs padding. MongoDB adaptively adjusts the size of record allocations in a collection by adding a paddingFactor so that the documents have room to grow. The paddingFactor indicates the padding for new inserts and moves.

To check the current paddingFactor on a collection, you can run the db.collection.stats() operation in the mongo shell, as in the following example:


Since MongoDB writes each document at a different point in time, the padding for each document will not be the same. You can calculate the padding size by subtracting 1 from the paddingFactor, for example:

padding size = (paddingFactor - 1) * <document size>.

For example, a paddingFactor of 1.0 specifies no padding whereas a paddingFactor of 1.5 specifies a padding size of 0.5 or 50 percent (50%) of the document size.

Because the paddingFactor is relative to the size of each document, you cannot calculate the exact amount of padding for a collection based on the average document size and padding factor.

If an update operation causes the document to decrease in size, for instance if you perform an $unset or a $pop update, the document remains in place and effectively has more padding. If the document remains this size, the space is not reclaimed until you perform a compact or a repairDatabase operation.

Operations That Remove Padding

The following operations remove padding: compact, repairDatabase, and initial replica sync operations. However, with the compact command, you can run the command with a paddingFactor or a paddingBytes parameter. See compact command for details.

Padding is also removed if you use mongoexport a collection. If you use mongoimport into a new collection, mongoimport will not add padding. If you use mongoimport with an existing collection with padding, mongoimport will not affect the existing padding.

When a database operation removes padding from a collection, subsequent updates to the collection that increase the record size will have reduced throughput until the collection’s padding factor grows. However, the collection will require less storage.

Record Allocation Strategies

New in version 2.2: collMod and usePowerOf2Sizes.

To more efficiently reuse the space freed as a result of deletions or document relocations, you can specify that MongoDB allocates record sizes in powers of 2. To do so, use the collMod command with the usePowerOf2Sizes flag. See collMod command for more details. As with all padding, power of 2 size allocations minimizes, but does not eliminate, document movements.

See also Can I manually pad documents to prevent moves during updates?