A newer version of this documentation is available.

View Latest

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

      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.

      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.