Scopes and Collections

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. Item-names must be unique within their collection. 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. Applications can be assigned per-collection access-rights; allowing each application to access only those collections it requires.

A collection can be created and managed by means of the Couchbase Web Console UI, the Couchbase CLI, the Couchbase REST API, and SQL++. It can also be created and managed by means of the SDK: see Collection Management. A collection can be indexed; and it can be dropped. The data in a collection can be replicated, by means of Cross Data Center Replication (XDCR), to another collection in the same or in a different bucket.

A scope is a mechanism for the grouping of multiple collections. Up to 1000 scopes can be created per cluster. 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 scopes it requires.

A scope can be created and managed by means of the Couchbase Web Console UI, the Couchbase CLI, the Couchbase REST API, and SQL++. It can also be created and managed by means of the SDK: see Collection Management. A scope can be dropped. A scope cannot be indexed. The contents of a scope can be replicated, by means of Cross Data Center Replication (XDCR), to another scope in the same or in a different bucket.

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

The namespace within a scope is independent of any other namespace within any other scope: consequently, the same collection-name can exist in multiple scopes, within a single bucket. Similarly, the namespace within a collection is independent of any other namespace within any other collection: consequently, the same document-key can exist in multiple collections, within a single scope.

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. On upgrade from a version of Couchbase Server prior to 7.0, all existing data is automatically placed in the default scope and default collection.

The default scope cannot be dropped. The default collection can be dropped, by means of either the Couchbase CLI, or the REST API. Once dropped, the default collection cannot be recreated.

In Couchbase Server Version 7.6+, in each user-created or sample bucket, a _system scope is created and maintained by default. This scope contains collections used by Couchbase services, for service-specific data. The _system scope and its collections (including mobile and query) are not for the use of administrators; and should not be accessed in any way by users or user-created applications. The _system scope and its collections cannot be dropped.

Access to scopes and collections is protected by Role-Based Access Control (RBAC): therefore, appropriate roles must be assigned.

For information on RBAC, see Authorization. For a list of roles, see Roles. For examples of how to assign roles to scopes and collections, see Manage Users, Groups, and Roles.

A query may refer to a collection using an absolute keyspace path; or a relative partial keyspace reference, which must be resolved by means of the query context. The use of partial keyspace references and query context supports the separation of tenant data in a multi-tenancy environment. For details, refer to Query Context.

An expiration value can be established on a collection: this determines the maximum expiration time of individual items within the collection. For information, see Expiration.

When Magma storage is used for a bucket, the changes made to documents within the bucket’s collections can be recorded, in a change history. The change history resides on disk. Its capacity is administrator-specified. When the change history is full, old records are automatically removed (by means of compaction), to allow space for new records.

For detailed information, see Change History.

See Manage Scopes and Collections, for information on how to use the CLI and REST API to create, maintain, and delete scopes and collections.

For information on using the Backup Service to inspect scopes and collections within backed-up data, and to restore data to specific scopes and collections, see Manage Backup and Restore.

For information on using scopes and collections with Cross Data Center Replication (XDCR), see Replicate Using Scopes and Collections.

For a complete reference to the CLI command for managing scopes and collections, see collection-manage.

For reference pages for the REST API commands that manage scopes and collections, see Scopes and Collections REST API.

For the cbstats reference pages for scopes and collections, see scopes, scopes-details, collections, and collections-details.

As indicated above, it is possible to create, maintain, and delete scopes and collections using {sql++}. See the SQL++ Language Reference for further details.

The 3.x API versions of Couchbase SDKs work with scopes and collections. For information, see the Java Howto doc.