Manage Scopes and Collections

Scopes and collections allow you to organize your documents within a database.

At a glance

Use collections to organize your content in a database

For example, if your database contains travel information, airport documents can be assigned to an airports collection, hotel documents can be assigned to a hotels collection, and so on.

Document names must be unique within their collection.

Use scopes to group multiple collections

Collections can be assigned to different scopes according to content-type or deployment-phase (for example, test versus production).

Collection names must be unique within their scope.

Default Scopes and Collections

Every database you create contains a default scope and a default collection named _default.

If you create a document in the database and don’t specify a specific scope or collection, it is saved in the default collection, in the default scope.

If you upgrade from a version of Couchbase Lite prior to 3.1, all existing data is automatically placed in the default scope and default collection.

The default scope and collection cannot be dropped.

Create a Scope and Collection

In addition to the default scope and collection, you can create your own scope and collection when you create a document.

Naming conventions for collections and scopes:

Must be between 1 and 251 characters in length.
Can only contain the characters A-Z, a-z, 0-9, and the symbols _, -, and %.
Cannot start with _ or %.
Scope names must be unique in databases.
Collection names must be unique within a scope.

Scope and collection names are case sensitive.

Example 1. Create a scope and collection

// create the collection "Verlaine" in the default scope ("_default")
Collection collection1 = db.createCollection("Verlaine");
// both of these retrieve collection1 created above
collection1 = db.getCollection("Verlaine");
collection1 = db.getDefaultScope().getCollection("Verlaine");

// create the collection "Verlaine" in the scope "Television"
Collection collection2 = db.createCollection("Television", "Verlaine");
// both of these retrieve  collection2 created above
collection2 = db.getCollection("Television", "Verlaine");
collection2 = db.getScope("Television").getCollection("Verlaine");

Index a Collection

Example 2. Index a Collection

// Create an index named "nameIndex1" on the property "lastName" in the collection using the IndexBuilder
collection.createIndex("nameIndex1", IndexBuilder.valueIndex(ValueIndexItem.property("lastName")));

// Create a similar index named "nameIndex2" using and IndexConfiguration
collection.createIndex("nameIndex2", new ValueIndexConfiguration("lastName"));

// get the names of all the indices in the collection
final Set<String> indices = collection.getIndexes();

// delete all the collection indices
for (String index: indices) { collection.deleteIndex(index); }

Drop a Collection

Example 3. Drop a Collection

Collection collection = db.getCollection(collectionName, scopeName);
if (collection != null) { db.deleteCollection(collection.getName(), collection.getScope().getName()); }

List Scopes and Collections

Example 4. List Scopes and Collections

final Set<Scope> scopes = db.getScopes();
for (Scope scope: scopes) {
    Logger.log("Scope :: " + scope.getName());
    final Set<Collection> collections = scope.getCollections();
    for (Collection collection: collections) {
        Logger.log("    Collection :: " + collection.getName());
    }
}