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("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());