Mapping

Rich object mapping support is provided by the MappingCassandraConverter. MappingCassandraConverter has a rich metadata model that provides a complete feature set of functionality to map domain objects to CQL tables.

The mapping metadata model is populated by using annotations on your domain objects. However, the infrastructure is not limited to using annotations as the only source of metadata. The MappingCassandraConverter also lets you map domain objects to tables without providing any additional metadata, by following a set of conventions.

In this chapter, we describe the features of the MappingCassandraConverter, how to use conventions for mapping domain objects to tables, and how to override those conventions with annotation-based mapping metadata.

../{spring-data-commons-docs}/object-mapping.adoc

Data Mapping and Type Conversion

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 “[cassandra.custom-converters]” for further details. The following table maps Spring Data types to Cassandra types:

Table 1. Type

Type	Cassandra types
`String`	`text` (default), `varchar`, `ascii`
`double`, `Double`	`double`
`float`, `Float`	`float`
`long`, `Long`	`bigint` (default), `counter`
`int`, `Integer`	`int`
`short`, `Short`	`smallint`
`byte`, `Byte`	`tinyint`
`boolean`, `Boolean`	`boolean`
`BigInteger`	`varint`
`BigDecimal`	`decimal`
`java.util.Date`	`timestamp`
`com.datastax.driver.core.LocalDate`	`date`
`InetAddress`	`inet`
`ByteBuffer`	`blob`
`java.util.UUID`	`uuid`
`TupleValue`, mapped Tuple Types	`tuple<…>`
`UDTValue`, mapped User-Defined Types	user type
`java.util.Map<K, V>`	`map`
`java.util.List<E>`	`list`
`java.util.Set<E>`	`set`
`Enum`	`text` (default), `bigint`, `varint`, `int`, `smallint`, `tinyint`
`LocalDate` (Joda, Java 8, JSR310-BackPort)	`date`
`LocalTime`+ (Joda, Java 8, JSR310-BackPort)	`time`
`LocalDateTime`, `LocalTime`, `Instant` (Joda, Java 8, JSR310-BackPort)	`timestamp`
`ZoneId` (Java 8, JSR310-BackPort)	`text`

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:

Example 1. Enum mapping to numeric types

@Table
public class EnumToOrdinalMapping {

  @PrimaryKey String id;

  @CassandraType(type = Name.INT) Condition asOrdinal;
}

public enum Condition {
  NEW, USED
}

Convention-based Mapping

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

The simple (short) Java class name is mapped to the table name by being changed to lower case. For example, com.bigbank.SavingsAccount maps to a table named savingsaccount.
The converter uses any registered Spring Converter instances to override the default mapping of object properties to tables columns.
The properties of an object are used to convert to and from columns in the table.

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:

Example 2. Configuring NamingStrategy on CassandraMappingContext

link:../{example-root}/NamingStrategyConfiguration.java[]

Mapping Configuration

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

Also, by creating your own instance, you can register Spring Converter instances to use for mapping specific classes to and from the database. The following example configuration class sets up Cassandra mapping support:

Example 3. @Configuration class to configure Cassandra mapping support

link:../{example-root}/SchemaConfiguration.java[]

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

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

Note	`AbstractCassandraConfiguration` creates a `CassandraTemplate` instance and registers it with the container under the name of `cassandraTemplate`.

Metadata-based Mapping

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:

Example 4. Example domain object

package com.mycompany.domain;

@Table
public class Person {

  @Id
  private String id;

  @CassandraType(type = Name.VARINT)
  private Integer ssn;

  private String firstName;

  private String lastName;
}

Important

The @Id annotation tells the mapper which property you want to use for the Cassandra primary key. Composite primary keys can require a slightly different data model.

Working with Primary Keys

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.

Simple Primary Keys

A simple primary key consists of one partition key field within an entity class. Since it is one field only, we safely can assume it is a partition key. The following listing shows a CQL table defined in Cassandra with a primary key of user_id:

Example 5. CQL Table defined in Cassandra

CREATE TABLE user (
  user_id text,
  firstname text,
  lastname text,
  PRIMARY KEY (user_id))
;

The following example shows a Java class annotated such that it corresponds to the Cassandra defined in the previous listing:

Example 6. Annotated Entity

@Table(value = "login_event")
public class LoginEvent {

  @PrimaryKey("user_id")
  private String userId;

  private String firstname;
  private String lastname;

  // getters and setters omitted

}

Composite Keys

Composite primary keys (or compound keys) consist of more than one primary key field. That said, a composite primary key can consist of multiple partition keys, a partition key and a clustering key, or a multitude of primary key fields.

