Collection Support

Couchbase supports Scopes and Collections. This section documents on how to use it with Spring Data Couchbase.

The try-cb-spring sample application is a working example of using Scopes and Collections in Spring Data Couchbase.

The 2021 Couchbase Connect presentation on Collections in Spring Data can be found at Presentation Only and Presentation with Slide Deck

Requirements

Couchbase Server 7.0 or above.
Spring Data Couchbase 4.3.1 or above.

Getting Started & Configuration

Scope and Collection Specification

There are several mechanisms of specifying scopes and collections, and these may be combined, or one mechanism may override another. First some definitions for scopes and collections. An unspecified scope indicates that the default scope is to be used, likewise, an unspecified collection indicates that the default collection is to be used. There are only three combinations of scopes and collections that are valid. (1) the default scope and the default collection; (2) the default scope and a non-default collection; and (3) a non-default scope and a non-default collection. It is not possible to have a non-default scope and a default collection as non-default scopes do not contain a default collections, neither can one be created.

A scope can be specified in the configuration:

@Configuration
static class Config extends AbstractCouchbaseConfiguration {

    // Usual Setup
    @Override public String getConnectionString() { /* ... */ }

    // optionally specify the scope in the Configuration
    @Override
    protected String getScopeName() {
        return "myScope"; // or a variable etc.;
    }

}

Scopes and Collections can be specified as annotations on entity classes and repositories:

@Document
@Scope("travel")
@Collection("airport")
public class Airport {...

@Scope("travel")
@Collection("airport")
public interface AirportRepository extends CouchbaseRepository<Airport, String> ...

Scopes and Collections can be specified on templates using the inScope(scopeName) and inCollection(collectionName) fluent APIs:

List<Airport> airports = template.findByQuery(Airport.class).inScope("archived").all()

Scopes and Collections can be specified on repositories that extend DynamicProxyable using the withScope(scopeName) and withCollection(collectionName) APIs:

public interface AirportRepository extends CouchbaseRepository<Airport, String>, DynamicProxyable<AirportRepository>{...}
...
List<Airport> airports = airportRepository.withScope("archived").findByName(iata);

The order of precedence is:

inScope()/inCollection() of the template fluent api
withScope()/withCollection() of the template/repository object
annotation of the repository method
annotation of the repository interface
annotation of the entity object
getScope() of the configuration