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

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.

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

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

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.