Manage Scopes and Collections
Scopes and collections allow you to organize your documents within a database.
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. |
// 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");
In the example above, you can see that db.createCollection()
can take two parameters.
The first 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. In this case, creating a collection called Verlaine
.
The second parameter is the name of the collection you want to create, in this case Verlaine
.
In the second section of the example you can see db.createCollection("Television", "Verlaine")
.
This creates the collection Verlaine
and then checks to see if the scope Television
exists.
If the scope Television
exists, the collection Verlaine
is assigned to the scope Television
. If not, a new scope, Television
is created and then the collection Verlaine
is assigned to it.
You cannot create an empty user-defined scope.
A scope is implicitly created in the db.createCollection() method.
|
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
Collection collection = db.getCollection(collectionName, scopeName);
if (collection != null) { db.deleteCollection(collection.getName(), collection.getScope().getName()); }
There is no need to drop a user-defined scope. User-defined scopes are dropped when the collections associated with them contain no documents. |
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());
}
}