Composite keys can be represented in two ways with Spring Data for Apache Cassandra:

Embedded in an entity.
By using @PrimaryKeyClass.

The simplest form of a composite key is a key with one partition key and one clustering key.

The following example shows a CQL statement to represent the table and its composite key:

Example 7. CQL Table with a Composite Primary Key

CREATE TABLE login_event(
  person_id text,
  event_code int,
  event_time timestamp,
  ip_address text,
  PRIMARY KEY (person_id, event_code, event_time))
  WITH CLUSTERING ORDER BY (event_time DESC)
;

Flat Composite Primary Keys

Flat composite primary keys are embedded inside the entity as flat fields. Primary key fields are annotated with @PrimaryKeyColumn. Selection requires either a query to contain predicates for the individual fields or the use of MapId. The following example shows a class with a flat composite primary key:

Example 8. Using a flat composite primary key

link:../{example-root}/LoginEvent.java[]

Primary Key Class

A primary key class is a composite primary key class that is mapped to multiple fields or properties of the entity. It is annotated with @PrimaryKeyClass and should define equals and hashCode methods. The semantics of value equality for these methods should be consistent with the database equality for the database types to which the key is mapped. Primary key classes can be used with repositories (as the Id type) and to represent an entity’s identity in a single complex object. The following example shows a composite primary key class:

Example 9. Composite primary key class

link:../{example-root}/LoginEventKey.java[]

The following example shows how to use a composite primary key:

Example 10. Using a composite primary key

@Table(value = "login_event")
public class LoginEvent {

  @PrimaryKey
  private LoginEventKey key;

  @Column("ip_address")
  private String ipAddress;

  // getters and setters omitted
}

Embedded Entity Support

Embedded entities are used to design value objects in your Java domain model whose properties are flattened out into the table. In the following example you see, that User.name is annotated with @Embedded. The consequence of this is that all properties of UserName are folded into the user table which consists of 3 columns (user_id, firstname, lastname).

Note	Embedded entities may only contain simple property types. It is not possible to nest an embedded entity into another embedded one.

However, if the firstname and lastname column values are actually null within the result set, the entire property name will be set to null according to the onEmpty of @Embedded, which nulls objects when all nested properties are null.
Opposite to this behavior USE_EMPTY tries to create a new instance using either a default constructor or one that accepts nullable parameter values from the result set.

Example 11. Sample Code of embedding objects

public class User {

	@PrimaryKey("user_id")
    private String userId;

    @Embedded(onEmpty = USE_NULL) (1)
    UserName name;
}

public class UserName {
    private String firstname;
    private String lastname;
}

Property is null if firstname and lastname are null. Use onEmpty=USE_EMPTY to instantiate UserName with a potential null value for its properties.

You can embed a value object multiple times in an entity by using the optional prefix element of the @Embedded annotation. This element represents a prefix and is prepended to each column name in the embedded object. Note that properties will overwrite each other if multiple properties render to the same column name.

Tip

Make use of the shortcuts @Embedded.Nullable and @Embedded.Empty for @Embedded(onEmpty = USE_NULL) and @Embedded(onEmpty = USE_EMPTY) to reduce verbosity and simultaneously set JSR-305 @javax.annotation.Nonnull accordingly.

public class MyEntity {

    @Id
    Integer id;

    @Embedded.Nullable (1)
    EmbeddedEntity embeddedEntity;
}

Shortcut for @Embedded(onEmpty = USE_NULL).

Mapping Annotation Overview

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

