Astyanax over Java Driver

Highly recommended readings

• Astyanax blog post in Dec 2013 - This describes what the integration between Astyanax and Java-Driver is all about.
• Schema in Cassandra 1.1 - decent intro to schema basics, dynamic columns, clustering keys etc
• What's new in CQL3 - info on how CQL3 deals with composite keys
• CQL3 for cassandra experts - info on how rows are structured at the storage level and how rows and columns are transposed to CQL3 rows.
• Thrift to CQL3 - another guide on how to use dynamic columns

Note - this is a BETA release only!

Java-Driver does some of the heavy lifting like load balancing and connection pooling and also provides some neat features such as cursor support and async requests. But note that thrift and CQL3 have several differences.

Building and supporting a unified API that straddles both drivers (thrift and Java Driver) is challenging and sometimes not feasible. Hence please review your use case to see if it is supported by this driver.

We have listed the caveats below along with several examples with the different types of schemas that are supported by the implementation.

What about my use case?

We've listed examples for different schemas below. If your schema does not fit the model, then you can work with us on getting support for it. Start with filing an issue and we can then discuss your use case. We also encourage sending pull requests as well!

How to select the right release / code branch

There are 2 main code branches and release versions for Astyanax - master and beta-java-driver

• master is the current main development branch and only supports the thrift based driver
• beta-java-driver is the branch which uses Java Driver. It also has all the code for the thrift based driver and hence is a superset of the master branch.

Astyanax also has 2 library versions that correspond to the 2 branches

• astyanax-1.x.x which comes from master
• astyanax-2.0.x-beta which comes from beta-java-driver

Any updates to the master branch (thrift based changes) will be ported forward to the beta-java-driver branch. The short term goal is to make it explicitly clear to consumers what code they are using and the longer term goal is to have just one master branch (if possible) that has both drivers supported.

Start with setting up your keyspace context

You need some bare minimum config/setup for using Astyanax over Java-Driver. See See Java-Driver-Configuration for examples on basic setup and all other Java Driver configuration details.

Caveats / changes / considerations

ColumnFamily object needs ColumnFamilyDefinition

Astyanax queries are translated to CQL3 queries and submitted to the Java Driver for execution. In order to accurately generate the CQL3 query, Astyanax needs to know the table schema i.e ColumnFamilyDefinition. You can easily do this using the example below.

	Keyspace keyspace = context.getClient();
		
	ColumnFamily<String, Long> CF = 
	new ColumnFamily<String, Long>("myCF", 
                                       StringSerializer.get(), 
                                       LongSerializer.get(), 
                                       StringSerializer.get());

	CF.describe(keyspace);

Important Note - the CF definition is needed for running every query and is cached with the CF object. Hence re-use the CF object for all your queries and hence you won't need to read the CF definition on subsequent queries.

Can I just use CQL3 directly?

Yes you can. Astyanax has it's own structured API, but will also let the user specify CQL3 directly. See Java-Driver-direct-CQL3 for detailed examples on how to do this.

How to use PreparedStatements for better performance

Java-Driver has better performance with the use of PreparedStatements. This necessitates statement/query management from the client. Astyanax can help here. See Java-Driver-Prepared-Statements for details on how to enable automatic generation and caching of PreparedStatements and also the caveats with this feature.

Are columns rows or are they columns !!??

Answer to both questions is yes :) See Java-Driver-Rows-vs-Columns for details on what CQL3 rows and columns look like and how Astyanax addresses this issue.

Indexes are not supported.

Unfortunately, the API implementation does not yet support indexing. We plan on adding support for this in the near future. In the meantime you could still use direct CQL3 with indexing to support your use case.

Supported Use Cases and Examples

Simple ColumnFamily with named columns

ColumnFamily with single clustering key e.g Time Series

ColumnFamily with composite columns