For information on the Spring Data for Apache Cassandra source code repository, nightly builds, and snapshot artifacts see the Spring Data for Apache Cassandra home page. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the community on Stack Overflow. To follow developer activity, look for the mailing list information on the Spring Data for Apache Cassandra home page. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue tracker. To stay up-to-date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community Portal. Finally, you can follow the Spring blog or the project team on Twitter (SpringData).

Unresolved directive in index.adoc - include::../../../../../spring-data-commons/src/main/asciidoc/dependencies.adoc[leveloffset=+1] Unresolved directive in index.adoc - include::../../../../../spring-data-commons/src/main/asciidoc/repositories.adoc[leveloffset=+1]

Spring Data for Apache Cassandra allows interaction on both the CQL and the entity level.

The value provided by the Spring Data for Apache Cassandra abstraction is perhaps best shown by the sequence of actions outlined in the table below. The table shows which actions Spring take care of and which actions are the responsibility of you, the application developer.

The core CQL support takes care of all the low-level details that can make Cassandra and CQL such a tedious API with which to develop. Using mapped entity objects allows schema generation, object mapping, and repository support.

Spring Data for Apache Cassandra requires Apache Cassandra 2.1 or later and Datastax Java Driver 4.0 or later. An easy way to quickly set up and bootstrap a working environment is to create a Spring-based project in STS or use Spring Initializer.

First, you need to set up a running Apache Cassandra server. See the Apache Cassandra Quick Start Guide for an explanation on how to start Apache Cassandra. Once installed, starting Cassandra is typically a matter of executing the following command: CASSANDRA_HOME/bin/cassandra -f.

To create a Spring project in STS, go to File → New → Spring Template Project → Simple Spring Utility Project and press Yes when prompted. Then enter a project and a package name, such as org.spring.data.cassandra.example.

Then you can add the following dependency declaration to your pom.xml file’s dependencies section.

Also, you should change the version of Spring in the pom.xml file to be as follows:

If using a milestone release instead of a GA release, you also need to add the location of the Spring Milestone repository for Maven to your pom.xml file so that it is at the same level of your <dependencies/> element, as follows:

The repository is also browseable here.

You can also browse all Spring repositories here.

Now you can create a simple Java application that stores and reads a domain object to and from Cassandra.

To do so, first create a simple domain object class to persist, as the following example shows:

Next, create the main application to run, as the following example shows:

Even in this simple example, there are a few notable things to point out:

To get a feel for how the library works, you can download and play around with several examples. .

One of the first tasks when using Apache Cassandra with Spring is to create a com.datastax.oss.driver.api.core.CqlSession object by using the Spring IoC container. You can do so either by using Java-based bean metadata or by using XML-based bean metadata. These are discussed in the following sections.

Apache Cassandra is a data store that requires a schema definition prior to any data interaction. Spring Data for Apache Cassandra can support you with schema creation.

The CqlTemplate class is the central class in the core CQL package. It handles the creation and release of resources. It performs the basic tasks of the core CQL workflow, such as statement creation and execution, and leaves application code to provide CQL and extract results. The CqlTemplate class executes CQL queries and update statements, performs iteration over ResultSet instances and extraction of returned parameter values. It also catches CQL exceptions and translates them to the generic, more informative, exception hierarchy defined in the org.springframework.dao package.

When you use the CqlTemplate for your code, you need only implement callback interfaces, which have a clearly defined contract. Given a Connection, the PreparedStatementCreator callback interface creates a prepared statement with the provided CQL and any necessary parameter arguments. The RowCallbackHandler interface extracts values from each row of a ResultSet.

The CqlTemplate can be used within a DAO implementation through direct instantiation with a SessionFactory reference or be configured in the Spring container and given to DAOs as a bean reference. CqlTemplate is a foundational building block for CassandraTemplate.

All CQL issued by this class is logged at the DEBUG level under the category corresponding to the fully-qualified class name of the template instance (typically CqlTemplate, but it may be different if you use a custom subclass of the CqlTemplate class).

You can control fetch size, consistency level, and retry policy defaults by configuring these parameters on the CQL API instances: CqlTemplate, AsyncCqlTemplate, and ReactiveCqlTemplate. Defaults apply if the particular query option is not set.

The Spring Framework provides exception translation for a wide variety of database and mapping technologies. This has traditionally been for JDBC and JPA. Spring Data for Apache Cassandra extends this feature to Apache Cassandra by providing an implementation of the org.springframework.dao.support.PersistenceExceptionTranslator interface.

