Spring Data on Stackoverflow is a tag for all Spring Data (not just Cassandra) users to share information and help each other. Note that registration is needed only for posting.

Developers post questions and answers on . The two key tags to search for related answers to this project are:

Professional, from-the-source support, with guaranteed response time, is available from Pivotal Sofware, Inc., the company behind Spring Data and Spring.

Typically, your repository interface will extend Repository, CrudRepository or PagingAndSortingRepository. Alternatively, if you do not want to extend Spring Data interfaces, you can also annotate your repository interface with @RepositoryDefinition. Extending CrudRepository exposes a complete set of methods to manipulate your entities. If you prefer to be selective about the methods being exposed, simply copy the ones you want to expose from CrudRepository into your domain repository.

In this first step you defined a common base interface for all your domain repositories and exposed findById(…) as well as save(…).These methods will be routed into the base repository implementation of the store of your choice provided by Spring Data ,e.g. in the case if JPA SimpleJpaRepository, because they are matching the method signatures in CrudRepository. So the UserRepository will now be able to save users, and find single ones by id, as well as triggering a query to find Users by their email address.

As of Spring Data 2.0, repository CRUD methods that return an individual aggregate instance use Java 8’s Optional to indicate the potential absence of a value. Besides that, Spring Data supports to return other wrapper types on query methods:

Alternatively query methods can choose not to use a wrapper type at all. The absence of a query result will then be indicated by returning null. Repository methods returning collections, collection alternatives, wrappers, and streams are guaranteed never to return null but rather the corresponding empty representation. See Repository query return types for details.

Using a unique Spring Data module in your application makes things simple hence, all repository interfaces in the defined scope are bound to the Spring Data module. Sometimes applications require using more than one Spring Data module. In such case, it’s required for a repository definition to distinguish between persistence technologies. Spring Data enters strict repository configuration mode because it detects multiple repository factories on the class path. Strict configuration requires details on the repository or the domain class to decide about Spring Data module binding for a repository definition:

Repository type details and identifying domain class annotations are used for strict repository configuration identify repository candidates for a particular Spring Data module. Using multiple persistence technology-specific annotations on the same domain type is possible to reuse domain types across multiple persistence technologies, but then Spring Data is no longer able to determine a unique module to bind the repository.

The last way to distinguish repositories is scoping repository base packages. Base packages define the starting points for scanning for repository interface definitions which implies to have repository definitions located in the appropriate packages. By default, annotation-driven configuration uses the package of the configuration class. The base package in XML-based configuration is mandatory.

The following strategies are available for the repository infrastructure to resolve the query. You can configure the strategy at the namespace through the query-lookup-strategy attribute in case of XML configuration or via the queryLookupStrategy attribute of the Enable${store}Repositories annotation in case of Java config. Some strategies may not be supported for particular datastores.

The query builder mechanism built into Spring Data repository infrastructure is useful for building constraining queries over entities of the repository. The mechanism strips the prefixes find…By, read…By, query…By, count…By, and get…By from the method and starts parsing the rest of it. The introducing clause can contain further expressions such as a Distinct to set a distinct flag on the query to be created. However, the first By acts as delimiter to indicate the start of the actual criteria. At a very basic level you can define conditions on entity properties and concatenate them with And and Or.

The actual result of parsing the method depends on the persistence store for which you create the query. However, there are some general things to notice.

Property expressions can refer only to a direct property of the managed entity, as shown in the preceding example. At query creation time you already make sure that the parsed property is a property of the managed domain class. However, you can also define constraints by traversing nested properties. Assume a Person has an Address with a ZipCode. In that case a method name of

creates the property traversal x.address.zipCode. The resolution algorithm starts with interpreting the entire part (AddressZipCode) as the property and checks the domain class for a property with that name (uncapitalized). If the algorithm succeeds it uses that property. If not, the algorithm splits up the source at the camel case parts from the right side into a head and a tail and tries to find the corresponding property, in our example, AddressZip and Code. If the algorithm finds a property with that head it takes the tail and continue building the tree down from there, splitting the tail up in the way just described. If the first split does not match, the algorithm move the split point to the left (Address, ZipCode) and continues.

