News

  • Check download section, new support for 1.0. Documentation still not updated, it will be soon.
  • Follow us on tweeter to get updates @Aquiles4Net

Description

Aquiles is a .NET (v3.5 or above) Client for Apache Cassandra version 0.6.X or above using Thrift API.

Basically, It adds:
  • A .NET friendly interface to cassandra operations. You operates against cassandra as you would operate against an SQL (See examples)
  • Connection Pool with warm-up and size control capabilities
  • An Endpoint Manager to manage all the entrypoint nodes to one cluster. It will automatically distribute the connections against all the cluster endpoints defined, and will check for healthiness of the nodes with a defensive node health check strategy.
  • Command parameter Validation:
  • a simple and user-friendly configuration section to configure all your clusters and support for dependency-injection frameworks.
  • You can handle more than 1 cluster in your application
  • You can configure what ConnectionPool you want to use and its internal parameters.
  • You can choose what EndpointManager you want to use
  • You can choose what Transport do you want to use, and even when using TBufferedTransport you can set the length of the buffer!
  • You can managed (add, modify, remove) your Keyspaces and ColumnFamilies
  • Some Byte Enconder Helpers to avoid the need to create and managed your own (Long, UTF8, ASCII, GUID, UUID, Long, Int and so on).
  • Monitor features out of the box, now you can monitor all your connections to Cassandra simply by using Performance Monitor (native with Windows) by implementing PerformanceCounterHelper fwk (*). Take the following screenshot as an example:

Monitor.jpg
Instructions on how to enable this feature are in Aquiles.Diagnostic.Extension.

(*) This feature was disabled on last refactor, it will be enabled back again soon.

You can take a look at Version History for the lastest updates.

Commands Supported

Aquiles supports all the Cassandra commands. Check Cassandra API on documentation about each one.

Easy Example of use

  • Example 1:
Suppose that you have a Cassandra instance configured in your App.Confg or Web.Config, and you named it "Cassandra1". Suppose then, that there is a Keyspace called "TestKeyspace" and within that KeySpace there is a ColumnFamily called "TestColumnFamily".
Now, lets presume that you need to insert a new key "testKey" with a new Column called "testColumn" with a value of "testValue". You may acomplish that with the following code.
string columnFamily = "TestColumnFamily";
string keyspace = "TestKeyspace";
string key = "testKey";
string columnName = "testColumn";
string columnValue = "testValue";

// Insert statement
byte[] key = ByteEncoderHelper.LongEncoder.ToByteArray(i);
ColumnParent columnParent = new ColumnParent();
Column column = new Column() {
    Name = ByteEncoderHelper.UTF8Encoder.ToByteArray(columnName),
    Timestamp = UnixHelper.UnixTimestamp,
    Value = ByteEncoderHelper.UTF8Encoder.ToByteArray(columnValue),
};

columnParent.Column_family = columnFamily;

ICluster cluster = AquilesHelper.RetrieveCluster("Cassandra1");
cluster.Execute(new ExecutionBlock(delegate(CassandraClient client) {
    client.insert(key, columnParent, column, ConsistencyLevel.ONE);
    return null;
}), keyspace);



  • Example 2:
Now, Lets continue with the assumption of the Example1 and that you need to retrieve the value inserted. Your code would be similar to:
// Get statement
byte[] key = ByteEncoderHelper.LongEncoder.ToByteArray(2);
ColumnPath columnPath = new ColumnPath()
{
    Column = ByteEncoderHelper.UTF8Encoder.ToByteArray(columnName),
    Column_family = columnFamily,
};
ICluster cluster = AquilesHelper.RetrieveCluster("Cassandra1");
object rtnValue = cluster.Execute(new ExecutionBlock(delegate(CassandraClient client)
{
    return client.get(key, columnPath, ConsistencyLevel.ONE);
}), keyspace);


As you see, using this client is, somehow, like using a connection to a Database (Cassandra is not a database, but the syntax is similar). More examples can be found at each command.

Aquiles Configuration Section

Configuring Aquiles to use a Cassandra cluster is easy, add the following section into your App.Config (Web.config in case of ASPNET application):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="aquilesConfiguration" type="Aquiles.Core.Configuration.AquilesConfigurationSection,Aquiles.Core"/>
  </configSections>


Note: That the section name must be ''aquilesConfiguration'' and no other, or you Aquiles will not load and will throw a ConfigurationException when first time used.

After that, you will only need to configure your cluster's information like following:

 <aquilesConfiguration>
    <clusters>
      <add friendlyName="Keyspace1">
        <connection poolType="SIZECONTROLLEDPOOL" factoryType="FRAMED">
        </connection>
        <endpointManager type="ROUNDROBIN" defaultTimeout="6000">
          <cassandraEndpoints>
            <add address="localhost" port="9160"/>
          </cassandraEndpoints>
        </endpointManager>
      </add>
    </clusters>
  </aquilesConfiguration>


For further Configuration options, please see Configuring Aquiles

Hints, Tricks, Best Practices

See a list of Hints, Tricks and Best Practices in this document.

Frequently Asked Questions

Q: Is this thing production ready?
A: Yes, im using it now on a heavy traffic site and it works great.

Q: Sure it is production ready?
A: Well, do a load test and give us feedback. If you find something wrong, let us know. And if you fix it, consider sharing the code.

Q: Are you going to support AVRO?
A: Maybe. At this time, the evolution of aquiles is driven by our needs, and we won't upgrade our cassandra servers until the TTL is on the trunk (or any other compelling feature or killing bug).

Q: Hey, it is Achilles!
A: Well, not for us spanish speaking people. To be fair, it should be Ἀχιλλεύς

Q: I'm a bit confuse on your version numbers. How do you choose them?
A: Well, yeap. I know it's a bit confusing. Cassandra now have 3 version numbers: Major.Minor.patchLevel. Well, I have added 1 more version lvl to the end in order to properly detect what is the release we are talking about. Besides this, and since Cassandra does not change its Thrift interface too much, you will probably just need the Aquiles that match exactly the first 2 levels of version (those would be just Major.Minor). For example: Aquiles 0.7.0.X can support from Cassandra 0.7.0.0 to 0.7.6.0 and so on. If you need further assistance just ask on the discussion section.

Success Stories

  • Chirper: twitter clone WebApp with .NET front-end and Cassandra NoSql back-end (thanks Chaker Nakhli)
  • Common Information Platform: Common abstraction over various data stores. (thanks PatrickThompson)
  • Despegar.com: Online Travel Agency. (thanks All in Despegar)

Donations

As you know, this project is free and it is supported and developed during my free time. However, I accept donations to help support Aquiles and accelerate development on it. Click here to donate to Aquiles

Last edited Oct 27, 2011 at 1:27 PM by javiercanillas, version 62