The configuration, xml schema, etc…​ has changed to take the evolution of the 2.x SDK API into account.

Where a single CouchbaseClient bean was previously the only bean declarable, you can now declare a Cluster bean (<couchbase:cluster>), one or more Bucket beans (<couchbase:bucket>) and even tune the SDK via a CouchbaseEnvironment bean (<couchbase:env>). All of these can also be created via Java Config method by extending AbstractCouchbaseConfig.

The cluster bean lists the nodes to connect through (and references the environment bean if tuning is necessary) while the bucket beans map to bucket names and passwords and actually opens the connections internally.

You can define more beans that are used for internal configuration of the Spring Data Couchbase module (MappingContext, CouchbaseConverter, TranslationService, …​).

For more information, see Installation & Configuration.

The view-backed query method has evolved and support for N1QL has been introduced. As a result, there are now 4 ways of doing repository queries:

View backed queries are associated with the @View annotation, while N1QL backed queries are associated with the @Query annotation.

N1QL query derivation is now the default query method (and there the @Query annotation is optional).

See N1QL based querying and Backing Views for more information.

To instead back them with views, use the @View annotation explicitly.

Without a viewName specified, the view will be guessed from method name (stripping count or find prefix). Otherwise, query derivation will be used to parameterize the view query from the method name and parameters.

All versions intended for production use are distributed across Maven Central and the Spring release repository. As a result, the library can be included like any other maven dependency:

This will pull in several dependencies, including the underlying Couchbase Java SDK, common Spring dependencies and also Jackson as the JSON mapping infrastructure.

You can also grab snapshots from the spring snapshot repository and milestone releases from the milestone repository. Here is an example on how to use the current SNAPSHOT dependency:

Once you have all needed dependencies on the classpath, you can start configuring it. Both Java and XML config are supported. The next sections describe both approaches in detail.

The annotation based configuration approach is getting more and more popular. It allows you to get rid of XML configuration and treat configuration as part of your code directly. To get started, all you need to do is subclcass the AbstractCouchbaseConfiguration and implement the abstract methods.

Please make sure to have cglib support in the classpath so that the annotation based configuration works.

All you need to provide is a list of Couchbase nodes to bootstrap into (without any ports, just the IP address or hostname). Please note that while one host is sufficient in development, it is recommended to add 3 to 5 bootstrap nodes here. Couchbase will pick up all nodes from the cluster automatically, but it could be the case that the only node you’ve provided is experiencing issues while you are starting the application.

The bucketName and password should be the same as configured in Couchbase Server itself. In the example given, we are connecting to the beer-sample bucket which is one of the sample buckets shipped with Couchbase Server and has no password set by default.

Depending on how your environment is set up, the configuration will be automatically picked up by the context or you need to instantiate your own one. How to manage configurations is not in scope of this manual, please refer to the spring documentation for more information on that topic.

Additionally, the SDK environment can be tuned by overriding the getEnvironment() method to return a properly tuned CouchbaseEnvironment.

While not immediately obvious, much more things can be customized and overridden as custom beans from this configuration (for example repositories, query consistency, validation and custom converters).

The library provides a custom namespace that you can use in your XML configuration:

This code is equivalent to the java configuration approach shown above. You can customize the SDK CouchbaseEnvironment via the <couchbase:env/> tag, that supports most tuning parameters as attributes. It is also possible to configure templates and repositories, which is shown in the appropriate sections.

If you start your application, you should see Couchbase INFO level logging in the logs, indicating that the underlying Couchbase Java SDK is connecting to the database. If any errors are reported, make sure that the given credentials and host information are correct.

All entities should be annotated with the @Document annotation.

Also, every field in the entity should be annotated with the @Field annotation from the Couchbase SDK. While this is - strictly speaking - optional, it helps to reduce edge cases and clearly shows the intent and design of the entity. It can also be used to store the field under a different name.

There is also a special @Id annotation which needs to be always in place. Best practice is to also name the property id.

Here is a very simple User entity:

Couchbase Server supports automatic expiration for documents. The library implements support for it through the @Document annotation. You can set a expiry value which translates to the number of seconds until the document gets removed automatically. If you want to make it expire in 10 seconds after mutation, set it like @Document(expiry = 10).

If you want a different representation of the field name inside the document in contrast to the field name used in your entity, you can set a different name on the @Field annotation. For example if you want to keep your documents small you can set the firstname field to @Field("fname"). In the JSON document, you’ll see {"fname": ".."} instead of {"firstname": ".."}.

The @Id annotation needs to be present because every document in Couchbase needs a unique key. This key needs to be any string with a length of maximum 250 characters. Feel free to use whatever fits your use case, be it a UUID, an email address or anything else.

