Skip to main content

Scopes and Collections

Description — 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 support for scops and collections, 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.
note

Scope and collection names are case sensitive.

Example 1. Create a scope and collection
final collection = await database.createCollection('myCollectionName', 'myScopeName');

In the example above, you can see that Database.createCollection can take two parameters. The second is the scope assigned to the created collection, if this parameter is omitted then a collection of the given name will be assigned to the _default scope.

The first parameter is the name of the collection you want to create, in this case myCollectionName.

If a collection with the specified name already exists in the specified scope, Database.createCollection returns the existing collection.

note

You cannot create an empty user-defined scope. A scope is implicitly created and removed by the Database.createCollection and Database.deleteCollection methods.

Index a Collection​

Example 2. Index a Collection
final config = FullTextIndexConfiguration(['overview']);
await collection.createIndex('overviewFTSIndex', config);

Drop a Collection​

Example 3. Drop a Collection
await database.deleteCollection('myCollectionName', 'myScopeName');

List Scopes and Collections​

Example 4. List Scopes and Collections
final scopes = await database.scopes;
final collections = await database.collections('myScopeName');
print(
  'I have ${scopes.length} scopes and ${collections.length} collections '
  'in scope "myScopeName"',
);