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.

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

Example with bare minimum config

		final String clusterName = "myCluster";
		final String keyspaceName = "myKeyspace";
		
		final String SEEDS = "localhost";
		final Supplier<List<Host>> HostSupplier = new Supplier<List<Host>>() {

			@Override
			public List<Host> get() {
				Host host = new Host(SEEDS, 9160);
				return Collections.singletonList(host);
			}
		};

		AstyanaxContext<Keyspace> context = new AstyanaxContext.Builder()
		.forCluster(clusterName)
		.forKeyspace(keyspaceName)
		.withHostSupplier(HostSupplier)
		.withAstyanaxConfiguration(
				new AstyanaxConfigurationImpl()
				.setDiscoveryType(NodeDiscoveryType.DISCOVERY_SERVICE)
				.setDiscoveryDelayInSeconds(60000)
		)
		.withConnectionPoolConfiguration(
				new JavaDriverConfigBuilder()
				.build())
		.buildKeyspace(CqlFamilyFactory.getInstance());
		
		Keyspace keyspace = context.getClient();
	

Note the critical config that was used in the example above. Ensure that at a bare minimum, you have the following specified

• Cluster and Keyspace name
• HostSupplier object along with NodeDiscoveryType telling Astyanax to use the HostSupplier
• JavaDriverConfigBuilder for the basic default config for Java Driver (Note that Astyanax does not use any of it's own defaults. It will use the Java Driver defaults directly)
• Lastly CqlFamilyFactory telling Astyanax to switch to the astyanax-cql impl for the driver underneath

See Java-Driver-Configuration for more examples on all Java Driver configuration details.

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.

Reads / Queries - how to use PreparedStatements for better performance

Writes / Mutations - how to use PreparedStatements for better performance

Examples

Simple ColumnFamily definition

ColumnFamily with composite columns

Regular flat table style ColumnFamily