The motivation behind mapping to Spring’s consistent data access exception hierarchy is to let you write portable and descriptive exception handling code without resorting to coding against and handling specific Cassandra exceptions. All of Spring’s data access exceptions are inherited from the DataAccessException class, so you can be sure that you can catch all database-related exceptions within a single try-catch block.

Applications connect to Apache Cassandra by using CqlSession objects. A Cassandra CqlSession keeps track of multiple connections to the individual nodes and is designed to be a thread-safe, long-lived object. Usually, you can use a single CqlSession for the whole application.

Spring acquires a Cassandra CqlSession through a SessionFactory. SessionFactory is part of Spring Data for Apache Cassandra and is a generalized connection factory. It lets the container or framework hide connection handling and routing issues from the application code.

The following example shows how to configure a default SessionFactory:

CqlTemplate and other Template API implementations obtain a CqlSession for each operation. Due to their long-lived nature, sessions are not closed after invoking the desired operation. Responsibility for proper resource disposal lies with the container or framework that uses the session.

You can find various SessionFactory implementations within the org.springframework.data.cassandra.core.cql.session package.

The CassandraTemplate class, located in the org.springframework.data.cassandra package, is the central class in Spring’s Cassandra support and provides a rich feature set to interact with the database. The template offers convenience operations to create, update, delete, and query Cassandra, and provides a mapping between your domain objects and rows in Cassandra tables.

The mapping between rows in Cassandra and application domain classes is done by delegating to an implementation of the CassandraConverter interface. Spring provides a default implementation, MappingCassandraConverter, but you can also write your own custom converter. See the section on Cassandra conversion for more detailed information.

The CassandraTemplate class implements the CassandraOperations interface. In as much as possible, the methods on CassandraOperations are named after methods available in Cassandra to make the API familiar to developers who are already familiar with Cassandra.

For example, you can find methods such as select, insert, delete, and update. The design goal was to make it as easy as possible to transition between the use of the base Cassandra driver and CassandraOperations. A major difference between the two APIs is that CassandraOperations can be passed domain objects instead of CQL and query objects.

The default converter implementation used by CassandraTemplate is MappingCassandraConverter. While MappingCassandraConverter can use additional metadata to specify the mapping of objects to rows, it can also convert objects that contain no additional metadata by using some conventions for the mapping of fields and table names. These conventions, as well as the use of mapping annotations, are explained in the “Mapping” chapter.

Another central feature of CassandraTemplate is exception translation of exceptions thrown in the Cassandra Java driver into Spring’s portable Data Access Exception hierarchy. See the section on exception translation for more information.

CassandraTemplate provides a simple way for you to save, update, and delete your domain objects and map those objects to tables managed in Cassandra.

You can express your queries by using the Query and Criteria classes, which have method names that reflect the native Cassandra predicate operator names, such as lt, lte, is, and others.

The Query and Criteria classes follow a fluent API style so that you can easily chain together multiple method criteria and queries while having easy-to-understand code. Static imports are used in Java when creating Query and Criteria instances to improve readability.

CQL statements that are executed multiple times can be prepared and stored in a PreparedStatement object to improve query performance. Both, the driver and Cassandra maintain a mapping of PreparedStatement queries to their metadata. You can use prepared statements through the following abstractions:

Spring Data for Apache Cassandra requires Apache Cassandra 2.1 or later and Datastax Java Driver 4.0 or later. An easy way to quickly set up and bootstrap a working environment is to create a Spring-based project in STS or use Spring Initializer.

First, you need to set up a running Apache Cassandra server. See the Apache Cassandra Quick Start Guide for an explanation on how to start Apache Cassandra. Once installed, starting Cassandra is typically a matter of running the following command: CASSANDRA_HOME/bin/cassandra -f.

To create a Spring project in STS, go to File → New → Spring Template Project → Simple Spring Utility Project and press Yes when prompted. Then enter a project and a package name, such as org.spring.data.cassandra.example.

Then you can add the following dependency declaration to your pom.xml file’s dependencies section.

Also, you should change the version of Spring in the pom.xml file to be as follows:

If using a milestone release instead of a GA release, you also need to add the location of the Spring Milestone repository for Maven to your pom.xml file so that it is at the same level of your <dependencies/> element, as follows:

The repository is also browseable here.

You can also browse all Spring repositories here.

Now you can create a simple Java application that stores and reads a domain object to and from Cassandra.

To do so, first create a simple domain object class to persist, as the following example shows:

Next, create the main application to run, as the following example shows:

Even in this simple example, there are a few notable things to point out:

A Github repository contains several examples that you can download and play around with to get a feel for how the library works.