Although this should work for most cases, it is possible for the algorithm to select the wrong property. Suppose the Person class has an addressZip property as well. The algorithm would match in the first split round already and essentially choose the wrong property and finally fail (as the type of addressZip probably has no code property).

To resolve this ambiguity you can use \_ inside your method name to manually define traversal points. So our method name would end up like so:

As we treat underscore as a reserved character we strongly advise to follow standard Java naming conventions (i.e. not using underscores in property names but camel case instead).

To handle parameters in your query you simply define method parameters as already seen in the examples above. Besides that the infrastructure will recognize certain specific types like Pageable and Sort to apply pagination and sorting to your queries dynamically.

The first method allows you to pass an org.springframework.data.domain.Pageable instance to the query method to dynamically add paging to your statically defined query. A Page knows about the total number of elements and pages available. It does so by the infrastructure triggering a count query to calculate the overall number. As this might be expensive depending on the store used, Slice can be used as return instead. A Slice only knows about whether there’s a next Slice available which might be just sufficient when walking through a larger result set.

Sorting options are handled through the Pageable instance too. If you only need sorting, simply add an org.springframework.data.domain.Sort parameter to your method. As you also can see, simply returning a List is possible as well. In this case the additional metadata required to build the actual Page instance will not be created (which in turn means that the additional count query that would have been necessary not being issued) but rather simply restricts the query to look up only the given range of entities.

The results of query methods can be limited via the keywords first or top, which can be used interchangeably. An optional numeric value can be appended to top/first to specify the maximum result size to be returned. If the number is left out, a result size of 1 is assumed.

The limiting expressions also support the Distinct keyword. Also, for the queries limiting the result set to one instance, wrapping the result into an Optional is supported.

If pagination or slicing is applied to a limiting query pagination (and the calculation of the number of pages available) then it is applied within the limited result.

The results of query methods can be processed incrementally by using a Java 8 Stream<T> as return type. Instead of simply wrapping the query results in a Stream data store specific methods are used to perform the streaming.

Repository queries can be executed asynchronously using Spring’s asynchronous method execution capability. This means the method will return immediately upon invocation and the actual query execution will occur in a task that has been submitted to a Spring TaskExecutor.

Each Spring Data module includes a repositories element that allows you to simply define a base package that Spring scans for you.

In the preceding example, Spring is instructed to scan com.acme.repositories and all its sub-packages for interfaces extending Repository or one of its sub-interfaces. For each interface found, the infrastructure registers the persistence technology-specific FactoryBean to create the appropriate proxies that handle invocations of the query methods. Each bean is registered under a bean name that is derived from the interface name, so an interface of UserRepository would be registered under userRepository. The base-package attribute allows wildcards, so that you can define a pattern of scanned packages.

The repository infrastructure can also be triggered using a store-specific @Enable${store}Repositories annotation on a JavaConfig class. For an introduction into Java-based configuration of the Spring container, see the reference documentation.^[1]

A sample configuration to enable Spring Data repositories looks something like this.

You can also use the repository infrastructure outside of a Spring container, e.g. in CDI environments. You still need some Spring libraries in your classpath, but generally you can set up repositories programmatically as well. The Spring Data modules that provide repository support ship a persistence technology-specific RepositoryFactory that you can use as follows.

To enrich a repository with custom functionality, you first define a fragment interface and an implementation for the custom functionality. Then let your repository interface additionally extend from the fragment interface.

The implementation itself does not depend on Spring Data and can be a regular Spring bean. So you can use standard dependency injection behavior to inject references to other beans like a JdbcTemplate, take part in aspects, and so on.

Let your repository interface extend the fragment one. Doing so combines the CRUD and custom functionality and makes it available to clients.

Spring Data repositories are implemented by using fragments that form a repository composition. Fragments are the base repository, functional aspects such as QueryDsl and custom interfaces along with their implementation. Each time you add an interface to your repository interface, you enhance the composition by adding a fragment. The base repository and repository aspect implementations are provided by each Spring Data module.

