Buckets, Scopes, and Collections

  • Capella Operational
  • concept
    +
    The data in a Couchbase Capella cluster is categorized and organized into different data containers. These data containers hold documents, which hold JSON key-value pairs that define your data.

    Capella clusters have 3 types of data containers:

    Diagram

    Use the hierarchy of buckets, scopes, and collections to categorize and organize your data for quick and easy retrieval.

    Store documents in collections and group similar collections with scopes. For example, you could use scopes and collections to group data in a travel application:

    Diagram
    You can create new buckets, scopes, and collections when you import data into your cluster. For more information, see Import Data with the Capella UI.

    Buckets

    Buckets are the top-level storage containers for data in a Capella cluster.

    You must create a bucket before you can store any data in your cluster. A Capella cluster can have a maximum of 30 buckets.

    Diagram

    For more information about how to create a new bucket, see Create a Bucket.

    Scopes

    A scope is a data container that exists inside a Capella bucket. Use scopes to group related collections.

    Each bucket can have a maximum of 1000 scopes.

    Diagram

    For more information about how to create a new scope, see Create a Scope.

    _default Scope

    When you create a bucket in your Capella cluster, a _default scope and collection are automatically created within that bucket. Any document that you create without a specific scope and collection is assigned to the _default scope and collection.

    You cannot delete the _default scope.

    _system Scope

    The _system scope is part of all clusters using Couchbase Server 7.6 or later. When you upgrade a cluster to Couchbase Server 7.6, Capella adds the _system scope to your existing buckets.

    All sample buckets and buckets that you create include a _system scope. The _system scope contains the _mobile and _query collections that store system documents for related Couchbases services.

    The _system scope and its collections are read-only, and their structure is subject to change without notice. Do not use these collections for other purposes.

    You cannot remove the _system scope or its collections.

    Collections

    A collection is a data container that exists inside a Capella scope. It’s the smallest container that holds the documents inside a bucket.

    Each scope in a bucket can have a maximum of 1000 collections.

    Diagram

    For more information about how to create a new collection, see Create a Collection.

    _default Collection

    When you create a bucket in your Capella cluster, a _default collection is automatically created within your _default scope. Any document that you create without a specific scope and collection is assigned to the _default scope and collection.

    You can delete the _default collection from the _default scope using the Couchbase Capella UI, API, SDKs, or queries. While you can delete the _default collection, there is no actual advantage to this. The _default collection is there to help group and organize documents without a set scope. If you decide to delete it, you’ll not be able to recreate or recover it later.

    Linking Collections

    You must link collections to your App Endpoints to use data contained within them for your mobile and IoT applications. For more information about collection linking and unlinking, see linking a collection.