Couchbase documents are organized into buckets, scopes, and collections. Let’s define those words.
A document is an entry in the database. Each document has key (sometimes called an "ID") and a value (sometimes called the "content").
The document key can be any UTF-8 string not larger than 250 bytes.
The document value can be any kind of data (text or binary) not larger than 20 MiB. By default, the SDK assumes the document value is in JSON format.
A collection is a place to put documents that belong together. You get to decide what it means to "belong." Developers usually put documents of the same type in the same collection.
For example, imagine you have two types of documents: customers and invoices.
You could put the customer documents in a collection called
customers, and the invoice documents in a collection called
Each document belongs to exactly one collection. A document’s ID is unique within the collection.
A scope is a place to put collections that belong together. You get to decide what it means to "belong." If your application has multiple tenants, you could have one scope per tenant.
Different scopes can hold collections with different names. There is no relationship between collections in different scopes.
Each collection belongs to exactly one scope. A collection’s name is unique within the scope.
A bucket holds scopes. Scopes in the same bucket share the same server resources, like the bucket’s RAM quota.
Each scope belongs to exactly one bucket. A scope’s name is unique within the bucket.
Default Scope and Collection
When you create a bucket, Couchbase Server also creates a default scope (named
_default) with a default collection (also named
Before Couchbase Server 7, you can use only the default scope and collection.
If you’re using Couchbase Server 7 or later, you can add more scopes and collections to organize your documents.
Getting a Collection
Before you start, you’ll need to know how to get a
Cluster object to get a
There is an easy way to get a bucket’s default collection:
val bucket = cluster.bucket("myBucket") val defaultCollection = bucket.defaultCollection()
Get other collections using the scope name and collection name:
val bucket = cluster.bucket("myBucket") val myCollection = bucket .scope("myScope") .collection("myCollection")
Collection objects are thread-safe.
You can get them when the application starts, and share the same objects everywhere.
Avoiding class name conflicts
The Couchbase SDK’s