One of the first tasks when using Apache Cassandra with Spring is to create a com.datastax.oss.driver.api.core.CqlSession object by using the Spring IoC container. You can do so either by using Java-based bean metadata or by using XML-based bean metadata. These are discussed in the following sections.

The ReactiveCqlTemplate class is the central class in the core CQL package. It handles the creation and release of resources. It performs the basic tasks of the core CQL workflow, such as creating and running statements, leaving application code to provide CQL and extract results. The ReactiveCqlTemplate class runs CQL queries and update statements and performs iteration over ResultSet instances and extraction of returned parameter values. It also catches CQL exceptions and translates them into the generic, more informative, exception hierarchy defined in the org.springframework.dao package.

When you use the ReactiveCqlTemplate in your code, you need only implement callback interfaces, which have a clearly defined contract. Given a Connection, the ReactivePreparedStatementCreator callback interface creates a prepared statement with the provided CQL and any necessary parameter arguments. The RowCallbackHandler interface extracts values from each row of a ReactiveResultSet.

The ReactiveCqlTemplate can be used within a DAO implementation through direct instantiation with a ReactiveSessionFactory reference or be configured in the Spring container and given to DAOs as a bean reference. ReactiveCqlTemplate is a foundational building block for ReactiveCassandraTemplate.

All CQL issued by this class is logged at the DEBUG level under the category corresponding to the fully-qualified class name of the template instance (typically ReactiveCqlTemplate, but it may be different if you use a custom subclass of the ReactiveCqlTemplate class).

The Spring Framework provides exception translation for a wide variety of database and mapping technologies. This has traditionally been for JDBC and JPA. Spring Data for Apache Cassandra extends this feature to Apache Cassandra by providing an implementation of the org.springframework.dao.support.PersistenceExceptionTranslator interface.

The motivation behind mapping to Spring’s consistent data access exception hierarchy is to let you write portable and descriptive exception handling code without resorting to coding against and handling specific Cassandra exceptions. All of Spring’s data access exceptions are inherited from the DataAccessException class, so you can be sure that you can catch all database-related exceptions within a single try-catch block.

ReactiveCqlTemplate and ReactiveCassandraTemplate propagate exceptions as early as possible. Exceptions that occur during the processing of the reactive sequence are emitted as error signals.

The ReactiveCassandraTemplate class, located in the org.springframework.data.cassandra package, is the central class in Spring Data’s Cassandra support. It provides a rich feature set to interact with the database. The template offers convenience data access operations to create, update, delete, and query Cassandra and provides a mapping between your domain objects and Cassandra table rows.

The mapping between rows in a Cassandra table and domain classes is done by delegating to an implementation of the CassandraConverter interface. Spring provides a default implementation, MappingCassandraConverter, but you can also write your own custom converter. See “Mapping” for more detailed information.

The ReactiveCassandraTemplate class implements the ReactiveCassandraOperations interface. As often as possible, the methods names ReactiveCassandraOperations match names in Cassandra to make the API familiar to developers who are familiar with Cassandra.

For example, you can find methods such as select, insert, delete, and update. The design goal was to make it as easy as possible to transition between the use of the base Cassandra driver and ReactiveCassandraOperations. A major difference between the two APIs is that ReactiveCassandraOperations can be passed domain objects instead of CQL and query objects.

The default converter implementation for ReactiveCassandraTemplate is MappingCassandraConverter. While the MappingCassandraConverter can make use of additional metadata to specify the mapping of objects to rows, it can also convert objects that contain no additional metadata by using conventions for the mapping of fields and table names. These conventions, as well as the use of mapping annotations, are explained in “Mapping”.

Another central feature of CassandraTemplate is exception translation. Exceptions thrown by the Cassandra Java driver are translated into Spring’s portable Data Access Exception hierarchy. See “Exception Translation” for more information.

ReactiveCassandraTemplate provides a simple way for you to save, update, and delete your domain objects and map those objects to tables managed in Cassandra.

To access domain entities stored in Apache Cassandra, you can use Spring Data’s sophisticated repository support, which significantly eases implementing DAOs. To do so, create an interface for your repository, as the following example shows:

Note that the entity has a property named id of type String. The default serialization mechanism used in CassandraTemplate (which backs the repository support) regards properties named id as being the row ID.

The following example shows a repository definition to persist Person entities:

Right now, the interface in the preceding example serves only typing purposes, but we add additional methods to it later.

Next, in your Spring configuration, add the following (if you use Java for configuration):

If you want to use Java configuration, use the @EnableCassandraRepositories annotation. The annotation carries the same attributes as the namespace element. If no base package is configured, the infrastructure scans the package of the annotated configuration class. The following example shows how to use the @EnableCassandraRepositories annotation:

If you want to use XML configuration, then the following example shows a minimal configuration snippet:

The cassandra:repositories namespace element causes the base packages to be scanned for interfaces that extend CrudRepository and create Spring beans for each one found. By default, the repositories are wired with a CassandraTemplate Spring bean called cassandraTemplate, so you only need to configure cassandra-template-ref explicitly if you deviate from this convention.

Because our domain repository extends CrudRepository, it provides you with basic CRUD operations. Working with the repository instance is a matter of injecting the repository as a dependency into a client, as the following example does by autowiring PersonRepository:

Cassandra repositories support paging and sorting for paginated and sorted access to the entities. Cassandra paging requires a paging state to forward-only navigate through pages. A Slice keeps track of the current paging state and allows for creation of a Pageable to request the next page. The following example shows how to set up paging access to Person entities:

The preceding example creates an application context with Spring’s unit test support, which performs annotation-based dependency injection into the test class. Inside the test cases (the test methods), we use the repository to query the data store. We invoke the repository query method that requests all Person instances.

Most of the data access operations you usually trigger on a repository result in a query being executed against the Apache Cassandra database. Defining such a query is a matter of declaring a method on the repository interface. The following example shows a number of such method declarations:

The following table shows short examples of the keywords that you can use in query methods:

The keywords in the preceding table can be used in conjunction with delete…By to create queries that delete matching documents.

Delete queries return whether the query was applied or terminate without returning a value using void.

Unresolved directive in reference/cassandra-repositories.adoc - include::../../../../../../spring-data-commons/src/main/asciidoc/repository-projections.adoc[leveloffset=+2]

The reactive space offers various reactive composition libraries. The most common libraries are RxJava and Project Reactor.

Spring Data for Apache Cassandra is built on top of the DataStax Cassandra Driver. The driver is not reactive but the asynchronous capabilities allow us to adopt and expose the Publisher APIs to provide maximum interoperability by relying on the Reactive Streams initiative. Static APIs, such as ReactiveCassandraOperations, are provided by using Project Reactor’s Flux and Mono types. Project Reactor offers various adapters to convert reactive wrapper types (Flux to Observable and back), but conversion can easily clutter your code.

Spring Data’s repository abstraction is a dynamic API that is mostly defined by you and your requirements as you declare query methods. Reactive Cassandra repositories can be implemented by using either RxJava or Project Reactor wrapper types by extending from one of the library-specific repository interfaces:

Spring Data converts reactive wrapper types behind the scenes so that you can stick to your favorite composition library.

To access domain entities stored in Apache Cassandra, you can use Spring Data’s sophisticated repository support, which significantly eases implementing DAOs. To do so, create an interface for your repository, as the following example shows:

Note that the entity has a property named id of type String. The default serialization mechanism used in CassandraTemplate (which backs the repository support) regards properties named id as being the row ID.

The following example shows a repository definition to persist Person entities:

For Java configuration, use the @EnableReactiveCassandraRepositories annotation. The annotation carries the same attributes as the corresponding XML namespace element. If no base package is configured, the infrastructure scans the package of the annotated configuration class. The following example uses the @EnableReactiveCassandraRepositories annotation:

Since our domain repository extends ReactiveSortingRepository, it provides you with CRUD operations as well as methods for sorted access to the entities. Working with the repository instance is a matter of dependency injecting it into a client, as the following example shows:

Cassandra repositories support paging and sorting for paginated and sorted access to the entities. Cassandra paging requires a paging state to forward-only navigate through pages. A Slice keeps track of the current paging state and allows for creation of a Pageable to request the next page. The following example shows how to set up paging access to Person entities:

The preceding example creates an application context with Spring’s unit test support, which performs annotation-based dependency injection into the test class. Inside the test cases (the test methods), we use the repository to query the data store. We invoke the repository query method that requests all Person instances.

Spring Data’s Reactive Cassandra support comes with the same set of features as the support for imperative repositories.

It supports the following features:

Unresolved directive in index.adoc - include::../../../../../spring-data-commons/src/main/asciidoc/auditing.adoc[leveloffset=+1] :leveloffset: +1

This section explains how types are mapped to and from an Apache Cassandra representation.

Spring Data for Apache Cassandra supports several types that are provided by Apache Cassandra. In addition to these types, Spring Data for Apache Cassandra provides a set of built-in converters to map additional types. You can provide your own custom converters to adjust type conversion. See “Overriding Default Mapping with Custom Converters” for further details. The following table maps Spring Data types to Cassandra types:

Each supported type maps to a default Cassandra data type. Java types can be mapped to other Cassandra types by using @CassandraType, as the following example shows:

MappingCassandraConverter uses a few conventions for mapping domain objects to CQL tables when no additional mapping metadata is provided. The conventions are:

You can adjust conventions by configuring a NamingStrategy on CassandraMappingContext. Naming strategy objects implement the convention by which a table, column or user-defined type is derived from an entity class and from an actual property.

The following example shows how to configure a NamingStrategy:

To take full advantage of the object mapping functionality inside the Spring Data for Apache Cassandra support, you should annotate your mapped domain objects with the @Table annotation. Doing so lets the classpath scanner find and pre-process your domain objects to extract the necessary metadata. Only annotated entities are used to perform schema actions. In the worst case, a SchemaAction.RECREATE_DROP_UNUSED operation drops your tables and you lose your data. The following example shows a simple domain object:

To have more fine-grained control over the mapping process, you can register Spring Converters with CassandraConverter implementations, such as MappingCassandraConverter.

MappingCassandraConverter first checks to see whether any Spring Converters can handle a specific class before attempting to map the object itself. To "'hijack'" the normal mapping strategies of the MappingCassandraConverter (perhaps for increased performance or other custom mapping needs), you need to create an implementation of the Spring Converter interface and register it with the MappingCassandraConverter.

The Cassandra mapping framework has several built-in org.springframework.context.ApplicationEvent events that your application can respond to by registering special beans in the ApplicationContext. Being based on Spring’s application context event infrastructure lets other products, such as Spring Integration, easily receive these events as they are a well known eventing mechanism in Spring-based applications.

To intercept an object before it goes into the database, you can register a subclass of org.springframework.data.cassandra.core.mapping.event.AbstractCassandraEventListener that overrides the onBeforeSave(…) method. When the event is dispatched, your listener is called and passed the domain object (which is a Java entity). The following example uses the onBeforeSave method:

Declaring these beans in your Spring ApplicationContext will cause them to be invoked whenever the event is dispatched.

The AbstractCassandraEventListener has the following callback methods:

Unresolved directive in reference/mapping.adoc - include::../../../../../../spring-data-commons/src/main/asciidoc/entity-callbacks.adoc[leveloffset=+1] :leveloffset: +2

Spring CQL and Spring Data Cassandra are now merged into a single module. The standalone spring-cql module is no longer available. You can find all types merged into spring-data-cassandra. The following listing shows how to include spring-data-cassandra in your maven dependencies:

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

We split CqlTemplate and CassandraTemplate in three 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, as the following example shows:

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

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

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

As much as possible, CQL specification types are now value types (such as FieldSpecification, AlterColumnSpecification), and objects are constructed by static factory methods. This allows immutability for simple value objects. Configurator objects (such as AlterTableSpecification) that operate on mandatory properties (such as a table name or 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. The following example shows how to use QueryOptions.builder():

This change affects You only if you operate directly on the mapping model.

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 map to a class through MappingContext.getRequiredPersistentEntity(…).

Upgrading to Spring Data Cassandra requires an upgrade to the DataStax Driver version 4. Upgrading to the new driver comes with transitive dependency changes, most notably, Google Guava is bundled and shaded by the driver. Check out the DataStax Java Driver for Apache Cassandra 4 Upgrade Guide for details on the Driver-related changes.

DataStax Java Driver 4 merges Cluster and Session objects into a single CqlSession object, therefore, all Cluster-related API was removed. The configuration was revised in large parts by removing most configuration items that were moved into DriverConfigLoader that is mostly file-based. This means that SocketOptions, AddressTranslator and many more options are configured now through other means.

If you’re using XML-based configuration, make sure to migrate all configuration files from the cql namespace (http://www.springframework.org/schema/cql https://www.springframework.org/schema/cql/spring-cql.xsd) to the cassandra namespace (http://www.springframework.org/schema/data/cassandra https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd).

To reflect the change in configuration builders, ClusterBuilderConfigurer was renamed to SessionBuilderConfigurer accepting now CqlSessionBuilder instead of the Cluster.Builder. Make sure to also provide the local data center in your configuration as it is required to properly configure load balancing.

Spring Data for Apache Cassandra encapsulates most of the changes that come with the driver upgrade as the Template API and repository support if your application mainly interacts with mapped entities or primitive Java types.

We generally recommend to create CqlTemplate and CassandraTemplate objects by using SessionFactory as the factory usage allows synchronization for schema creation and introduces a level of flexibility when working with multiple databases.

You will have to adapt your code in all places, where you use DataStax driver API directly. Typical cases include:

Your data model may require updates if you use the following features: