Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Database Commands
/
Administration

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 Enterprise: The subscription-based, self-managed version of MongoDB

  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Note

This command is currently not supported in MongoDB Atlas clusters.

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.

Required Privileges

For clusters enforcing authentication, you must authenticate as a user with the compact privilege action on the cluster. The hostManager role provides the required privileges for running autoCompact.

Behavior

Blocking

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

Additionally, MongoDB returns an error if you call autoCompact while background compaction is active. If you need to restart autoCompact or run it again with different options, you must first stop the current background compaction operation:

db.runCommand( { autoCompact: false } )

Once the current background compaction is disabled, you can restart autoCompact with the new configuration.

Excluded Collections

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

Performance Considerations

We recommend running autoCompact during periods of low traffic.

Compaction regularly checkpoints the database, which can lead to synchronization overhead. On high-traffic databases, this can potentially delay or prevent operational tasks such as taking backups. To avoid unexpected disruptions, disable compaction before taking a backup.

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

Back

Administration

Next

bulkWrite