Auto-Compaction: Global
Auto-compaction settings can be established and retrieved for the entire cluster.
Description
The global auto-compaction settings are the default settings used for each newly created bucket. Whenever changes are made to the global settings, these changes apply to all buckets created subsequently. The changes also apply immediately to all existing buckets that were created with the default settings and have continued to use them until this point. Note, however, that once a bucket’s settings are individually modified, the bucket’s settings will no longer be affected by changes to the global settings.
Auto-compaction settings for the cluster can be established and retrieved by the Full Admin and Cluster Admin roles; and can be retrieved 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. For more information, see Storage Settings.
HTTP methods and URIs
Global auto-compaction settings are retrieved and established by the following combinations of HTTP method and URI:
GET /settings/autoCompaction POST /controller/setAutoCompaction
Curl Syntax
curl -u [admin-name]:[password] -X GET http://[cluster-ip-address]:8091/settings/autoCompaction curl -u Administrator:password -X POST 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=[ full | 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 retrieved by the GET
method, are as follows:
Function | Description |
---|---|
|
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. This parameter is for Community Edition only. |
|
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. This parameter is for Community Edition only. |
|
Integer between 0 and 23 inclusive, specifying the concluding hour of the time-period during which circular index compaction, if specified, can run. This parameter is for Community Edition only. |
|
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. This parameter is for Community Edition only. |
|
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 global auto-compaction settings that does not include the parallelDBAndViewCompaction
parameter fails with 400 Bad Request
and returns an object that includes the following key-value pair: {"parallelDBAndViewCompaction":"parallelDBAndViewCompaction is missing"}
.
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 auto-compaction settings, globally.
Retrieving Global Auto-Compaction Settings
The following command retrieves the global auto-compaction settings. Note that the output is piped to the jq command, to optimize readability.
curl -X GET http://10.143.193.101:8091/settings/autoCompaction \ -u Administrator:password | jq
If successful, the command returns output similar to the following:
{ "autoCompactionSettings": { "parallelDBAndViewCompaction": false, "allowedTimePeriod": { "fromHour": 1, "toHour": 2, "fromMinute": 30, "toMinute": 30, "abortOutside": true }, "databaseFragmentationThreshold": { "percentage": 50, "size": 52428800 }, "viewFragmentationThreshold": { "percentage": 70, "size": 52428800 }, "indexCompactionMode": "circular", "indexCircularCompaction": { "daysOfWeek": "Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday", "interval": { "fromHour": 0, "toHour": 0, "fromMinute": 0, "toMinute": 0, "abortOutside": false } }, "indexFragmentationThreshold": { "percentage": 30 } }, "purgeInterval": 30 }
Establishing Global Auto-Compaction Settings
The following command provides values for all the global auto-compaction parameters.
curl -i -X POST http://10.143.192.101:8091/controller/setAutoCompaction \ -u Administrator:password \ -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 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.