The storage format of choice is JSON. It is great, but like many data representations it allows less datatypes than you could express in Java directly. Therefore, for all non-primitive types some form of conversion to and from supported types needs to happen.

For the following entity field types, you don’t need to add special handling:

Since JSON supports objects ("maps") and lists, Map and List types can be converted naturally. If they only contain primitive field types from the last paragraph, you don’t need to add special handling too. Here is an example:

Storing a user with some sample data could look like this as a JSON representation:

You don’t need to break everything down to primitive types and Lists/Maps all the time. Of course, you can also compose other objects out of those primitive values. Let’s modify the last example so that we want to store a List of Children:

A populated object can look like:

Most of the time, you also need to store a temporal value like a Date. Since it can’t be stored directly in JSON, a conversion needs to happen. The library implements default converters for Date, Calendar and JodaTime types (if on the classpath). All of those are represented by default in the document as a unix timestamp (number). You can always override the default behavior with custom converters as shown later. Here is an example:

A populated object can look like:

If you want to override a converter or implement your own one, this is also possible. The library implements the general Spring Converter pattern. You can plug in custom converters on bean creation time in your configuration. Here’s how you can configure it (in your overridden AbstractCouchbaseConfiguration):

There are a few things to keep in mind with custom conversions:

Couchbase Server does not support multi-document transactions or rollback. To implement optimistic locking, Couchbase uses a CAS (compare and swap) approach. When a document is mutated, the CAS value also changes. The CAS is opaque to the client, the only thing you need to know is that it changes when the content or a meta information changes too.

In other datastores, similar behavior can be achieved through an arbitrary version field with a incrementing counter. Since Couchbase supports this in a much better fashion, it is easy to implement. If you want automatic optimistic locking support, all you need to do is add a @Version annotation on a long field like this:

If you load a document through the template or repository, the version field will be automatically populated with the current CAS value. It is important to note that you shouldn’t access the field or even change it on your own. Once you save the document back, it will either succeed or fail with a OptimisticLockingFailureException. If you get such an exception, the further approach depends on what you want to achieve application wise. You should either retry the complete load-update-write cycle or propagate the error to the upper layers for proper handling.

The library supports JSR 303 validation, which is based on annotations directly in your entities. Of course you can add all kinds of validation in your service layer, but this way its nicely coupled to your actual entities.

To make it work, you need to include two additional dependencies. JSR 303 and a library that implements it, like the one supported by hibernate:

Now you need to add two beans to your configuration:

Now you can annotate your fields with JSR303 annotations. If a validation on save() fails, a ConstraintViolationException is thrown.

The central interface in Spring Data repository abstraction is Repository (probably not that much of a surprise). It takes the domain class to manage as well as the id type of the domain class as type arguments. This interface acts primarily as a marker interface to capture the types to work with and to help you to discover interfaces that extend this one. The CrudRepository provides sophisticated CRUD functionality for the entity class that is being managed.

On top of the CrudRepository there is a PagingAndSortingRepository abstraction that adds additional methods to ease paginated access to entities:

Accessing the second page of User by a page size of 20 you could simply do something like this:

In addition to query methods, query derivation for both count and delete queries, is available.

Standard CRUD functionality repositories usually have queries on the underlying datastore. With Spring Data, declaring those queries becomes a four-step process:

Also, note that the JavaConfig variant doesn’t configure a package explictly as the package of the annotated class is used by default. To customize the package to scan use one of the basePackage… attribute of the data-store specific repository @Enable…-annotation.

The sections that follow explain each step in detail.

As a first step you define a domain class-specific repository interface. The interface must extend Repository and be typed to the domain class and an ID type. If you want to expose CRUD methods for that domain type, extend CrudRepository instead of Repository.

The repository proxy has two ways to derive a store-specific query from the method name. It can derive the query from the method name directly, or by using a manually defined query. Available options depend on the actual store. However, there’s got to be a strategy that decides what actual query is created. Let’s have a look at the available options.

In this section you create instances and bean definitions for the repository interfaces defined. One way to do so is using the Spring namespace that is shipped with each Spring Data module that supports the repository mechanism although we generally recommend to use the Java-Config style configuration.

Often it is necessary to provide a custom implementation for a few repository methods. Spring Data repositories easily allow you to provide custom repository code and integrate it with generic CRUD abstraction and query method functionality.

This section documents a set of Spring Data extensions that enable Spring Data usage in a variety of contexts. Currently most of the integration is targeted towards Spring MVC.

While support for repositories is always present, you need to enable them in general or for a specific namespace. If you extend AbstractCouchbaseConfiguration, just use the @EnableCouchbaseRepositories annotation. It provides lots of possible options to narrow or customize the search path, one of the most common ones is basePackages.