Repositories may be composed of multiple custom implementations that are imported in the order of their declaration. Custom implementations have a higher priority than the base implementation and repository aspects. This ordering allows you to override base repository and aspect methods and resolves ambiguity if two fragments contribute the same method signature. Repository fragments are not limited to be used in a single repository interface. Multiple repositories may use a fragment interface to reuse customizations across different repositories.

The preceding approach requires customization of all repository interfaces when you want to customize the base repository behavior, so all repositories are affected. To change behavior for all repositories, you need to create an implementation that extends the persistence technology-specific repository base class. This class will then act as a custom base class for the repository proxies.

The final step is to make the Spring Data infrastructure aware of the customized repository base class. In JavaConfig this is achieved by using the repositoryBaseClass attribute of the @Enable…Repositories annotation:

A corresponding attribute is available in the XML namespace.

Querydsl is a framework which enables the construction of statically typed SQL-like queries via its fluent API.

Several Spring Data modules offer integration with Querydsl via QueryDslPredicateExecutor.

To make use of Querydsl support simply extend QueryDslPredicateExecutor on your repository interface.

The above enables to write typesafe queries using Querydsl Predicate s.

Spring Data modules ships with a variety of web support if the module supports the repository programming model. The web related stuff requires Spring MVC JARs on the classpath, some of them even provide integration with Spring HATEOAS ^[2]. In general, the integration support is enabled by using the @EnableSpringDataWebSupport annotation in your JavaConfig configuration class.

The @EnableSpringDataWebSupport annotation registers a few components we will discuss in a bit. It will also detect Spring HATEOAS on the classpath and register integration components for it as well if present.

Alternatively, if you are using XML configuration, register either SpringDataWebSupport or HateoasAwareSpringDataWebSupport as Spring beans:

If you work with the Spring JDBC module, you probably are familiar with the support to populate a DataSource using SQL scripts. A similar abstraction is available on the repositories level, although it does not use SQL as the data definition language because it must be store-independent. Thus the populators support XML (through Spring’s OXM abstraction) and JSON (through Jackson) to define data with which to populate the repositories.

Assume you have a file data.json with the following content:

You can easily populate your repositories by using the populator elements of the repository namespace provided in Spring Data Commons. To populate the preceding data to your PersonRepository , do the following:

This declaration causes the data.json file to be read and deserialized via a Jackson ObjectMapper.

The type to which the JSON object will be unmarshalled to will be determined by inspecting the \_class attribute of the JSON document. The infrastructure will eventually select the appropriate repository to handle the object just deserialized.

To rather use XML to define the data the repositories shall be populated with, you can use the unmarshaller-populator element. You configure it to use one of the XML marshaller options Spring OXM provides you with. See the Spring reference documentation for details.

You can choose among several approaches to use as a basis for your Cassandra database access. Spring’s support for Apache Cassandra comes in different flavors. Once you start using one of these approaches, you can still mix and match to include a feature from a different approach.

An example of using Java-based bean metadata to register an instance of a com.datastax.driver.core.Session is shown below.

This approach allows you to use the standard com.datastax.driver.core.Session API that you may already be used to using.

An alternative is to register an instance of com.datastax.driver.core.Session instance with the container using Spring’s CassandraCqlSessionFactoryBean and CassandraCqlClusterFactoryBean. As compared to instantiating a com.datastax.driver.core.Session instance directly, the FactoryBean approach has the added advantage of also providing the container with an ExceptionTranslator implementation that translates Cassandra exceptions to exceptions in Spring’s portable DataAccessException hierarchy for data access classes annotated. This hierarchy and use of @Repository is described in Spring’s DAO support features.

An example of a Java-based bean metadata that supports exception translation on @Repository annotated classes is shown below:

Using CassandraTemplate with object mapping and Repository support requires a CassandraTemplate, CassandraMappingContext, CassandraConverter and enabling Repository support.

Creating configuration classes registering Spring Data for Apache Cassandra components can be an exhausting challenge so Spring Data for Apache Cassandra comes with a prebuilt configuration support class. Classes extending from AbstractCassandraConfiguration will register beans for Spring Data for Apache Cassandra use. AbstractCassandraConfiguration lets you provide various configuration options such as initial entities, default query options, pooling options, socket options and much more. AbstractCassandraConfiguration will support you also with schema generation based on initial entities, if any are provided. Extending from AbstractCassandraConfiguration requires you to at least provide the Keyspace name by implementing the getKeyspaceName method.

