(Quick Reference)

Astyanax Cassandra Client - Reference Documentation

Authors: Bob Florian

Version: 0.2.0

1 Cassandra Astyanax Plugin

The Cassandra Astyanax Plugin simplifies integration of the Netflix developed Astyanax Cassandra client into a Grails application. In addition to encapsulating the client into a Grails service the plugin adds several dynamic methods that make using the client from the Groovy language more convenient for typical use cases.

1.1 Getting Started

The plugin supports any number of Cassandra clusters, which may have different connection pool implementations, default consistency levels, and retry policies. To create a simple configuration with one cluster add the following to your project's Config.groovy file:

astyanax {
    clusters {
        standard {
            seeds = ["localhost:9160"]
            defaultKeyspace = "AstyanaxTest"
        }
    }
    defaultCluster = 'standard'
}

Calling Cassandra with the default cluster and keyspace (the "standard" cluster and "AstyanaxTest" keyspace in this case) would then look like:

astyanaxService.keyspace().prepareQuery("Standard1")
        .getKey("some-row-key")
        .execute()
        .result

Alternately, you can pass the keyspace context to a closure, for example:

astyanaxService.withKeyspace {keyspace ->
    keyspace.prepareQuery("Standard1")
            .getKey("some-row-key")
            .execute()
            .result
}

The above examples query the Standard1 column family using the StringSerializer for both the row key and column serializer (the plugin's default). You can also specify different serializers:

astyanaxService.keyspace().prepareQuery(new ColumnFamily("Standard1", StringSerializer.get(), LongSerializer.get()))
        .getKey("some-row-key")
        .execute()
        .result

You can also specify a different keyspace:

astyanaxService.keyspace("AstyanaxTest2").prepareQuery("Standard2")
        .getKey("some-row-key")
        .execute()
        .result

To access a second cluster, add it to the config:

astyanax {
    clusters {
        standard {
            seeds = ["localhost:9160"]
            defaultKeyspace = "AstyanaxTest"
        }
        anotherCluster {
            seeds = ["111.222.333.444:9160"]
        }
    }
    defaultCluster = 'standard'
}

You call the second cluster as follows:

astyanaxService.keyspace("TheKeyspace", "anotherCluster").prepareQuery("TestCF1")
        .getKey("some-row-key")
        .execute()
        .result

1.2 Configuration Options

The complete set of configuration options supported by the plugin (with their default values) are shown in the following configuration:

astyanax {
    clusters {
        standard {
            seeds = ["localhost:9160"]
            defaultKeyspace = "AstyanaxTest"
            port = 9160
            maxConsPerHost = 10
            retryCount = 3
            connectionPoolMonitor = new com.netflix.astyanax.connectionpool.impl.CountingConnectionPoolMonitor()
            discoveryType = com.netflix.astyanax.connectionpool.NodeDiscoveryType.NONE
            retryPolicy = new com.netflix.astyanax.retry.RetryNTimes(3)
            connectionPoolName = "MyConnectionPool"
            defaultReadConsistencyLevel = "CL_ONE"
            defaultWriteConsistencyLevel = "CL_ONE"
        }
    }
    defaultCluster = 'standard'
}

PropertyRequiredMeaning
seedsyesArray of node strings of the form "host:port" that Astyanax will use in quering Cassandra
defaultKeyspacenoName of the keyspace to use if one is not specified in the service call
portnoPort number used for communicating to Cassandra nodes. Defaults to 9160.
maxConsPerHostnoThe maximum number of connections to be created for any one node. Defaults to 10.
retryCountnoThe number of times Astyanax will retry a call before failing. Has not effect if the retryPolicy property is set. Defaults to 3.
connectionPoolMonitornoThe connection pool monitor implementation. Defaults to new com.netflix.astyanax.connectionpool.impl.CountingConnectionPoolMonitor
discoveryTypenoThe method of discovering new nodes. Defaults to NONE (no discovery). Other values are RING_DESCRIBE, DISCOVERY_SERVICE, and TOKEN_AWARE
retryPolicynoThe retry policy to use. Defaults to RetryNTimes. Others values include RunOnce, ConstantBackoff, ExponentialBackoff, BoundedExponentialBackoff, and SleepingRetryPolicy
connectionPoolNamenoName used to identify the connection pool. Defaults to the astyanax.clusters configuration key, i.e. "standard" in this example
defaultReadConsistencyLevelnoDefault consistency level used when reading from the cluster. This value can be overwritten on the Query operations.
defaultWriteConsistencyLevelnoDefault consistency level used when reading from the cluster. This value can be overwritten on MutationBatch operation

1.3 Dynamic Methods Added

The Cassandra Astyanax plugin adds a number of methods to the standard Astyanax classes to make them more convenient to use from the Groovy language.

ColumnFamilyQuery Keyspace.prepareQuery(String columnFamily, rowKey, column)

Prepares a column family query using the default row and column serializer.

ColumnListMutation MutationBatch.withRow(String columnFamily, rowKey)

Prepares a column list mutation using the default row and column serializer.

Map<Object, Map<Object, Column>> Rows.toMap()

Returns a two-level nested map where the row key is the key of the outer map, the column name is the key of the inner map, and the Column object is the value of the inner map.

Map<Object, Map<Object, String>> Rows.toStringMap()

Returns a two-level nested map where the row key is the key of the outer map, the column name is the key of the inner map, and the Column stringValue is the value of the inner map.

Map<Object, Map<Object, Long>> Rows.toStringMap()

Returns a two-level nested map where the row key is the key of the outer map, the column name is the key of the inner map, and the Column longValue is the value of the inner map.

Map<Object, Column> AbstractColumnList.toMap()

Returns a map with the column name as the key and the Column object as the value

Map<Object, String> AbstractColumnList.toStringMap()

Returns a map with the column name as the key and the Column stringValue as the value

Map<Object, Long> AbstractColumnList.toLongMap()

Returns a map with the column name as the key and the Column longValue as the value

ColumnMutation Keyspace.prepareColumnMutation(String columnFamily, rowKey, column)

Prepares a column mutation using the default row and column serializer.

Execution ColumnMutation.putValue(value)

Adds the specified value to the column mutation with no time-to-live.

ColumnListMutation ColumnListMutation.putColumn(name, value)

Adds a column with the specified name and value to the column mutation with no time-to-live.

ColumnListMutation ColumnListMutation.putColumns(Map map)

Adds a column for each enry in the map, where the column name is the map key and the column value the map value, with no time-to-live.

ColumnListMutation ColumnListMutation.incrementCounterColumn(name, value = 1)

Increments the value of a counter column by the specified value, or by 1 if the value isn't specified.

ColumnListMutation ColumnListMutation.incrementCounterColumns(Map map)

Increments the value of a counter for each entry in the map, where the column name is the map key and the increment is the map value, or 1 if the map value is null.