Docs Menu

Docs Home → Develop Applications → MongoDB Manual

autoCompact

On this page

  • Definition
  • Syntax
  • Compatibility
  • Command Fields
  • Required Privileges
  • Behavior
  • Learn More

Definition

autoCompact

New in version 8.0.

Enables or disables background compaction. When enabled, autoCompact periodically iterates through all available files and continuously runs compaction if there is enough free storage space available.

Before you enable autoCompact, run the dbStats command to see if you have enough available storage space for compaction to proceed. If the amount of available space returned by dbStats is less than freeSpaceTargetMB, background compaction has no effect.

Syntax

The command has the following syntax:

db.runCommand(
   {
     autoCompact: <boolean>,
     freeSpaceTargetMB: <int>, // Optional
     runOnce: <boolean>, // Optional
   }
)

Compatibility

This command is available in deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

This command is not supported in M0, M2, and M5 clusters. For more information, see Unsupported Commands.

Command Fields

The command can take the following optional fields:

Field
Type
Description
freeSpaceTargetMB
Integer

Optional. Specifies the minimum amount of storage space, in megabytes, that must be recoverable for compaction to proceed.

Default: 20

runOnce
boolean

Optional. If runOnce is set to true, background compaction runs only once through every collection on the node.

If runOnce is set to false, background compaction runs continuously on all collections in the database. If a collection fails to compact while runOnce is false, MongoDB temporarily skips that collection and continues compacting the remaining collections. MongoDB attempts to compact the failed collection again after approximately one day.

Warning

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

Required Privileges

For clusters enforcing authentication, you must authenticate as a user with the compact privilege action on the target collection. The dbAdmin and hostManager roles provide the required privileges for running autoCompact against all collections.

Behavior

Blocking

Although the autoCompact command itself doesn't block any reads and writes, background compaction applies the same blocking behavior as the compact command.

Excluded Collections

If an oplog exists, MongoDB excludes it from background compaction.

Performance Considerations

We recommend running autoCompact during periods of low traffic. If you run background compaction in parallel with other operations, it can negatively impact performance.

Replica Sets

You can run background compaction on collections and indexes that are stored in a replica set. However, note the following considerations:

  • The primary node does not replicate the autoCompact command to the secondary nodes.

  • A secondary node can replicate data while background compaction is running.

  • Reads and writes are permitted while background compaction is running.

Sharded Clusters

autoCompact only applies to mongod instances. In a sharded environment, run autoCompact on each shard separately.

You cannot run autoCompact against a mongos instance.

Learn More

← Administration Commands
bulkWrite →

On this page