Creating a Collection

reference

Collections can be created by means of the REST API.

Description

Collections are created by means of the POST /pools/default/buckets/<bucket_name>/scopes/<scope_name>/collections HTTP method and URI.

HTTP Method and URI

POST /pools/default/buckets/<bucket_name>/scopes/<scope_name>/collections

Curl Syntax

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]

The <bucket-name> path-parameter specifies the name of the bucket within which the new collection is to reside. The <scope-name> path-parameter provides the name of the scope within which the new collection is to reside. The name parameter specifies the name of the collection to be created: this name cannot subsequently be changed. The optional maxTTL parameter is a period of time in seconds. It defaults to 0. When you set maxTTL to value greater than zero (but less than its maximum value of 2147483647), it has the following effects:

It sets a default expiration time for documents you create or mutate in the collection.
It sets the maximum time in seconds a document can exist before it expires. You can explicitly set a document to expire before this time. Attempting to set a document to expire after this time has Couchbase Server set the document to expire in maxTTL seconds.

For more information, see Expiration.

Responses

Success returns 200 OK. Failure to authenticate gives 401 Unauthorized. 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.

Example

The following call creates a collection named my_collection_in_my_scope, within an existing scope named my_scope, and specifies the default expiration for documents in the collection that’s equivalent to two years:

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_1 \
-d maxTTL=63113904

If successful, the call returns a uid, such as the following:

{"uid":18}