Creating and Editing Buckets
Buckets can be created, and their configurations subsequently edited, with the REST API.
Description
These respectively create a new bucket and edit an existing bucket. The bucket can be of any type: Couchbase, Ephemeral, or Memcached. (Note, however that Memcached buckets are now deprecated.)
On creation, a bucket must be assigned a name that is unique among buckets defined on the cluster: this name cannot subsequently be changed. Names cannot be longer than 100 bytes (which is to say, characters).
A maximum of 30 buckets can be created on a single cluster.
Administrators with either the Full Admin or the Cluster Admin role can create buckets and edit their configurations. Bucket configurations can also be edited by administrators with the Bucket Admin role, provided that its privileges have been extended either to all buckets on the cluster, or to the specific bucket whose configuration is to be edited. See Roles, for information on roles and privileges.
Curl Syntax
Note that floats and integers referred to in the following syntax-display are non-negative only.
curl -X POST -u <administrator>:<password>
http://<ip-address-or-hostname>:<port>/pools/default/buckets
-d name=<bucketName>
-d bucketType=[ couchbase | ephemeral | memcached ]
-d ramQuota=<integer>
-d storageBackend=[ couchstore | magma ]
-d evictionPolicy=[
[ valueOnly | fullEviction ] |
[ noEviction | nruEviction ]
]
-d durabilityMinLevel=[
[ none | majority | majorityAndPersistActive | persistToMajority ] |
[ none | majority ]
]
-d threadsNumber=[ 3 | 8 ]
-d rank=<integer>
-d replicaNumber=[ 1 | 2 | 3 ]
-d compressionMode=[ off | passive | active ]
-d maxTTL=<integer>
-d replicaIndex=[ 0 | 1 ]
-d conflictResolutionType=[ seqno | lww ]
-d flushEnabled=[ 0 | 1 ]
-d magmaSeqTreeDataBlockSize=<integer>
-d historyRetentionCollectionDefault=[ true | false ]
-d historyRetentionBytes=<integer>
-d historyRetentionSeconds=<integer>
-d autoCompactionDefined=[ true | false ]
-d parallelDBAndViewCompaction=[ true | false ]
-d databaseFragmentationThreshold[percentage]=<integer>
-d databaseFragmentationThreshold[size]=<integer>
-d viewFragmentationThreshold[percentage]=<integer>
-d viewFragmentationThreshold[size]=<integer>
-d purgeInterval=[ <float> | <integer> ]
-d allowedTimePeriod[fromHour]=<integer>
-d allowedTimePeriod[fromMinute]=<integer>
-d allowedTimePeriod[toHour]=<integer>
-d allowedTimePeriod[toMinute]=<integer>
-d allowedTimePeriod[abortOutside]=[ true | false ]
All parameters are described in the following subsections.
Parameter Groups
Parameters that support the creation and editing of buckets can be considered to form two groups; which are, respectively, General and Auto-compaction.
General
Parameters in the General group include:
-
Parameters that must be specified on bucket creation, these being:
-
Parameters that can be specified on bucket creation, but if not specified, acquire a default value. They include:
-
Parameters that can be edited after bucket creation; these being evictionPolicy, durabilityMinLevel, threadsNumber, rank, replicaNumber, compressionMode, maxTTL, flushEnabled, magmaSeqTreeDataBlockSize, historyRetentionCollectionDefault, historyRetentionBytes, and historyRetentionSeconds.
-
Parameters that cannot be edited after bucket creation; these being bucketType, storageBackend, replicaIndex, and conflictResolutionType.
-
For full details and examples, see General Parameters, below.
Auto-Compaction
All auto-compaction parameters can be edited, following bucket creation.
The Auto-compaction parameter group contains the following: autoCompactionDefined, parallelDBAndViewCompaction, databaseFragmentationThreshold[percentage], databaseFragmentationThreshold[size], viewFragmentationThreshold[percentage], viewFragmentationThreshold[size], purgeInterval, allowedTimePeriod[fromHour], allowedTimePeriod[fromMinute], allowedTimePeriod[toHour], allowedTimePeriod[toMinute], and allowedTimePeriod[abortOutside].
Note that Auto-compaction parameters take effect only if both of the following are true:
-
Auto-compaction is enabled, by means of the autoCompactionDefined parameter.
-
An explicit setting is made to the parallelDBAndViewCompaction parameter.
Note that in Couchbase Server Enterprise Edition, auto-compaction does not apply to memory-optimized index storage, and there are no settings necessary for configuring the auto-compaction of Global Secondary Indexes using standard index storage. For information on storage, see Storage Engines.
For full details and examples, see Auto-Compaction Parameters, below.
General Parameters
The parameters listed in the following subsections are all included in the General group, and therefore apply equally to Couchbase Server Enterprise and Community Editions.
name
A name for a bucket that is to be created.
The name must be unique among the bucket-names defined for the cluster, and cannot be longer than 100 characters.
Acceptable characters are A-Z, a-z, and 0-9.
Additionally, the underscore, period, dash, and percent characters can be used.
The name parameter must be specified, if a bucket is being created.
If it is not, or if the intended name is improperly designed, an error-notification is returned.
For example: : {"name":"Bucket name needs to be specified"}.
Note that a bucket-name cannot be changed after bucket-creation.
Therefore, if this parameter is specified in an attempt to edit the bucket-configuration, it is ignored.
To edit the configuration of an existing bucket, the bucket-name must be specified as the <bucketName> path-parameter; as indicated above, in HTTP Methods and URIs.
Example: Defining a New Name, When Creating
In the following example, a bucket named testBucket is created, with a RAM-size of 256 MiB.
The bucket name is specified by means of the name parameter, with a value of testBucket.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256
If successful, the call returns a 202 Accepted notification, with empty content.
Example: Referencing the Existing Name, When Editing
To edit the bucket, the same endpoint is used, but with the bucket name specified as a concluding path-parameter, as follows:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d ramQuota=512
The value of the ramQuota parameter (described below), is hereby increased to 512 MiB.
bucketType
Specifies the type of the bucket.
This can be couchbase (which is the default), ephemeral, or memcached.
For a detailed explanation of bucket types, see Buckets.
If an invalid bucket type is specified, the error-notification {"bucketType":"invalid bucket type"} is returned.
This parameter cannot be modified, following bucket-creation. If an attempt at modification is made, the parameter is ignored.
Example: Defining a Bucket Type, When Creating
A bucket type can only be specified when the bucket is created: the specified type cannot be changed subsequently.
The following example creates a bucket, named testBucket, whose type is ephemeral:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d bucketType=ephemeral
If successful, the call returns a 202 Accepted notification.
No object is returned.
ramQuota
The amount of memory to be allocated to the bucket, per node, in MiB. The minimum amount is 100 MiB. The maximum amount is the total Data Service memory quota configured per node, minus the amount already assigned to other buckets. For information on per node memory configuration, see the page for General Settings.
A value for ramQuota must be specified: the value can be modified, following bucket-creation.
An incorrect memory-specification returns a notification such as {"ramQuota":"RAM quota cannot be less than 100 MiB"}.
Example: Specifying a Memory Quota, when Creating
The following example creates a Couchbase bucket, named testBucket and assigns it 256 MiB of memory.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256
Note that the bucket is of type couchbase by default.
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a New Memory Quota, when Editing
The following example assigns a new memory quota, of 512 MiB, to the existing bucket testBucket.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d ramQuota=512
If successful, the call returns a 200 OK notification.
No object is returned.
storageBackend
The storage backend to be assigned to and used by the bucket.
This can be either couchstore (which is the default) or magma.
For information, see Storage Engines.
Example: Specifying the Storage Backend
The storage backend can be specified only on bucket-creation.
A minimum of 1024 MiB is required if the magma option is used; a minimum of 100 MiB if the default couchstore is used.
curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \ -u Administrator:password \ -d ramQuota=1024 \ -d storageBackend=magma \ -d name=testBucket
If successful, the call returns a 202 Accepted notification.
No object is returned.
evictionPolicy
The ejection policy to be assigned to and used by the bucket.
(Note that eviction is, in the current release, referred to as ejection; and this revised naming will continue to be used in future releases.)
Policy-assignment depends on bucket type.
For a Couchbase bucket, the policy can be valueOnly (which is the default) or fullEviction.
For an Ephemeral bucket, the policy can be noEviction (which is the default) or nruEviction.
No policy can be assigned to a Memcached bucket.
This value can be modified, following bucket-creation. If such modification occurs, the bucket is restarted with the new setting: this may cause inaccessibility of data, during the bucket’s warm-up period.
Incorrect specification of an ejection policy returns an error-notification, such as {"evictionPolicy":"Eviction policy must be either 'valueOnly' or 'fullEviction' for couchbase buckets"}.
For information on ejection policies, see Bucket Types. For general information on memory management in the context of ejection, see Ejection.
Example: Specifying an Eviction Policy, when Creating
The following example creates a new bucket, named testBucket, which is a Couchbase bucket by default; and assigns it the fullEviction policy.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket -d ramQuota=256 \ -d evictionPolicy=fullEviction
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a New Eviction Policy, when Editing
The following example modifies the eviction policy of the existing bucket testBucket, specifying that it should be valueOnly.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d evictionPolicy=valueOnly
If successful, the call returns a 200 OK notification.
No object is returned.
durabilityMinLevel
A durability level to be assigned to the bucket, as the minimum level at which all writes to the bucket must occur.
Level-assignment depends on bucket type.
For a Couchbase bucket, the level can be none, majority, majorityAndPersistActive, or persistToMajority.
For an Ephemeral bucket, the level can be none or majority.
No level can be assigned to a Memcached bucket.
This parameter can be modified, following bucket-creation.
For information on durability and levels, see Durability.
Example: Specifying a Minimum Durability Level, when Creating
The following example creates a new bucket, named testBucket, which is a Couchbase bucket by default; and assigns it the minimum durability level of majorityAndPersistActive.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d durabilityMinLevel=majorityAndPersistActive
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a New Minimum Durability Level, when Editing
The following example modifies the minimum durability level of the existing bucket testBucket, changing the level to persistToMajority.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d durabilityMinLevel=persistToMajority
If successful, the call returns a 200 OK notification.
No object is returned.
threadsNumber
The priority for the bucket, as described in Create a Bucket.
Priority can be established as either Low or High.
To establish priority as Low (which is the default), the value of threadsNumber must be 3.
To establish priority as High, the value must be 8.
If any other value is used, the value is ignored; and the bucket’s priority remains low.
If this parameter is incorrectly specified, an error-notification such as the following is returned: {"threadsNumber":"The number of threads must be an integer between 2 and 8"}.
(Note that, as indicated above, all values other than 3 and 8 are ignored.)
This parameter can be modified, following bucket-creation. If such modification occurs, the bucket is restarted with the new setting: this may cause inaccessibility of data, during the bucket’s warm-up period.
Example: Specifying a Bucket Priority, when Creating
The following example creates a new bucket, named testBucket, which is a Couchbase bucket by default; and assigns it a High priority, by specifying 8 as the value to the threadsNumber parameter.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d threadsNumber=8
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a New Bucket Priority, when Editing
The following example modifies the priority of the existing bucket testBucket, changing the level to Low, by establishing 3 as the value of the threadsNumber parameter.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d threadsNumber=3
If successful, the call returns a 200 OK notification.
No object is returned.
rank
The rank for the bucket: this determines the bucket’s place in the order in which the rebalance process handles the buckets on the cluster.
The bucket can be either a Couchbase or an Ephemeral bucket.
Rank can be established as an integer, from 0 (the default) to 1000.
The higher a bucket’s assigned integer (in relation to the integers assigned other buckets), the sooner in the rebalance process the bucket is handled.
For example, if on a cluster that hosts multiple buckets, one bucket is assigned a rank of 25 and all others remain with the default assignment of 0, the bucket assigned 25 is handled before any other bucket, when rebalance occurs.
This assignment of rank allows a cluster’s most mission-critical data to be rebalanced with top priority.
Example: Specifying a Bucket’s Rank, when Creating
The following establishes a new bucket named testBucket, and assigns it a rank of 100.
curl -v -X POST http://localhost:8091/pools/default/buckets -u Administrator:password -d name=testBucket -d ramQuota=125 -d rank=100
If the call is successful, 202 Accepted is returned.
Assigned the rank of 100, testBucket will be handled by the rebalance process before any bucket whose assignment is less than 100, and after and bucket whose assignment is greater.
Example: Specifying a Bucket’s Rank, when Editing
The following edits the previously established value of rank for testBucket:
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket / -u Administrator:password / -d rank=200
Success returns 200 OK, and changes the rank of testBucket to 200.
replicaNumber
The number of replicas for the bucket.
For information on replicas and replication, see Intra-Cluster Replication and vBuckets.
The possible values are 0 (which disables replication, and therefore ensures that no replicas will be maintained), 1 (which is the default), 2, and 3.
If a number greater than 3 is specified, the following error-notification is returned: {"replicaNumber":"Replica number larger than 3 is not supported."}.
If more replicas are requested than can be assigned to the cluster, due to an insufficient number of nodes, no notification is returned. Instead, the maximum possible number of replicas is created: additional replicas will be added subsequently, if more nodes become available.
This parameter can be modified, following bucket-creation. Such modification may require a rebalance: for information, see Rebalance.
Example: Specifying a Number of Replicas, when Creating
The following example creates a new bucket, named testBucket, and specifies that it should have 3 replicas.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d replicaNumber=3
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a Modified Number of Replicas, when Editing
The following example changes the replica-number of the existing bucket testBucket, specifying that the number be 2:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d replicaNumber=2
If successful, the call returns a 200 OK notification.
No object is returned.
compressionMode
The compression mode for the bucket.
The possible values are off, passive (which is the default), and active.
If the value is incorrectly specified, the following error-notification is returned: {"compressionMode":"compressionMode can be set to 'off', 'passive' or 'active'"}.
This parameter can be modified, following bucket-creation.
For information on compression and compression modes, see Compression.
Example: Specifying a Compression Mode, when Creating
The following example creates a new bucket, named testBucket, and assigns it the active compression mode:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d compressionMode=active
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a New Compression Mode, when Editing
The following example changes the compression mode of the existing bucket testBucket, specifying that the mode now be off:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d compressionMode=off
If successful, the call returns a 200 OK notification.
No object is returned.
maxTTL
The bucket’s Time To Live (TTL); which imposes a maximum lifespan on items within a bucket, and thus ensures the expiration of such items, once the specified period is complete.
The value must be an integer, which specifies a number of seconds.
The maximum value is MAX32INT (2147483648 seconds, or 68.096 years).
The default value is 0, which disables TTL for the bucket.
Specifying any positive value up to MAX32INT enables TTL for the bucket.
Specifying an incorrect value returns an error-notification such as the following: {"maxTTL":"Max TTL must be an integer between 0 and 2147483647"}.
This parameter can be modified, following bucket-creation.
For information on TTL, see Expiration.
Example: Specifying a Time-to-Live Value, when Creating
The following example creates a new bucket, named testBucket, and assigns it a time-to-live of 500,000 seconds:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d maxTTL=500000
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a New Time-to-Live value, when Editing
The following example modifies the time-to-live setting of the existing bucket testBucket, reducing it to 0, and thereby disabling expiration.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d maxTTL=0
If successful, the call returns a 200 OK notification.
No object is returned.
replicaIndex
Specifies whether View Indexes are to be replicated.
The value can be either 0 (which is the default), specifying that they are not to be replicated; or 1, specifying that they are to be replicated.
Specifying any other value returns an error-notification such as the following: {"replicaIndex":"replicaIndex can only be 1 or 0"}.
This option is valid for Couchbase buckets only. Note that there may be, at most, one replica view index.
This parameter cannot be modified, following bucket-creation.
Example: Specifying View Index Replication, when Creating
View index replication can only be specified when a bucket is created. Attempts to change the value subsequently are ignored.
The following example creates a new bucket, named testBucket, and specifies that View indexes are to be replicated:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d replicaIndex=1
If successful, the call returns a 202 Accepted notification.
No object is returned.
conflictResolutionType
Specifies the conflict resolution type for the bucket.
The value can be seqno (which is the default), specifying sequence-number based resolution; or lww (last write wins), specifying timestamp-based resolution
This parameter cannot be modified, following bucket-creation.
If modification is attempted, the following error-notification is returned: {"conflictResolutionType":"Conflict resolution type not allowed in update bucket"}.
For information on conflict resolution, see: XDCR Conflict Resolution.
Example: Specifying a Conflict Resolution Policy, when Creating
A bucket’s conflict resolution policy can only be specified when the bucket is created: attempts to change the setting subsequently are ignored.
The following example creates a new bucket, named testBucket, specifying the lww conflict resolution policy.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d conflictResolutionType=lww
If successful, the call returns a 202 Accepted notification.
No object is returned.
flushEnabled
Whether flushing is enabled for the bucket.
The value can be either 1, which enables flushing; or 0, which is the default, and disables flushing.
Flushing deletes every document in the bucket, and therefore should not be enabled unless absolutely necessary.
This parameter can be modified, following bucket-creation.
Example: Enable Flushing, when Creating
The following example creates a new bucket, named testBucket, and enables flushing:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d flushEnabled=1
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Modify Flushing Enablement-Status, when Editing
The following example modifies the flushing enablement-status of the existing bucket, testBucket, switching it to disabled, by specifying the value 0 for the parameter flushEnabled:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d flushEnabled=0
If successful, the call returns a 200 OK notification.
No object is returned.
magmaSeqTreeDataBlockSize
The block size, in bytes, for Magma seqIndex blocks.
The minimum block size that can be specified is 4096; and the maximum is 131072.
The default size is 4096.
The larger the specified block size, the better may be the block compression; potentially at the cost of greater consumption of memory, CPU, and I/O bandwidth.
Note that storageBackend must be magma.
This setting cannot be established or retrieved until the entire cluster is running 7.2 or higher.
Example: Set magmaSeqTreeDataBlockSize, when Creating
The following example creates the bucket testBucket, establishing the value of magmaSeqTreeDataBlockSize as 7000.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=1100 \ -d storageBackend=magma \ -d magmaSeqTreeDataBlockSize=7000
If successful, the call returns 202 Accepted.
historyRetentionCollectionDefault
Whether a change history is made for the bucket.
The value can be either true (the default) or false.
If the value is true, the change history records changes made to all collections within the bucket, unless this setting is overridden for one or more individual collections.
(For details on per collection overriding, see Creating and Editing a Collection).
This parameter is ignored unless the value of storageBackend is specified as magma.
This parameter is also ignored unless a positive value is specified for either historyRetentionSeconds or historyRetentionBytes, or both.
For an overview of change history, see Change History.
Example: Disable historyRetentionCollectionDefault, when Creating
The following example creates a bucket, specifies its storage as magma, and specifies that a record of changes made to collections within the bucket should not be made.
curl -X POST http://localhost:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=1100 \ -d storageBackend=magma \ -d historyRetentionCollectionDefault=false
Success returns 202 Accepted.
Example: Modify historyRetentionCollectionDefault, when Editing
The following example modifies the value of historyRetentionCollectionDefault for the existing bucket testBucket.
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d historyRetentionCollectionDefault=true
Success returns 200 OK.
Note, however, that this call only results in a change history being written to disk if storageBackend was specified as magma at bucket-creation, and if a positive value is specified (either prior to or after this call) for either historyRetentionSeconds or historyRetentionBytes, or for both.
historyRetentionBytes
Specifies the maximum size, in bytes, of the change history that is written to disk for all collections in this bucket when the value of historyRetentionCollectionDefault is true.
The minimum size for the change history is 2 GiB (which would be specified as 2147483648).
The maximum is 1.8 PiB (which would be specified as 18446744073709551615).
If a positive integer outside this range is specified, an error is flagged, no file-size is established, and change history remains disabled for the bucket.
Each replica configured for the bucket maintains a copy of the change history. Therefore, if two replicas are configured, and the specified maximum size is 2 GiB, the total size used for the change history across the cluster becomes 6 GiB.
Note that for a change history to be written to disk, a positive value must be specified either for this parameter or for historyRetentionSeconds, or both.
Additionally, storageBackend must be specified as magma.
For an overview of change history, see Change History.
Example: Set historyRetentionBytes, when Creating
The following example creates a bucket, specifies its storage as magma, accepts the default value of true for historyRetentionCollectionDefault, and specifies the maximum disk-size of the change-record as 2 GiB.
Thus, when this size-limit is reached, the oldest key-value pairs in the current record will be successively removed, by means of compaction.
curl -v -X POST http://localhost:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=1100 \ -d storageBackend=magma \ -d historyRetentionBytes=2147483648
Success returns 202 Accepted.
Example: Modify historyRetentionBytes, when Editing
The following example modifies the value of historyRetentionBytes to 4 GiB, for the existing bucket testBucket.
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d historyRetentionBytes=4294967296
Success returns 200 OK.
historyRetentionSeconds
Specifies the maximum number of seconds to be covered by the change history that is written to disk for all collections in this bucket when the value of historyRetentionCollectionDefault is true.
Note that for a change history to be written to disk, a positive value must be specified either for this parameter or for historyRetentionBytes, or both.
For an overview of change history, see Change History.
Example: Set historyRetentionSeconds, when Creating
The following example creates a bucket, specifies its storage as magma, accepts the default value of true for historyRetentionCollectionDefault, and specifies the maximum number of seconds for the change-record as 13,600.
Thus, key-value pairs that have been recorded prior to 13,600 seconds before the current time will be removed, by means of compaction.
curl -v -X POST http://localhost:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=1100 \ -d storageBackend=magma \ -d historyRetentionBytes=13600
Success returns 202 Accepted.
Example: Modify historyRetentionSeconds, when Editing
The following example modifies the number of seconds to be covered by the change history for the existing bucket testBucket to 11,000.
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d historyRetentionSeconds=11000
Success returns 200 OK.
Auto-Compaction Parameters
The parameters listed in the following subsections are all included in the Auto-compaction group
autoCompactionDefined
Specifies whether the default auto-compaction settings are to be modified for this bucket.
The value specified can be either true or false (which is the default).
If the value is false, any parameter-values specified in order to modify the default auto-compaction settings are ignored.
If the value is incorrectly specified, an error-notification such as the following is returned: {"autoCompactionDefined":"autoCompactionDefined is invalid"}.
Note that if autoCompactionDefined is specified as true:
-
All other auto-compaction-related parameters that need to be established should themselves be explicitly specified in the current call.
-
The parameter
parallelDBAndViewCompactionmust be defined. If it is not defined, an error-notification such as the following is returned:{"parallelDBAndViewCompaction":"parallelDBAndViewCompaction is missing"}.
Auto-compaction settings are unnecessary for memory-optimized indexes. For information on index storage, see Storage Settings.
For further information on auto-compaction settings, see Auto-Compaction.
Example: Enabling Auto-Compaction, when Creating
The following example creates a new bucket, named testBucket, and enables auto-compaction for the bucket.
Necessarily, a setting is also explicitly made for parallelDBAndViewCompaction:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d autoCompactionDefined=true \ -d parallelDBAndViewCompaction=false
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Modifying Auto-Compaction Enablement, when Editing
The following example changes the auto-compaction enablement of the existing bucket testBucket, disabling auto-compaction, by specifying the value false to the autoCompactionDefined parameter:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d autoCompactionDefined=false
This disables auto-compaction for the bucket, and removes all auto-compaction-related settings.
If the call is successful, a 200 OK notification is returned, with no object.
To enable auto-compaction after bucket creation, the parallelDBAndViewCompaction parameter must also be specified; as in the following example, which sets parallelDBAndViewCompaction to false:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d autoCompactionDefined=true \ -d parallelDBAndViewCompaction=false
If successful, the call returns a 200 OK notification.
No object is returned.
parallelDBAndViewCompaction
Specifies whether compaction should occur to documents and view indexes in parallel.
This is a global setting, which therefore affects all buckets on the cluster.
The value can either be true or false: one value or the other must be specified.
If the value is incorrectly specified, the following error-notification is returned: {"parallelDBAndViewCompaction":"parallelDBAndViewCompaction is invalid"}.
This parameter-value is ignored if autoCompactionDefined is false (which is its default value).
For examples, see autoCompactionDefined, above.
databaseFragmentationThreshold[percentage]
Specifies, as a percentage, the level of database fragmentation that must be reached for data compaction to be automatically triggered.
The assigned value must be an integer from 0 to 100.
The default value is "undefined".
If a value for databaseFragmentationThreshold[size] is also specified, data compaction is automatically triggered as soon as the threshold specified by one parameter or the other is reached.
If this parameter is incorrectly specified, an error-notification such as the following is returned: "databaseFragmentationThreshold[percentage]":"database fragmentation must be an integer".
This parameter is ignored if autoCompactionDefined is false (which is its default value).
Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating
The following example establishes a value for databaseFragmentationThreshold[percentage], and for all other auto-compaction-related parameters, in its creation of a new bucket, named testBucket:
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \ -u Administrator:password \ -d name=testBucket \ -d ramQuota=256 \ -d autoCompactionDefined=true \ -d parallelDBAndViewCompaction=false \ -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 purgeInterval=3.0
The data fragmentation threshold percentage is hereby specified as 30.
If successful, the call returns a 202 Accepted notification.
No object is returned.
Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing
The following example modifies the databaseFragmentationThreshold[percentage] setting for the existing bucket testBucket; establishing a new value of 47.
Note that although other auto-compaction settings are intended to be unchanged from their previous, explicit settings, all must be respecified correspondingly in the new call: otherwise, all revert to their default values.
curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \ -u Administrator:password \ -d autoCompactionDefined=true \ -d parallelDBAndViewCompaction=false \ -d databaseFragmentationThreshold[percentage]=47 \ -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 purgeInterval=3.0
databaseFragmentationThreshold[size]
Specifies, as a size in MiB, the level of database fragmentation that must be reached for data compaction to be automatically triggered.
The assigned value must be a positive integer.
The default value is "undefined".
If a value for databaseFragmentationThreshold[percentage] is also specified, data compaction is automatically triggered as soon as the threshold specified by one parameter or the other is reached.
If this parameter is incorrectly specified, an error-notification such as the following is returned: "databaseFragmentationThreshold[size]":"database fragmentation must be an integer".
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
viewFragmentationThreshold[percentage]
Specifies, as a percentage, the level of View fragmentation that must be reached for View compaction to be automatically triggered.
The assigned value must be an integer from 0 to 100.
The default value is "undefined".
If a value for viewFragmentationThreshold[size] is also specified, View compaction is automatically triggered as soon as the threshold specified by one parameter or the other is reached.
If this parameter is incorrectly specified, an error-notification such as the following is returned: "viewFragmentationThreshold[percentage]":"view fragmentation must be an integer".
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
viewFragmentationThreshold[size]
Specifies, as a size in MiB, the level of View fragmentation that must be reached for View compaction to be automatically triggered.
The assigned value must be a positive integer.
The default value is "undefined".
If a value for viewFragmentationThreshold[percentage] is also specified, View compaction is automatically triggered as soon as the threshold specified by one parameter or the other is reached.
If this parameter is incorrectly specified, an error-notification such as the following is returned: "viewFragmentationThreshold[size]":"view fragmentation size must be an integer".
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
purgeInterval
Specifies the tombstone (or metadata) purge interval.
The value can be either an integer (indicating a number of days), or a float (indicating an interval that may be greater or less than one day, and entails a number of hours, with 0.04 indicating one hour).
The default value is three days.
If this parameter is incorrectly specified, an error-notification such as the following is returned: {"purgeInterval":"metadata purge interval must be a number"}.
For more information see Tombstone Purge Interval and Storage.
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
allowedTimePeriod[fromHour]
The starting hour of the time-period during which auto-compaction is permitted to run.
The value must be an integer.
The default value is 0.
If the value is incorrectly specified, an error-notification such as either of the following is returned: {"allowedTimePeriod[fromHour]":"from hour must be an integer"} , {"allowedTimePeriod[fromHour]":"from hour is too large. Allowed range is 0 - 59"}..
This parameter is ignored if autoCompactionDefined is false (which is its default value).
allowedTimePeriod[fromMinute]
The starting minute of the time-period during which auto-compaction is permitted to run.
The value must be an integer.
The default value is 0.
If the value is incorrectly specified, an error-notification such as either of the following is returned: {"allowedTimePeriod[fromMinute]":"from minute must be an integer"}, {"allowedTimePeriod[fromMinute]":"from minute is too large. Allowed range is 0 - 59"}.
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
allowedTimePeriod[toHour]
The ending hour of the time-period during which auto-compaction is permitted to run.
The value must be an integer.
The default value is 0.
If the value is incorrectly specified, an error-notification such as either of the following is returned: {"allowedTimePeriod[fromHour]":"to hour must be an integer"}, {"allowedTimePeriod[toHour]":"to hour is too large. Allowed range is 0 - 59"}.
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
allowedTimePeriod[toMinute]
The ending minute of the time-period during which auto-compaction is permitted to run.
The value must be an integer.
The default value is 0.
If the value is incorrectly specified, an error-notification such as either of the following is returned: {"allowedTimePeriod[toMinute]":"to minute must be an integer"}, {"allowedTimePeriod[toMinute]":"to minute is too large. Allowed range is 0 - 59"}.
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
allowedTimePeriod[abortOutside]
Specifies whether compaction can be aborted if the specified time-period is exceeded.
The value must be either true or false (which is the default).
This parameter is ignored if autoCompactionDefined is false (which is its default value).
See the examples provided above, in Example: Specifying a Data Fragmentation Threshold as a Percentage, when Creating and Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing.
Responses
If bucket-creation is successful, HTTP response 202 Accepted is returned, with empty content.
If bucket-editing is successful, HTTP response 200 OK is returned, with empty content.
If the bucket cannot created due to a missing or incorrect parameter, a 400 response is returned, with a JSON payload containing the reason for the error (errors are described per parameter, in the sections above).
If the URL is incorrectly specified a 404 (Object Not Found) error is returned.
Failure to authenticate gives 401 Unauthorized.
See Also
A conceptual description of buckets is provided in Buckets.
Options for managing buckets with Couchbase Web Console are provided in Manage Buckets.
For information on the Couchbase CLI command bucket-create, see the reference page for bucket-create.
Information on memory-management options for Couchbase Server is provided in For information on index storage, see Storage Settings. Information on auto-compaction settings is provided in Auto-Compaction.
For an overview of change history, see Change History. Information on other, Couchbase-Server key concepts can be found as follows: for durability, in Durability; for expiration (time-to-live), in Expiration; for ejection, in Memory; for replication, in Intra-Cluster Replication; for compression, in Compression; for conflict resolution, in XDCR Conflict Resolution; for purging, in Tombstone Purge Interval.
See Roles, for information on roles and privileges.
For information on how to inspect a bucket’s current configuration, see Getting All Bucket Information.