Auto-Compaction: Per Bucket
Auto-compaction settings can be established and retrieved for individual buckets.
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
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 -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 |
---|---|
|
Boolean specifying whether the auto-compaction settings for the specified bucket can be modified.
If |
|
Integer specifying the database fragmentation percentage that is the point at which compaction is triggered. |
|
Integer specifying the megabytes of database fragmentation that is the point at which compaction is triggered. |
|
Integer specifying the view fragmentation percentage that is the point at which compaction is triggered. |
|
Integer specifying the megabytes of view fragmentation that is the point at which compaction is triggered. |
|
Integer between 0 and 23 inclusive, specifying the starting hour of the time-period during which compaction can run. |
|
Integer between 0 and 59 inclusive, specifying the starting minute (within the specified starting hour) of the time-period during which compaction can run. |
|
Integer between 0 and 23 inclusive, specifying the concluding hour of the time-period during which compaction can run. |
|
Integer between 0 and 59 inclusive, specifying the concluding minute (within the specified concluding hour) of the time-period during which compaction can run. |
|
Either |
|
Either |
|
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. |
|
The compaction mode for indexes.
Can be either |
|
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: |
|
Integer between 0 and 23 inclusive, specifying the starting hour of the time-period during which circular index compaction, if specified, can run. |
|
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. |
|
Integer between 0 and 23 inclusive, specifying the concluding hour of the time-period during which circular index compaction, if specified, can run. |
|
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. |
|
Either |
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 thepurgeInterval
at its current value. -
An invalid parameter-specification may result in the value being established as
"undefined"
. For example, specifying-d allowedTimePeriod[toMinut3e]=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
The following examples show how to retrieve and establish 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 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.
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
The Couchbase CLI allows auto-compaction to be managed by means of the setting-compaction command. For information on managing auto-compaction with Couchbase Web Console, see Auto-Compaction.