DOCSP-34846 autoCompact Reference Page (#6361)

Author: ajhuh-mdb

source/includes/fact-freeSpaceTargetMB.rst

@@ -0,0 +1,2 @@
+Optional. Specifies the minimum amount of storage space, in megabytes, that must 
+be recoverable for compaction to proceed. 

source/reference/built-in-roles.txt

@@ -595,6 +595,7 @@ Cluster Administration Roles
 
       - :authaction:`applicationMessage`
       - :authaction:`closeAllDatabases`
+      - :authaction:`compact` (New in version 7.3)
       - :authaction:`connPoolSync`
       - :authaction:`flushRouterConfig`
       - :authaction:`fsync`

source/reference/command/autoCompact.txt

@@ -0,0 +1,150 @@
+===========
+autoCompact
+===========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. dbcommand:: autoCompact
+
+   .. versionadded:: 8.0
+
+   Enables or disables background :ref:`compaction <compact>`. 
+   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 :dbcommand:`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:
+
+.. code-block:: javascript
+
+   db.runCommand(
+      { 
+        autoCompact: <boolean>, 
+        freeSpaceTargetMB: <int>, // Optional 
+        runOnce: <boolean>, // Optional
+      }
+   )
+
+Compatibility
+-------------
+
+This command is available in deployments hosted in the following environments: 
+
+.. include:: /includes/fact-environments-atlas-only.rst
+
+.. include:: /includes/fact-environments-atlas-support-no-free.rst
+
+.. include:: /includes/fact-environments-onprem-only.rst
+
+Command Fields
+--------------
+
+The command can take the following optional fields:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - Field
+     - Type
+     - Description
+
+   * - ``freeSpaceTargetMB`` 
+     - Integer 
+     - .. versionadded: 7.3
+
+       .. include:: /includes/fact-freeSpaceTargetMB.rst
+
+       *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.
+
+.. _autocompact-authentication:
+
+Required Privileges
+-------------------
+
+For clusters enforcing :ref:`authentication <authentication>`,
+you must authenticate as a user with the :authaction:`compact` privilege
+action on the target collection. The :authrole:`dbAdmin` and 
+:authrole:`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 :ref:`blocking behavior 
+<compact-blocking>` as the :dbcommand:`compact` command.
+
+Excluded Collections 
+~~~~~~~~~~~~~~~~~~~~
+
+If an :term:`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 :binary:`~bin.mongod` instances. In a
+sharded environment, run ``autoCompact`` on each shard separately.
+
+You cannot run ``autoCompact`` against a :binary:`~bin.mongos` instance.
+
+Learn More 
+----------
+
+- :dbcommand:`compact`

source/reference/command/compact.txt

@@ -17,9 +17,7 @@ Definition
 
 .. dbcommand:: compact
 
-   Rewrites and defragments all data and indexes in a collection. On
-   :ref:`WiredTiger <storage-wiredtiger>` databases, this command
-   releases unneeded disk space to the operating system.
+   Attempts to release unneeded disk space to the operating system.
 
 Syntax
 ------
@@ -69,10 +67,7 @@ The command takes the following fields:
      - Integer 
      - .. versionadded: 7.3 
 
-       Optional. Specifies the minimum amount of storage space, in megabytes, 
-       that must be recoverable for compaction to proceed. Compaction proceeds 
-       only if the amount of free storage space available is greater than 
-       ``freeSpaceTargetMB``.
+       .. include:: /includes/fact-freeSpaceTargetMB.rst
 
        *Default:* 20
 
@@ -92,9 +87,9 @@ The command takes the following fields:
 
 For clusters enforcing :ref:`authentication <authentication>`,
 you must authenticate as a user with the :authaction:`compact` privilege
-action on the target collection. The :authrole:`dbAdmin` role provides 
-the required privileges for running ``compact`` against
-non-system collections. 
+action on the target collection. The :authrole:`dbAdmin` and 
+:authrole:`hostManager` roles provide the required privileges for running 
+``compact`` against non-system collections. 
 
 For :ref:`system collections <metadata-system-collections>`, you must: 
 
@@ -127,8 +122,8 @@ collection:
 For more information on configuring the ``resource`` document, see 
 :ref:`resource-document`.
 
-To add the :authrole:`dbAdmin` or the custom role to an existing
-user, use :method:`db.grantRolesToUser` or :method:`db.updateUser()`.
+To add the :authrole:`dbAdmin`, :authrole:`hostManager`, or the custom role to 
+an existing user, use :method:`db.grantRolesToUser` or :method:`db.updateUser()`.
 The following operation grants the custom ``compact`` role to the 
 ``myCompactUser`` on the ``admin`` database:
 
@@ -157,6 +152,8 @@ specify the role to the ``roles`` array of the
 Behavior
 --------
 
+.. _compact-blocking:
+
 Blocking
 ~~~~~~~~
 
@@ -333,3 +330,8 @@ Running ``compact`` returns output similar to the following:
    :copyable: false
 
    { bytesFreed: 27859, ok: 1 }
+
+Learn More 
+----------
+
+- :dbcommand:`autoCompact`

source/reference/command/nav-administration.txt

@@ -20,6 +20,12 @@ Administration Commands
 
      - Description
 
+   * - :dbcommand:`autoCompact`
+
+     - Enables background compaction.
+
+       .. versionadded:: 8.0
+        
    * - :dbcommand:`bulkWrite`
 
      - Performs many insert, update, and delete operations on multiple
@@ -37,7 +43,7 @@ Administration Commands
 
    * - :dbcommand:`compact`
 
-     - Defragments a collection and rebuilds the indexes.
+     - Attempts to release unneeded disk space to the operating system.
 
    * - :dbcommand:`convertToCapped`
 
@@ -182,6 +188,7 @@ Administration Commands
    :titlesonly:
    :hidden:
 
+   /reference/command/autoCompact
    /reference/command/bulkWrite
    /reference/command/cloneCollectionAsCapped
    /reference/command/collMod

source/reference/privilege-actions.txt

@@ -599,8 +599,8 @@ Server Administration Actions
 
 .. authaction:: compact
 
-   User can perform the :dbcommand:`compact` command. Apply this action to
-   database or collection resources.
+   User can perform the :dbcommand:`compact` command and :dbcommand:`autoCompact` 
+   commands. Apply this action to database or collection resources.
 
 .. authaction:: compactStructuredEncryptionData
 

source/release-notes/8.0.txt

@@ -17,6 +17,14 @@ Release Notes for MongoDB 8.0 (Release Candidate)
 General Changes
 ---------------
 
+Background Compaction 
+~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 8.0, you can use the new :dbcommand:`autoCompact` command 
+to perform background compaction. If enabled, the server attempts to keep free 
+space within each collection and index below the specified the 
+``freeSpaceTargetMB`` value.
+
 New Bulk Write Command
 ~~~~~~~~~~~~~~~~~~~~~~