Creating and Editing a Collection
Collections can be created by means of the REST API.
Collections are created by means of the
POST /pools/default/buckets/<bucket_name>/scopes/<scope_name>/collections HTTP method and URI.
Collections are edited by means of the
PATCH /pools/default/buckets/<bucket_name>/scopes/<scope_name>/collections/<collection_name> HTTP method and URI.
POST /pools/default/buckets/<bucket_name>/scopes/<scope_name>/collections PATCH /pools/default/buckets/\ <bucket_name>/scopes/<scope_name>/collections/<collection_name>
The curl syntax is as follows:
curl -X POST -u [admin]:[password] http://<hostname-or-ip>:8091/pools/default/buckets/\ <bucket_name>/scopes/<scope_name>/collections -d name=<collection-name> -d maxTTL=[integer] -d history=[ true | false ] curl -X PATCH -u [admin]:[password] http://<hostname-or-ip>:8091/pools/default/buckets/\ <bucket_name>/scopes/<scope_name>/collections/<collection_name> -d history=[ true | false ]
<bucket_name> path-parameter specifies the name of the bucket within which the new collection is to reside.
<scope_name> path-parameter provides the name of the scope within which the new collection is to reside.
name parameter specifies the name of a collection to be created: this name cannot subsequently be changed.
Used with the
PATCH method, the
<collection_name> path-parameter specifies the name of an existing collection to be edited.
maxTTL flag can be used to specify an expiration value for the collection: the specified value must be an integer representing seconds; with the maximum permissible value being 2147483648 (or 68.096 years).
The default value for
0, which disables TTL for the collection.
For more information, see Expiration.
If the value of the optional
history parameter is:
Not explicitly set by the administrator, the parameter inherits the value of the
historyRetentionCollectionDefaultparameter, used in the creating and editing of buckets.
Explicitly set by the administrator to
false, it potentially overrides, for the current collection, the bucket-wide default established by
If the value of
true, change history is recorded for the collection.
If the value is
false, change history is not recorded.
This parameter is ignored unless the following settings have been made at bucket level:
The value of
A positive value is established for
historyRetentionBytes, or both.
history is the only parameter that can be edited (by means of the
PATCH method), subsequent to the collection’s creation.
200 OK, for each call.
Failure to authenticate gives
A malformed URI fails with
404 Object Not Found.
If the collection-name is improperly specified, a notification such as
"name":"Length must be in range from 1 to 30" or
"name":"Can only contain characters A-Z, a-z, 0-9 and the following symbols _ - %" is displayed.
See Naming for Scopes and Collections, for an account of naming conventions.
The following call creates a collection named
my_collection_in_my_scope, within an existing scope named
my_scope, and specifies an expiration value in seconds that is equivalent to two years.
It also specifies that no change history should be maintained for the collection.
curl -X POST -v -u Administrator:password \ http://10.143.210.101:8091/pools/default/buckets/\ testBucket/scopes/my_scope/collections \ -d name=my_collection_in_my_scope \ -d maxTTL=63113904 \ -d history=false
If successful, the call returns a
uid, such as the following:
The following call modifies the definition of the collection
my_collection_in_my_scope; specifying that deduplication should not be applied to the change history for the collection:
curl -X PATCH http://localhost:8091/pools/default/buckets/testBucket/scopes/my_scope/collections/my_collection_in_my_scope \ -u Administrator:password \ -d history=true
An overview of scopes and collections is provided in Scopes and Collections. Step-by-step procedures for management are provided in Manage Scopes and Collections. See also the CLI reference page for the collection-manage command.