XML-based configuration is also available:

In the simplest case, your repository will extend the CrudRepository<T, String>, where T is the entity that you want to expose. Let’s look at a repository for a UserInfo:

Please note that this is just an interface and not an actual class. In the background, when your context gets initialized, actual implementations for your repository descriptions get created and you can access them through regular beans. This means you will save lots of boilerplate code while still exposing full CRUD semantics to your service layer and application.

Now, let’s imagine we @Autowire the UserRepository to a class that makes use of it. What methods do we have available?

Now that’s awesome! Just by defining an interface we get full CRUD functionality on top of our managed entity. All methods suffixed with (*) in the table are backed by Views, which is explained later.

If you are coming from other datastore implementations, you might want to implement the PagingAndSortingRepository as well. Note that as of now, it is not supported but will be in the future.

While the exposed methods provide you with a great variety of access patterns, very often you need to define custom ones. You can do this by adding method declarations to your interface, which will be automatically resolved to requests in the background, as we’ll see in the next two sections.

This is the historical way of secondary indexing in Couchbase. Views are much more limited in terms of querying flexibility, and each custom method may very well need its own backing view, to be prepared in the cluster beforehand.

We’ll only cover views to the extent to which they are needed, if you need in-depth information about them please refer to the official Couchbase Server manual and the Couchbase Java SDK manual.

As a rule of thumb, all repository CRUD access methods which are not "by a specific key" still require a single backing view, by default all, to find the one or more matching entities.

To cover the basic CRUD methods from the CrudRepository, one view needs to be implemented in Couchbase Server. It basically returns all documents for the specific entity and also adds the optional reduce function _count.

Since every view has a design document and view name, by convention we default to all as the view name and the uncapitalized (lowercase first letter) entity name as the design document name. So if your entity is named UserInfo, then the code expects the all view in the userInfo design document. It needs to look like this:

Note that the important part in this map function is to only include the document IDs which correspond to our entity. Because the library always adds the _class property, this is a quick and easy way to do it. If you have another property in your JSON which does the same job (like a explicit type field), then you can use that as well - you don’t have to stick to _class all the time.

Also make sure to publish your design documents into production so that they can be picked up by the library! Also, if you are curious why we use emit(null, null) in the view: the document id is always sent over to the client implicitly, so we can shave off a view bytes in our view by not duplicating the id. If you use emit(meta.id, null) it won’t hurt much too.

One aspect that is often needed and doesn’t have a direct equivalent in the Spring Data query derivation mechanism is query consistency. In both view-based queries and N1QL, you have this concept that the secondary index can return stale data, because the latest version hasn’t been indexed yet. This gives the best performance at the expense of consistency.

If one wants to have stronger consistency, there are two possibilities described in the next sections.

The template can be accessed through the couchbaseTemplate bean out of your context. Once you’ve got a reference to it, you can run all kinds of operations against it. Other than through a repository, in a template you need to always specify the target entity type which you want to get converted.

To mutate documents, you’ll find save, insert and update methods exposed. Saving will insert or update the document, insert will fail if it has been created already and update only works against documents that have already been created.

Since Couchbase Server has different levels of persistence (by default you’ll get a positive response if it has been acknowledged in the managed cache), you can provide higher durability options through the overloaded PersistTo and/or ReplicateTo options. The behaviour is part of the Couchbase Java SDK, please refer to the official documentation for more details.

Removing documents through the remove methods works exactly the same.

If you want to load documents, you can do that through the findById method, which is the fastest and if possible your tool of choice. The find methods for views are findByView which converts it into the target entity, but also queryView which exposes lower level semantics. Similarly, find methods using N1QL are provided in findByN1QL and queryN1QL. Additionally, since N1QL allows you to select specific fields in documents (or even across documents using joins), findByN1QLProjection will allow you to skip full Document conversion and map these fields to an ad-hoc class.

If you really need low-level semantics, the couchbaseBucket is also always in scope through getCouchbaseBucket().

The template can be configured via xml, including setting a custom TranslationService.

The <repositories /> element triggers the setup of the Spring Data repository infrastructure. The most important attribute is base-package which defines the package to scan for Spring Data repository interfaces.[3]

The <populator /> element allows to populate the a data store via the Spring Data repository infrastructure.[4]

The following table lists the keywords generally supported by the Spring Data repository query derivation mechanism. However, consult the store-specific documentation for the exact list of supported keywords, because some listed here might not be supported in a particular store.

The following table lists the return types generally supported by Spring Data repositories. However, consult the store-specific documentation for the exact list of supported return types, because some listed here might not be supported in a particular store.