Cassandra ships with a very basic interactive command line interface, or shell. Using the CLI you can connect to remote nodes in the cluster, create or update your schema, set and retrieve records and columns, or query node and cluster meta-data (i.e. cluster name, keyspace listings and disposition, etc). This page is intended for those using Cassandra 0.7.x. For CLI docs on 0.6.x, see this page.
You can start the CLI using the bin/cassandra-cli startup script in your Cassandra installation.
evans@achilles:~/cassandra$ bin/cassandra-cli Welcome to cassandra CLI. Type 'help;' or '?' for help. Type 'quit;' or 'exit;' to quit. [default@unknown] connect localhost/9160; Connected to: "Test Cluster" on localhost/9160 [default@unknown] create keyspace Twissandra; d105c4f1-3c93-11e0-9fb5-e700f669bcfc [default@unknown] use Twissandra; Authenticated to keyspace: Twissandra [default@Twissandra] create column family User with comparator = UTF8Type; 00389812-3c94-11e0-9fb5-e700f669bcfc [default@Twissandra] quit; evans@achilles:~/cassandra$
In the above example we started the cli with no options. You can specify things like -host, -port, -keyspace, -username, -password, etc. Use bin/cassandra-cli -? for a full set of options.
We went on to connect to our local Cassandra node. We created keyspace Twissandra and column family User. Note that with the column family, we used a UTF8Type comparator. That means that the columns will be sorted based on UTF8Type sorting. It also means that when the column names are displayed on the command-line, they will be displayed as UTF8Type (readable) text. For more information and options for creating column families type help create column family; on the command line. Finally, we exited from our cli shell.
Note: As of Cassandra 0.8, values are interpreted as bytes by default, so we will need to declare a key_validation_class for the column family so we can enter text keys:
update column family User with key_validation_class=UTF8Type;
or, you can wrap each value to specify how it should be interpreted, e.g:
set User[utf8('jsmith')]['first'] = 'John';
or, you can temporarily assume a type (this must be repeated every CLI session)
assume User keys as utf8; set User['jsmith']['first'] = 'John';
Let's get back into the shell with some options specified and create some data. You should be aware that using the right assumption for your column family keys is 'essential' for the CLI to work correctly. None of the data retrieval/manipulation commands will work as expected if the key assumption is wrong. If you are just exploring cassandra from the CLI, you can leave the assumptions at their defaults, though.
tblose@quasar:~/dev/workspaces/cassandra$ bin/cassandra-cli -host localhost -port 9160 Connected to localhost/9160 Welcome to cassandra CLI. Type 'help;' or '?' for help. Type 'quit;' or 'exit;' to quit. [default@unknown] use Twissandra; Authenticated to keyspace: Twissandra [default@Twissandra] set User['jsmith']['first'] = 'John'; Value inserted. [default@Twissandra] set User['jsmith']['last'] = 'Smith'; Value inserted. [default@Twissandra] set User['jsmith']['age'] = '39'; Value inserted.
Note that before we can start adding data, we have to use Twissandra; to set our context. We created a record in the User column family using the key jsmith. This record has three columns, first, last, and age. Each of these commands is the equivalent to an insert() using the Thrift API.
Now let's read back the jsmith row to see what it contains:
[default@Twissandra] get User['jsmith']; => (column=age, value=3339, timestamp=1298504259386000) => (column=first, value=4a6f686e, timestamp=1298504239938000) => (column=last, value=536d697468, timestamp=1298504248570000) Returned 3 results.
Note: Using the get command in this form is the equivalent to a get_slice() using the Thrift API.
Why are the values all hex? It's because the default validation class is BytesType, which displays in hex in the output. Let's update the column metadata of the column family to not only make them output in a readable format, but also add a secondary index on age. We'll also add another record so that we can see the secondary index work.
[default@Twissandra] update column family User with
... column_metadata =
... [
... {column_name: first, validation_class: UTF8Type},
... {column_name: last, validation_class: UTF8Type},
... {column_name: age, validation_class: UTF8Type, index_type: KEYS}
... ];
fd98427f-3fa6-11e0-8f42-e700f669bcfc
[default@Twissandra] set User['zaphod']['first'] = 'Zaphod';
Value inserted.
[default@Twissandra] set User['zaphod']['last'] = 'Beeblebrox';
Value inserted.
[default@Twissandra] set User['zaphod']['age'] = '42';
Value inserted.
[default@Twissandra] get User where age = '42';
-------------------
RowKey: zaphod
=> (column=age, value=42, timestamp=1298504874382000)
=> (column=first, value=Zaphod, timestamp=1298504803709000)
=> (column=last, value=Beeblebrox, timestamp=1298504848982000)
1 Row Returned.
In the above example, you can see that we can span commands over multiple lines. We add column metadata that validates the column data as well as display value unencoded in the cli output. We also add an index on age. The KEYS index type means that we can only perform equality operations over it. We add one more row with an age of '42' and finally query the column family for rows with an age of 42.
One final thing that is very handy about the cassandra-cli, you can script your schema creation in a file and run it through the cli. You just create a text file with any number of creation commands and run the cli with the -f option:
tblose@quasar:~/dev/workspaces/cassandra$ bin/cassandra-cli -host localhost -port 9160 -f ~/cassandra-schema.txt Connected to: "Test Cluster" on localhost/9160 1eafa8f4-3faf-11e0-a627-e700f669bcfc Authenticated to keyspace: Twissandra 1f09fdf5-3faf-11e0-a627-e700f669bcfc
with cassandra-schema.txt:
create keyspace Twissandra;
use Twissandra;
create column family User with
comparator = UTF8Type and
column_metadata =
[
{column_name: first, validation_class: UTF8Type},
{column_name: last, validation_class: UTF8Type},
{column_name: age, validation_class: UTF8Type, index_type: KEYS}
];
This has just been a brief introduction with a couple of examples. For more information on how things work, type help; on the cli by itself or with any of the commands you're interested in.