A newer version of this documentation is available.

View Latest

Collections Overview

    • Developer Preview
      The Couchbase Enterprise Server 6.5 Developer Preview provides collections and scopes. Only a subset of the planned functionality is included, in order to support early access and experimentation.

      Collections and Scopes

      A collection is a data container, defined on Couchbase Server, within a bucket whose type is either Couchbase or Ephemeral. Up to 1000 collections can be created per cluster. Bucket-items can optionally be assigned to different collections according to content-type. For example, within a bucket that contains travel information, documents that relate specifically to airports might be assigned to an airports collection, while documents that relate to hotels might be assigned to a hotels collection, and so on.


      A scope is a mechanism for the grouping of multiple collections. Up to 100 scopes can be created per bucket. Collection-names must be unique within their scope. Collections might be assigned to different scopes according to content-type, or to deployment-phase (ie, test versus production). Applications can be assigned per-scope access-rights; allowing each application to access only those collections it requires.

      Naming for Scopes and Collections

      User-defined scopes and collections must be assigned user-defined names. Such names:

      • Must be between 1 and 30 characters in length.

      • Can only contain the characters A-Z, a-z, 0-9, and the symbols _, -, and %.

      • Cannot start with _ or %.

      Default Scope and Collection

      In the Developer Preview, every created bucket is automatically given a default scope, and within it, a default collection. Each is named _default. All documents created within the bucket without reference to specific scopes or collections are saved in the default collection, within the default scope. The default scope and collection cannot be dropped.

      Bucket Set-Up

      Scopes and collections exist within buckets. Therefore, to test scopes and collections, at least one bucket must be created. The following options are available for bucket-creation:

      The examples provided in this section use a bucket named testBucket, which is created in turn with the REST API and CLI. Note that the CLI examples demonstrate how to use the cbstats command to return information on collections, including the number of documents each contains. To provide documents to be counted, the cbc create CLI facility is used.


      The following limitations apply to scopes and collections, as made available in Developer Preview mode, in Couchbase Server Enterprise Edition 6.5:

      • Scopes and collections are supported by the Data Service only. This means that key-value data-access can be experimented with.

      • Scopes and collections are not supported by the Index, Query, Search, Eventing, and Analytics Services. This means that data-access by means of these services should not be attempted, using any bucket within which a scope or collection has been explicitly created. Note that these services will provide support for scopes and collections in future.

      • Scopes and collections are not supported by Role-Based Access Control: therefore, access to individual scopes and collections cannot be permitted or denied on a basis of assigned roles. Note that Role-Based Access Control will provide support for scopes and collections in future.

      See also the summary of intentions and limitations provided in Developer Preview Mode and Features.

      Using Other Developer-Preview Features

      The Developer Preview provides, in addition to scopes and collections, features that are part of the Query and Index Services — as described in Developer Preview Features in This Release. In order to experiment simultaneously with these features and with scopes and collections in the same Developer Preview environment, confine the explicit creation of scopes and collections to one or more buckets separate from that (or those) used for experimentation with any of the other features.

      Information in this Section

      This section provides example-sequences, whereby system set-up and use of REST and CLI procedures are demonstrated. Additionally, it provides a reference page for each REST method.

      For examples of using the REST API, see Collections via REST.

      For examples of using the CLI, see Collections via CLI.

      For the REST reference pages for collections, see REST API Reference.

      For the cbstats reference pages for collections, see cbstats Reference.

      Working with Collections from Couchbase SDKs

      The 3.0 API versions of our SDKs will work with collections in the Developer Preview. See the Java Howto doc, for example.