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

Function	Description
`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 `full` or `circular`. This parameter is for Community Edition only.
`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. This parameter is for Community Edition only.
`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. This parameter is for Community Edition only.
`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. This parameter is for Community Edition only.
`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. This parameter is for Community Edition only.
`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. This parameter is for Community Edition only.
`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. This parameter is for Community Edition only.

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 full or circular. This parameter is for Community Edition only.

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. This parameter is for Community Edition only.

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. This parameter is for Community Edition only.

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. This parameter is for Community Edition only.

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. This parameter is for Community Edition only.

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. This parameter is for Community Edition only.

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. This parameter is for Community Edition only.

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 the purgeInterval 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.