The very first thing to start with is a Cassandra Keyspace. A Keyspace is a logical grouping of tables that share the same replication factor and replication strategy. Keyspace management is located in the Cluster configuration, which has the notion of KeyspaceSpecification and startup/shutdown CQL script execution.

Declaring a Keyspace with a specification allows creating/dropping of the Keyspace. It will derive CQL from the specification so you’re not required to write CQL yourself.

Startup/shutdown CQL execution follows a slightly different approach that is bound to the Cluster lifecycle. You can provide arbitrary CQL that is executed on Cluster initialization and shutdown in the SYSTEM keyspace.

Spring Data for Apache Cassandra’s approaches data access with mapped entity classes that fit your data model. These entity classes can be used to create Cassandra table specifications and user type definitions.

Schema creation is tied to Session initialization with SchemaAction. The following actions are supported:

This section provides some examples of the CqlTemplate class in action. These examples are not an exhaustive list of all of the functionality exposed by the CqlTemplate; see the attendant Javadocs for that.

CassandraTemplate should always be configured as a Spring bean, although we show an example above where you can instantiate it directly. But, for the purposes of this being a Spring module, lets assume we are using the Spring container.

There are 2 easy ways to get a CassandraTemplate, depending on how you load you Spring ApplicationContext.

Like all Spring Autowiring, this assumes there is only one bean of type CassandraOperations in the ApplicationContext. If you have multiple CassandraTemplate beans (which will be the case if you are working with multiple Keyspaces in the same project), then use the `@Qualifier`annotation to designate which bean you want to Autowire.

You can also just lookup the CassandraTemplate bean from the ApplicationContext.

Spring Data for Apache Cassandra relies on the DataStax Java Driver’s CodecRegistry to ensure type support. As types are added or changed, the Spring Data for Apache Cassandra module will continue to function without requiring changes. See CQL data types and Data Mapping and Type Conversion for the current type mapping matrix.

There are several convenient methods on CassandraTemplate for saving and inserting your objects. To have more fine-grained control over the conversion process you can register Spring Converters with the MappingCassandraConverter. For example, Converter<Row, Person>.

The simple case of using the insert operation is to save a POJO. In this case, the table name will be determined by the simple name of the class (not fully-qualified). The table to store the object can be overridden using mapping metadata.

When inserting or updating, the id property must be set. There is no means to generate an ID with Apache Cassandra.

Here is a basic example of using the save operation and retrieving its contents.

The insert/save operations available to you are listed below.

A similar set of update operations is listed below

Then, there is always the old fashioned way; you can write your own CQL statements.

You can also configure additional options such as TTL, consistency level and lightweight transactions using InsertOptions and UpdateOptions.

For updates, we can select to update a number of rows.

Here is an example of updating a single account object where we are adding a one-time $50.00 bonus to the balance using the + assignment.

In addition to the Query discussed above, we provide the update definition using an Update object. The Update class has methods that match the update assignments available for Apache Cassandra.

As you can see most methods return the Update object to provide a fluent API for code styling purposes.

You can use several overloaded methods to remove an object from the database.

We saw how to retrieve a single object using the selectOneById method on CassandraTemplate in previous sections, which return a single domain object. We can also query for a collection of rows to be returned as a list of domain objects. Assuming we have a number of Person objects with name and age stored as rows in a table and that each person has an account balance, we can now run a query using the following code.

select, selectOneById and stream methods take a Query object as a parameter. This object defines the criteria and options used to perform the query. The criteria is specified using a Criteria object that has a static factory method named where used to instantiate a new Criteria object. We recommend using a static import for org.springframework.data.cassandra.core.query.Criteria.where and Query.query to make the query more readable.

This query should return a list of Person objects that meet the specified criteria. The Criteria class has the following methods that correspond to the operators provided in Apache Cassandra.

The query methods need to specify the target type T that will be returned.

An example implementation of a Converter that converts a Person object to a java.lang.String using Jackson 2 is shown below:

An example implementation of a Converter that converts a java.lang.String into a Person object using Jackson 2 is shown below:

Spring Data for Apache Cassandra Java Config provides a convenient way to register Spring Converter`s with the `MappingCassandraConverter. The configuration snippet below shows how to manually register converters as well as configure CustomConversions.

Generally, we inspect the Converter implementations for both the source and target types they convert from and to. Depending on whether one of those is a type Cassandra can handle natively, Spring Data will register the Converter instance as a reading or writing one.

Have a look at the following samples:

In case you implement a Converter whose source and target types are native Cassandra types, there’s no way for Spring Data to determine whether we should consider it as a reading or writing Converter. Registering the Converter instance as both might lead to unwanted results.

E.g. a Converter<String, Long> is ambiguous although it probably does not make sense to try to convert all String instances into Long instances when writing. To generally be able to force the infrastructure to register a Converter for one way only we provide @ReadingConverter as well as @WritingConverter to be used as the appropriate Converter implementation.

You can configure Reactive Cassandra support via Java Configuration classes. Reactive Cassandra support adapts a Session to provide a reactive execution model on top of an asynchronous driver.

A reactive Session is configured similar to an imperative Session. We provide supporting configuration classes that come with predefined defaults and require only environment-specific information to configure Spring Data for Apache Cassandra. The base class for reactive support is AbstractReactiveCassandraConfiguration. This configuration class extends the imperative AbstractCassandraConfiguration and so the reactive support will also configure the imperative API support as well.

This configuration class is schema-management-enabled to create CQL objects during startup. See Schema Management for further details.

This section provides some examples of ReactiveCqlTemplate class usage. These examples are not an exhaustive list of all of the functionality exposed by the ReactiveCqlTemplate; see the attendant Javadocs for that.

ReactiveCassandraTemplate should always be configured as a Spring bean, although we show an example above where you can instantiate it directly. But, for the purposes of this being a Spring module, lets assume we are using the Spring container.

There are 2 easy ways to get a ReactiveCassandraTemplate, depending on how you load you Spring ApplicationContext.

Like all Spring Autowiring, this assumes there is only one bean of type ReactiveCassandraOperations in the ApplicationContext. If you have multiple ReactiveCassandraTemplate beans (which will be the case if you are working with multiple Keyspaces in the same project), then use the `@Qualifier`annotation to designate which bean you want to Autowire.

You can also just lookup the CassandraTemplate bean from the ApplicationContext.

There are several convenient methods on CassandraTemplate for saving and inserting your objects. To have more fine-grained control over the conversion process you can register Spring Converter`s with the `MappingCassandraConverter. For example, Converter<Row, Person>.

The simple case of using the INSERT operation is to save a POJO. In this case the table name will be determined by the simple class name (not fully-qualified class name). The table to store the object can be overridden using mapping metadata.

When inserting or updating, the id property must be set. There is no means to generate an ID in Apache Cassandra.

Here is a basic example of using the save operation and retrieving its contents.

The insert/save operations available to you are listed below.

A similar set of update operations is listed below

Then, there is always the old fashioned way. You can write your own CQL statements.

You can also configure additional options such as TTL, consistency level and lightweight transactions using InsertOptions and UpdateOptions.

For updates, we can select to update a number of rows.

Here is an example of updating a single account object where we are adding a one-time $50.00 bonus to the balance using the + assignment.

In addition to the Query discussed above we provide the update definition using an Update object. The Update class has methods that match the update assignments available for Apache Cassandra.

As you can see most methods return the Update object to provide a fluent API for code styling purposes.

Read more about Query and Update.

Spring Data query methods usually return one or multiple instances of the aggregate root managed by the repository. However, it might sometimes be desirable to rather project on certain attributes of those types. Spring Data allows to model dedicated return types to more selectively retrieve partial views onto the managed aggregates.

Imagine a sample repository and aggregate root type like this:

Now imagine we’d want to retrieve the person’s name attributes only. What means does Spring Data offer to achieve this?

You can specify query options for query methods by passing a QueryOptions object to apply options to the query before the actual query execution. QueryOptions is treated as non-query parameter and isn’t considered as query parameter value.

For static declaration of a consistency level, use the @Consistency annotation on query methods. The declared consistency level is applied to the query each time it is executed.

