--- title: "Auto-Compaction: Per Bucket" description: Auto-compaction settings can be established and retrieved for individual buckets. pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-server/edit/release/7.6/modules/rest-api/pages/rest-autocompact-per-bucket.adoc xref: xref:7.6@server:rest-api:rest-autocompact-per-bucket.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/7.6/rest-api/rest-autocompact-per-bucket.html) # Auto-Compaction: Per Bucket > Auto-compaction settings can be established and retrieved for individual buckets. ## [](#description)Description Auto-compaction settings can be modified for an existing bucket. Once this has occurred, the bucket's auto-compaction settings will no longer be affected by changes to the global auto-compaction settings. Auto-compaction settings for a specific bucket can be established and retrieved by the _Full Admin_ and _Cluster Admin_ roles. Auto-compaction settings for a specific bucket can be retrieved by a _Bucket Admin_ role that applies to that bucket; and by the _Read-Only Admin_ role. Auto-compaction settings for _GSI Indexes_ are provided; however, these are for use with Couchbase Server Community Edition only. These settings are not needed for the indexes used by Enterprise Edition: if these settings are established, they are ignored by nodes running Enterprise Edition. ## [](#http-methods-and-uris)HTTP methods and URIs Per bucket auto-compaction settings are retrieved and established by the following combinations of HTTP method and URI: GET /pools/default/buckets/[bucket-name] POST /pools/default/buckets/[bucket-name] ## [](#curl-syntax)Curl Syntax curl -X GET -u Administrator:password http://[cluster-ip-address]:8091/pools/default/buckets/[bucket-name] curl -X POST -u Administrator:password http://[cluster-ip-address]:8091/controller/setAutoCompaction -d databaseFragmentationThreshold[percentage]=[percentage] -d databaseFragmentationThreshold[size]=[size] -d viewFragmentationThreshold[percentage]=[percentage] -d viewFragmentationThreshold[size]=[size] -d allowedTimePeriod[fromHour]=[integer] -d allowedTimePeriod[fromMinute]=[integer] -d allowedTimePeriod[toHour]=[integer] -d allowedTimePeriod[toMinute]=[integer] -d allowedTimePeriod[abortOutside]=[ true | false ] -d parallelDBAndViewCompaction=[ true | false ] -d purgeInterval=[numberofdays] -d indexCompactionMode=[ standard | circular ] -d indexCircularCompaction[daysOfWeek]=[daynames-comma-separated] -d indexCircularCompaction[interval][fromHour]=[integer] -d indexCircularCompaction[interval][fromMinute]=[integer] -d indexCircularCompaction[interval][toHour]=[integer] -d indexCircularCompaction[interval][toMinute]=[integer] -d indexCircularCompaction[interval][abortOutside]=[ true | false ] The parameters, which can be specified by the `POST` method and (unless otherwise specified) retrieved by the `GET` method, are as follows: | Function | Description | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | autoCompactionDefined | Boolean specifying whether the auto-compaction settings for the specified bucket can be modified. If true, the settings _can_ be modified; if false, they _cannot_ be modified. Note that this parameter _must_ be specified as true, for per-bucket auto-compaction settings to be modified. If the parameter is _not_ specified as true, the call completes without error — but no modifications occur, and no further errors are reported. This parameter cannot be retrieved with the GET method. | | databaseFragmentationThreshold\[percentage\] | Integer specifying the database fragmentation percentage that is the point at which compaction is triggered. | | databaseFragmentationThreshold\[size\] | Integer specifying the megabytes of database fragmentation that is the point at which compaction is triggered. | | viewFragmentationThreshold\[percentage\] | Integer specifying the view fragmentation percentage that is the point at which compaction is triggered. | | viewFragmentationThreshold\[size\] | Integer specifying the megabytes of view fragmentation that is the point at which compaction is triggered. | | allowedTimePeriod\[fromHour\] | Integer between 0 and 23 inclusive, specifying the starting hour of the time-period during which compaction can run. | | allowedTimePeriod\[fromMinute\] | Integer between 0 and 59 inclusive, specifying the starting minute (within the specified starting hour) of the time-period during which compaction can run. | | allowedTimePeriod\[toHour\] | Integer between 0 and 23 inclusive, specifying the concluding hour of the time-period during which compaction can run. | | allowedTimePeriod\[toMinute\] | Integer between 0 and 59 inclusive, specifying the concluding minute (within the specified concluding hour) of the time-period during which compaction can run. | | allowedTimePeriod\[abortOutside\] | Either true or false, indicating respectively that compaction _should_ or _should not_ be aborted, if its running extends beyond the specified time of conclusion. | | parallelDBAndViewCompaction | Either true or false, indicating respectively that compaction of databases and views _should_ or _should not_ run in parallel. This parameter _must_ be specified. | | purgeInterval | The frequency with which the _tombstone purge_ is run, specified as either an integer or a decimal number. If a decimal is specified, the fractional part is rounded at fifteen places. The default value is 3.0; the minimum 0.04; the maximum 60. | | indexCompactionMode | The compaction mode for indexes. Can be either standard or circular. | | indexCircularCompaction\[daysOfWeek\] | The days of the week on which circular compaction (if specified) is to run. Individual values must be day-names, each specified with an initial capital, and otherwise lower-case: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. Multiple values must be separated by a single comma, with no spaces. | | indexCircularCompaction\[interval\]\[fromHour\] | Integer between 0 and 23 inclusive, specifying the starting hour of the time-period during which circular index compaction, if specified, can run. | | indexCircularCompaction\[interval\]\[fromMinute\] | Integer between 0 and 59 inclusive, specifying the starting minute of the time-period, within the specified starting hour, during which circular index compaction, if specified, can run. | | indexCircularCompaction\[interval\]\[toHour\] | Integer between 0 and 23 inclusive, specifying the concluding hour of the time-period during which circular index compaction, if specified, can run. | | indexCircularCompaction\[interval\]\[toMinute\] | Integer between 0 and 59 inclusive, specifying the concluding minute of the time-period, within the specified concluding hour, during which circular index compaction, if specified, can run. | | indexCircularCompaction\[interval\]\[abortOutside\] | Either true or false, indicating respectively that circular index compaction, if specified, _should_ or _should not_ be aborted, if its running extends beyond the specified time of conclusion. | ## [](#responses)Responses If the call is successful, `200 OK` is given. A malformed URI gives `404 Object Not Found`. Failure to authenticate gives `401 Unauthorized`. An attempt to establish per-bucket auto-compaction settings that does not include the `parallelDBAndViewCompaction` parameter fails with `400 Bad Request` and an object that includes the following key-value pair: `{"parallelDBAndViewCompaction":"parallelDBAndViewCompaction is missing"}`. An attempt to establish per-bucket auto-compaction settings that does not include a `true` setting for the `autoCompactionDefined` parameter does _not_ fail, but does not establish _any_ modified settings, and does not report any further errors. If, when auto-compaction settings are being established, one or more individual parameter-values are incorrectly specified, `400 Bad Request` is returned, and an object containing error messages is displayed. For example, attempting to assign `allowedTimePeriod[toHour]` the value `24` returns `"allowedTimePeriod[toHour]":"to hour is too large. Allowed range is 0 - 23"`. Index-fragmentation parameters, which apply only to Couchbase Server Community Edition, are ignored if established for a cluster consisting of Enterprise Edition-based nodes. If one or more individual parameter-names are incorrectly specified: * The call may nevertheless succeed, returning `200 OK`. The values assigned to validly specified parameters will be applied. * An invalid parameter-name and its assigned value may be ignored. For example, specifying `-d purgeIntervalg=11` leaves the `purgeInterval` at its current value. * An invalid parameter-specification may result in the value being established as `"undefined"`. For example, specifying `-d allowedTimePeriod[toMinute]=10` results in a setting such as the following: "allowedTimePeriod": { "fromHour": 7, "toHour": 12, "fromMinute": 7, "toMinute": "undefined", "abortOutside": true }, Failure to establish settings correctly is likely to generate errors; and may have further, unpredictable consequences. ## [](#examples)Examples The following examples show how to retrieve and establish per-bucket auto-compaction settings. ### [](#retrieving-per-bucket-auto-compaction-settings)Retrieving Per-Bucket Auto-Compaction Settings The following command retrieves the per-bucket auto-compaction settings for the `travel-sample` bucket. Note that the output is piped to the [jq](https://stedolan.github.io/jq/) command, to optimize readability. curl -X GET -u Administrator:password http://10.143.193.101:8091/pools/default/buckets/travel-sample | jq If successful, the command returns statistics on all aspects of the bucket. The opening section of the output appears as follows: { "name": "travel-sample", "nodeLocator": "vbucket", "uuid": "dbca445dfc82a0f68c98485b2166853b", "uri": "/pools/default/buckets/travel-sample?bucket_uuid=dbca445dfc82a0f68c98485b2166853b", "streamingUri": "/pools/default/bucketsStreaming/travel-sample?bucket_uuid=dbca445dfc82a0f68c98485b2166853b", "bucketCapabilitiesVer": "", "bucketCapabilities": [ "collections", "durableWrite", "tombstonedUserXAttrs", "couchapi", "subdoc.ReplaceBodyWithXattr", "subdoc.DocumentMacroSupport", "dcp", "cbhello", "touch", "cccp", "xdcrCheckpointing", "nodesExt", "xattr" ], "collectionsManifestUid": "1", "ddocs": { "uri": "/pools/default/buckets/travel-sample/ddocs" }, "vBucketServerMap": { "hashAlgorithm": "CRC", "numReplicas": 1, "serverList": [ "127.0.0.1:11210" ], . . . The section of the output that applies to auto-compaction appears as follows: "autoCompactionSettings": { "parallelDBAndViewCompaction": false, "allowedTimePeriod": { "fromHour": 0, "toHour": 6, "fromMinute": 0, "toMinute": 0, "abortOutside": true }, "databaseFragmentationThreshold": { "percentage": 30, "size": 1073741824 }, "viewFragmentationThreshold": { "percentage": 30, "size": 1073741824 } }, . . . For more information on this command, including an extended representation of its output, see [Getting Single Bucket Information](rest-buckets-summary.md). ### [](#establishing-per-bucket-auto-compaction-settings)Establishing Per-Bucket Auto-Compaction Settings The following command establishes the per-bucket auto-compaction settings for the `travel-sample` bucket curl -i -X POST http://10.143.193.101:8091/pools/default/buckets/travel-sample \ -u Administrator:password \ -d autoCompactionDefined=true \ -d databaseFragmentationThreshold[percentage]=30 \ -d databaseFragmentationThreshold[size]=1073741824 \ -d viewFragmentationThreshold[percentage]=30 \ -d viewFragmentationThreshold[size]=1073741824 \ -d allowedTimePeriod[fromHour]=0 \ -d allowedTimePeriod[fromMinute]=0 \ -d allowedTimePeriod[toHour]=6 \ -d allowedTimePeriod[toMinute]=0 \ -d allowedTimePeriod[abortOutside]=true \ -d parallelDBAndViewCompaction=false \ -d purgeInterval=3.0 \ -d indexCompactionMode=circular \ -d indexCircularCompaction[daysOfWeek]=Monday,Wednesday,Friday \ -d indexCircularCompaction[interval][fromHour]=6 \ -d indexCircularCompaction[interval][fromMinute]=0 \ -d indexCircularCompaction[interval][toHour]=9 \ -d indexCircularCompaction[interval][toMinute]=0 \ -d indexCircularCompaction[interval][abortOutside]=true This example establishes fragmentation thresholds and sizes for database and view, and specifies the time-period during which compaction should occur. It specifies that compaction be aborted if it should overrun this time-period. Parallel compaction for database and view is switched _off_. The tombstone purge interval is set to 3 days; and _circular_ standard compaction is specified for particular days and hours. ## [](#see-also)See Also The Couchbase CLI allows auto-compaction to be managed by means of the [setting-compaction](../cli/cbcli/couchbase-cli-setting-compaction.md) command. For information on managing auto-compaction with Couchbase Web Console, see [Auto-Compaction](../manage/manage-settings/configure-compact-settings.md).