A newer version of this documentation is available.

View Latest

Creating a Collection

  • reference
    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.

    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]
      -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. Optionally, the 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 maxTTL is 0, which disables TTL for the collection. For more information, see Expiration.


    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.


    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:

    curl -X POST -v -u Administrator:password \\
    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:


    See Also

    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.