Query options are applicable to derived and string @Query repository methods.

Instances of the Repository interfaces are usually created by a container, and the Spring container is the most natural choice when working with Spring Data. Spring Data for Apache Cassandra ships with a custom CDI extension that allows using the repository abstraction in CDI environments. The extension is part of the JAR so all you need to do to activate it is dropping the Spring Data for Apache Cassandra JAR into your classpath. You can now set up the infrastructure by implementing a CDI Producer for the CassandraTemplate:

The Spring Data for Apache Cassandra CDI extension will pick up CassandraOperations available as CDI bean and create a proxy for a Spring Data Repository whenever an bean of a Repository type is requested by the container. Thus obtaining an instance of a Spring Data Repository is a matter of declaring an @Inject-ed property:

Unless explicitly configured, an instance of MappingCassandraConverter is created by default when creating a CassandraTemplate. You can create your own instance of the MappingCassandraConverter so as to tell it where to scan the classpath at startup for your domain classes in order to extract metadata and construct indexes.

Also, by creating your own instance you can register Spring `Converter`s to use for mapping specific classes to and from the database.

AbstractCassandraConfiguration requires you to implement methods that define a Keyspace. AbstractCassandraConfiguration also has a method you can override named getEntityBasePackages(…) which tells the converter where to scan for classes annotated with the @Table annotation.

You can add additional converters to the MappingCassandraConverter by overriding the method customConversions.

Cassandra requires at least one partition key field for a CQL table. A table can additionally declare one or more clustering key fields. When your CQL table has a composite primary key, you must create a @PrimaryKeyClass to define the structure of the composite primary key. In this context, composite primary key means one or more partition columns optionally combined with one or more clustering columns.

Primary keys can make use of any singular simple Cassandra type or mapped User-Defined Type. Collection-typed primary keys are not supported.

The MappingCassandraConverter can use metadata to drive the mapping of objects to rows in a Cassandra table. An overview of the annotations is provided below:

The mapping metadata infrastructure is defined in the separate, spring-data-commons project that is both technology and data store agnostic.

Here is an example of a more complex mapping.

When storing and querying your objects it is convenient to have a CassandraConverter instance handle the mapping of all Java types to Rows. However, sometimes you may want the CassandraConverter to do most of the work but still allow you to selectively handle the conversion for a particular type, or to optimize performance.

To selectively handle the conversion yourself, register one or more org.springframework.core.convert.converter.Converter instances with the CassandraConverter.

Below is an example of a Spring Converter implementation that converts from a Row to a Person POJO.

Spring CQL and Spring Data Cassandra are now merged into a single module. The standalone spring-cql module is no longer available. Find all types merged into spring-data-cassandra.

With the merge, we merged all CQL packages into Spring Data Cassandra:

We split CqlTemplate and CassandraTemplate in two ways:

The method was removed because it did not support complex Ids. The newly introduced query DSL allows mapped and complex id’s for single column Id’s:

We renamed CassandraRepository and TypedIdCassandraRepository to align SD Cassandra naming with other Spring Data modules:

SD Cassandra ConsistencyLevel and RetryPolicy have been removed. Please use the types provided by the DataStax driver directly.

The SD Cassandra types restricted usage of available features provided in and allowed by the Cassandra native driver. As a result, the SD Cassandra’s types required an update each time newer functionality was introduced by the driver.

CQL specification types are now value types as much as possible (such as FieldSpecification, AlterColumnSpecification) and objects are constructed via static factory methods. This allows immutability for simple value objects. Configurator objects (such as AlterTableSpecification) that operate on mandatory properties like a table name, keyspace name, are initially constructed through a a static factory method and allow further configuration until the desired state is created.

QueryOptions and WriteOptions are now immutable and can be created through builders. Methods accepting QueryOptions enforce non-null objects which are available from static empty() factory methods.

You are only affected by this change if you operate on the mapping model directly.

CassandraPersistentProperty allowed previously multiple column names to be bound for composite primary key use. Columns of a CassandraPersistentProperty are now reduced to a single column. Resolved composite primary keys mapped to a class via MappingContext.getRequiredPersistentEntity(…).