A Ruby client for the Cassandra distributed database.
Copyright 2009, 2010 Twitter, Inc. See included LICENSE file. Portions copyright 2004-2009 David Heinemeier Hansson, and used with permission.
-
clean encapsulation of the Thrift API
-
compatible UUID and Long classes, for GUID generation
-
Ruby 1.9 compatibility
The Github source repository is here. Patches and contributions are very welcome.
You need Ruby 1.8 or 1.9. If you have those, just run:
sudo gem install cassandra
Cassandra itself is a rapidly moving target. In order to get a working server, use the ‘bin/cassandra_helper` script:
cassandra_helper cassandra
A server will be installed in ‘$HOME/cassandra/server`, and started in debug mode.
WARNING: Don’t use the test folder for your data, as it will get overwritten when you update the gem.
Now, start IRb and require the library, which defaults to version 0.6 of the Cassandra API:
require 'cassandra'
Alternatively, you can specify a version of the Cassandra API to use:
require 'cassandra/0.6'
or
require 'cassandra/0.7'
Connect to a server and keyspace:
client = Cassandra.new('Twitter', '127.0.0.1:9160')
Login on server if the keyspace require authentication:
client.login!('username','password')
Insert into a column family. You can insert a ‘Cassandra::OrderedHash`, or a regular Hash, if order doesn’t matter:
client.insert(:Users, "5", {'screen_name' => "buttonscat"})
The 0.7 API insert() includes support for TTL on columns. The following example inserts into a comlumn family with a time to live of 30 seconds.
client.insert(:Users, "5", {'screen_name' => "buttonscat"}, {:ttl=>30})
Insert into a super column family:
client.insert(:UserRelationships, "5", {"user_timeline" => {UUID.new => "1"}})
Query a super column:
timeline = client.get(:UserRelationships, "5", "user_timeline")
The returned result will always be a Cassandra::OrderedHash.
Create and delete a 2ary index:
client.create_index("Twitter", "Users", "revenue_generating_units", "LongType")
client.delete_index("Twitter", "Users", "revenue_generating_units"
Create an index clause and query an indexed column family:
expr = client.create_idx_expr("revenue_generating_units", 100, ">") clause = client.create_idx_clause([expr]) client.get_indexed_slices(:Users, clause)
See Cassandra for more methods.
By default, cassandra is setup to listen on localhost. If you want to move your clients to another host, you’re going to need to change which interface it binds to in the storage-conf.xml. You should also change the seed address.
The list of hosts you pass to the client is only used to auto-discover all the nodes in your cluster. You don’t need to give the client a list of all of your nodes.
The Github issue tracker is here. If you have problems with this library or Cassandra itself, please use the cassandra-user mailing list.