@Id: Applied at the field or property level to mark the property used for identity purposes.
@Table: Applied at the class level to indicate that this class is a candidate for mapping to the database. You can specify the name of the table where the object is stored.
@PrimaryKey: Similar to @Id but lets you specify the column name.
@PrimaryKeyColumn: Cassandra-specific annotation for primary key columns that lets you specify primary key column attributes, such as for clustered or partitioned. Can be used on single and multiple attributes to indicate either a single or a composite (compound) primary key. If used on a property within the entity, make sure to apply the @Id annotation as well.
@PrimaryKeyClass: Applied at the class level to indicate that this class is a compound primary key class. Must be referenced with @PrimaryKey in the entity class.
@Transient: By default, all private fields are mapped to the row. This annotation excludes the field where it is applied from being stored in the database. Transient properties cannot be used within a persistence constructor as the converter cannot materialize a value for the constructor argument.
@PersistenceConstructor: Marks a given constructor — even a package protected one — to use when instantiating the object from the database. Constructor arguments are mapped by name to the key values in the retrieved row.
@Value: This annotation is part of the Spring Framework . Within the mapping framework it can be applied to constructor arguments. This lets you use a Spring Expression Language statement to transform a key’s value retrieved in the database before it is used to construct a domain object. In order to reference a property of a given Row/UdtValue/TupleValue one has to use expressions like: @Value("#root.getString(0)") where root refers to the root of the given document.
@ReadOnlyProperty: Applies at the field level to mark a property as read-only. Entity-bound insert and update statements do not include this property.
@Column: Applied at the field level. Describes the column name as it is represented in the Cassandra table, thus letting the name differ from the field name of the class. Can be used on constructor arguments to customize the column name during constructor creation.
@Embedded: Applied at the field level. Enables embedded object usage for types mapped to a table or a user-defined type. Properties of the embedded object are flattened into the structure of its parent.
@Indexed: Applied at the field level. Describes the index to be created at session initialization.
@SASI: Applied at the field level. Allows SASI index creation during session initialization.
@CassandraType: Applied at the field level to specify a Cassandra data type. Types are derived from the property declaration by default.
@Frozen: Applied at the field level to class-types and parametrized types. Declares a frozen UDT column or frozen collection like List<@Frozen UserDefinedPersonType>.
@UserDefinedType: Applied at the type level to specify a Cassandra User-defined Data Type (UDT). Types are derived from the declaration by default.
@Tuple: Applied at the type level to use a type as a mapped tuple.
@Element: Applied at the field level to specify element or field ordinals within a mapped tuple. Types are derived from the property declaration by default. Can be used on constructor arguments to customize tuple element ordinals during constructor creation.
@Version: Applied at field level is used for optimistic locking and checked for modification on save operations. The initial value is zero which is bumped automatically on every update.

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

The following example shows a more complex mapping:

Example 12. Mapped Person class

link:../{example-root}/mapping/Person.java[]

The following example shows how to map a UDT Address:

Example 13. Mapped User-Defined Type Address

link:../{example-root}/mapping/Address.java[]

Note	Working with User-Defined Types requires a `UserTypeResolver` that is configured with the mapping context. See the configuration chapter for how to configure a `UserTypeResolver`.

The following example shows how map a tuple:

Example 14. Mapped Tuple

link:../{example-root}/mapping/Coordinates.java[]

Index Creation

You can annotate particular entity properties with @Indexed or @SASI if you wish to create secondary indexes on application startup. Index creation creates simple secondary indexes for scalar types, user-defined types, and collection types.

You can configure a SASI Index to apply an analyzer, such as StandardAnalyzer or NonTokenizingAnalyzer (by using @StandardAnalyzed and @NonTokenizingAnalyzed, respectively).

Map types distinguish between ENTRY, KEYS, and VALUES indexes. Index creation derives the index type from the annotated element. The following example shows a number of ways to create an index:

Example 15. Variants of map indexing

link:../{example-root}/mapping/PersonWithIndexes.java[]

Note	The `@Indexed` annotation can be applied to single properties of embedded entities or along side with the `@Embedded` annotation, in which case all properties of the embedded are indexed.

Caution

Index creation on session initialization may have a severe performance impact on application startup.

./converters.adoc

../{spring-data-commons-docs}/is-new-state-detection.adoc

Note

Cassandra provides no means to generate identifiers upon inserting data. As consequence, entities must be associated with identifier values. Spring Data defaults to identifier inspection to determine whether an entity is new. If you want to use auditing make sure to either use [cassandra.template.optimistic-locking] or implement Persistable for proper entity state detection.

Lifecycle Events

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). Entity lifecycle events can be costly and you may notice a change in the performance profile when loading large result sets. You can disable lifecycle events on the Template API. The following example uses the onBeforeSave method:

link:../{example-root}/mapping/BeforeSaveListener.java[]

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:

onBeforeSave: Called in CassandraTemplate.insert(…) and .update(…) operations before inserting or updating a row in the database.
onAfterSave: Called in CassandraTemplate…insert(…) and .update(…) operations after inserting or updating a row in the database.
onBeforeDelete: Called in CassandraTemplate.delete(…) operations before deleting row from the database.
onAfterDelete: Called in CassandraTemplate.delete(…) operations after deleting row from the database.
onAfterLoad: Called in the CassandraTemplate.select(…), .slice(…), and .stream(…) methods after each row is retrieved from the database.
onAfterConvert: Called in the CassandraTemplate.select(…), .slice(…), and .stream(…) methods after converting a row retrieved from the database to a POJO.

Note	Lifecycle events are emitted only for root-level types. Complex types used as properties within an aggregate root are not subject to event publication.

../{spring-data-commons-docs}/entity-callbacks.adoc ./cassandra-entity-callbacks.adoc

spring-data-cassandra/src/main/asciidoc/reference/mapping.adoc