A newer version of this documentation is available.

View Latest

Compaction API

Compaction is used to reclaim disk space and reduce disk fragmentation.

Description

Couchbase Server writes all data that you append, update and delete as files on disk. This can eventually lead to gaps in the data file, particularly when you delete data. Be aware the server also writes index files in a sequential format based on appending new results in the index. You can reclaim the empty gaps in all data files by performing a process called compaction. For both data files and index files, perform frequent compaction of the files on disk to help reclaim disk space and reduce disk fragmentation.

Table 1. Compaction endpoints
HTTP method URI path Description Admin Role

POST

/pools/default/buckets/[bucket_name]/ \ controller/compactBucket

Compacts bucket data and indexes.

Full, Cluster,

POST

/pools/default/buckets/[bucket_name]/ \ controller/cancelBucketCompaction

Cancels compaction for the specified bucket.

Full, Cluster

POST

/[bucket_name]/_design/[ddoc_name]/ \ _spatial/_compact

Compacts a spatial view.

Full, Cluster

Auto-compaction description

Auto-compaction parameters are configured to trigger data and view compaction. These parameters can be specified for an entire cluster (cluster-wide) or for a specific bucket in a cluster.

Administrative credentials are required to change these settings.
Table 2. Auto-compaction endpoints
HTTP method URI path Description Admin Role

POST

/controller/setAutoCompaction

Sets cluster-wide auto-compaction intervals and thresholds

Full, Cluster

GET

/settings/autoCompaction

Retrieves cluster-wide settings for auto-compaction

Full, Cluster

GET

/pools/default/buckets/[bucket_name]

Retrieves auto-compaction settings for named bucket

Full, Cluster, Bucket*, BucketA

POST

/pools/default/buckets/[bucket_name]

Sets auto-compaction interval or thresholds for named bucket

Full, Cluster, Bucket*, BucketA

"Bucket A" represents a bucket administrator for a single bucket, and Bucket* a bucket administrator with privileges for all buckets in the cluster.
Table 3. Auto-compaction parameters
Parameter Value Notes

databaseFragmentationThreshold: percentage

Integer between 2 and 100

Percentage disk fragmentation for data

databaseFragmentationThreshold: size

Integer greater than 1

Bytes of disk fragmentation for data

viewFragmentationThreshold: percentage

Integer between 2 and 100

Percentage disk fragmentation for index

viewFragmentationThreshold: size

Integer greater than 1

Bytes of disk fragmentation for index

parallelDBAndViewCompaction

True or false.

Run index and data compaction in parallel. Global setting only.

allowedTimePeriod: abortOutside

True or false

Terminate compaction if the process takes longer than the allowed time

allowedTimePeriod: fromHour

Integer between 0 and 23

Compaction can occur from this hour onward

allowedTimePeriod: fromMinute

Integer between 0 and 59

Compaction can occur from this minute onward

allowedTimePeriod: toHour

Integer between 0 and 23

Compaction can occur up to this hour

allowedTimePeriod: toMinute

Integer between 0 and 59

Compaction can occur up to this minute

purgeInterval

Integer between 1 and 60

Number of days a item is deleted or expired. The key and metadata for that item is purged by auto-compaction

The purge interval parameter removes the key and metadata for items that have been deleted or are expired. This is known as tombstone purging.