Hibernate.orgCommunity Documentation

Chapter 14. Cassandra (Experimental)

14.1. Configuring Cassandra
14.1.1. Adding Cassandra dependencies
14.1.2. Cassandra specific configuration properties
14.2. Storage principles
14.2.1. Properties and built-in types
14.3. Transactions and Concurrency
14.4. Native queries

Cassandra is a distributed column family database.

This implementation uses CQL3 over the native wire protocol with java-driver. The currently supported version is Cassandra 2.1.

Note

Support for Cassandra is considered an EXPERIMENTAL feature of this release.

Should you find any bugs or have feature requests for this dialect, then please open a ticket in the OGM issue tracker.

14.1. Configuring Cassandra

Configuring Hibernate OGM to use Cassandra is easy:

To add the dependencies via Maven, add the following module:

<dependency>
    <groupId>org.hibernate.ogm</groupId>
    <artifactId>hibernate-ogm-cassandra</artifactId>
    <version>5.0.4.Final</version>
</dependency>

This will pull the Cassandra Java driver transparently.

If you’re not using a dependency management tool, copy all the dependencies from the distribution in the directories:

To get started you will need to configure the following properties:

Cassandra datastore configuration properties

hibernate.ogm.datastore.provider
To use Cassandra as a datastore provider, this property must be set to cassandra_experimental
hibernate.ogm.datastore.host

The hostname and port of the Cassandra instance. The optional port is concatenated to the host and separated by a colon. Let’s see a few valid examples:

hibernate.ogm.datastore.port
Deprecated: use hibernate.ogm.datastore.host. The port used by the Cassandra instance. Ignored when multiple hosts are defined. The default value is 9042.
hibernate.ogm.datastore.database
The database to connect to. This property has no default value.
hibernate.ogm.datastore.username
The username used when connecting to the Cassandra server. This property has no default value.
hibernate.ogm.datastore.password
The password used to connect to the Cassandra server. This property has no default value.

14.2. Storage principles

Each Entity type maps to one Cassandra table. Each Entity instance maps to one CQL3 row of the table, each property of the Entity being one CQL3 column.

CQL3 table and column names are always quoted to preserve case consistency with the Java layer, with the table name matching the Entity class and the column names matching the Entity’s properties. The @Table and @Column annotations can be used to override identifier names in the usual manner.

Embedded objects are stored as additional columns in the owning Entitie’s table. The columns are named as EmbeddedTypeName.FieldOfEmbeddedType The type and field names can be overridden by annotations, but concatenation token delimiter cannot.

CQL3 types

CQL3 supports a smaller selection of numeric data types than Hibernate, so the missing types are automatically converted. byte and short values are promoted to integer. java.math.BigDecimal is converted to decimal.

CQL3 has no character type, so character is promoted to varchar i.e. String. Strings are UTF-8, not ascii.

CQL3 does not distinguish between byte[] and BLOB types for binary storage. These are handled equivalently.

CQL3 does not have a Calendar type, so these are converted to Dates, which are stores as time offset from the unix epoch.

You can assign id values yourself or let Hibernate OGM generate the value using the @GeneratedValue annotation.

The preferred identifier approach in Cassandra is to use UUIDs.

Cassandra does not natively support sequences (auto increment identifiers) at present. This approach is supported though use of an additional table to store sequence state, but incurs additional access overheads that make it undesirable for tables with frequent inserts.

14.3. Transactions and Concurrency

Cassandra does not support transactions. Changes to a single Entity are atomic. Changes to more than one entity are neither atomic nor isolated.

Cassandra does not distinguish between update and insert operations and will not prevent creation of an Entity with duplicate Id, instead treating it as modification of the existing Entity.

14.4. Native queries

Native queries are supported: you can execute native CQL queries using the EntityManager infrastructure.

Currently, only ordinal parameters are supported, named parameters do not work.

Example 14.1. Using native CQL queries

Query query = em.createNativeQuery( "SELECT * FROM \"WILDE_POEM\" WHERE name = ?" );
query.setParameter( 1, "Portia" ); // CQL parameters positions start at 1
List<OscarWildePoem> results = query.getResultList();

Warning

Unlike in JPQL, in CQL, parameters positions start at 1, not 0.