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.8.x. For CLI docs on 0.7.x see this page, 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.

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 or see the help below.

Commands

assume

assume <cf> comparator as <type>;
assume <cf> sub_comparator as <type>;
assume <cf> validator as <type>;
assume <cf> keys as <type>;

Assume one of the attributes (comparator, sub_comparator, validator or keys) of the given column family match specified type. The specified type will be used when displaying data returned from the column family.

This statement does not change the column family definition stored in Cassandra. It only affects the cli and how it will transform values to be sent to and interprets results from Cassandra.

If results from Cassandra do not validate according to the assumptions an error is displayed in the cli.

Required Parameters

Examples

assume Standard1 comparator as lexicaluuid;
assume Standard1 keys as ascii;

connect

connect <hostname>/<port> (<username> '<password>')?;

Connect to the a Cassandra node on the specified port.

If a username and password are supplied the login will occur when the 'use' statement is executed. If the server does not support authentication it will silently ignore credentials.

For information on configuring authentication and authorisation see the conf/cassandra.yaml file or the project documentation.

Required Parameters

Optional Parameters

Examples

connect localhost/9160;
connect localhost/9160 user 'badpasswd';
connect 127.0.0.1/9160 user 'badpasswd';

consistencylevel

consistencylevel as <level>;

Sets the consistency level for the client to use. Defaults to One.

Required Parameters

count

count <cf>['<key>'];
count <cf>['<key>']['<super>'];

Count the number of columns in the row with the specified key, or subcolumns in the specified super column.

Required Parameters

Optional Parameters

Examples

count Super1['testkey']['my super'];
count Standard1['testkey'];

create column family

create column family <name>;
create column family <name> with <att1>=<value1>;
create column family <name> with <att1>=<value1> and <att2>=<value2>...;

Create a column family in the current keyspace with the specified attributes.

Required Parameters

column family Attributes (all are optional):

Decreasing this will cause minor compactions to start more frequently andbe less intensive. The min_compaction_threshold and max_compaction_thresholdboundaries are the number of tables Cassandra attempts to merge together atonce.

Increasing this will cause minor compactions to start less frequently andbe more intensive. The min_compaction_threshold and max_compaction_thresholdboundaries are the number of tables Cassandra attempts to merge together atonce.

Supported values are:

It is also valid to specify the fully-qualified class name to a classthat implements org.apache.cassandra.cache.IRowCacheProvider.

ConcurrentLinkedHashCacheProvider provides the same features as the versionsprior to Cassandra v0.8. Row data is cached using the Java JVM heap.

SerializingCacheProvider serialises the contents of the row andstores the data off the JVM Heap. This may reduce the GC pressure.NOTE: Thsi provider requires JNA.jar to be in the class path toenable native methods.

Examples

create column family Super4
    with column_type = 'Super'
    and comparator = 'AsciiType'
    and rows_cached = 10000;
create column family Standard3
    with comparator = 'LongType'
    and rows_cached = 10000;
create column family Standard4
    with comparator = AsciiType
    and column_metadata =
    [{
        column_name : Test,
        validation_class : IntegerType,
        index_type : 0,
        index_name : IdxName},
    {
        column_name : 'other name',
        validation_class : LongType
    }];

create keyspace

create keyspace <keyspace>;
create keyspace <keyspace> with <att1>=<value1>;
create keyspace <keyspace> with <att1>=<value1> and <att2>=<value2> ...;

Create a keyspace with the specified attributes.

Required Parameters

Keyspace Attributes (all are optional):

Examples

create keyspace Keyspace2
    with placement_strategy = 'org.apache.cassandra.locator.SimpleStrategy'
    and strategy_options = [{replication_factor:4}];
create keyspace Keyspace3
    with placement_strategy = 'org.apache.cassandra.locator.NetworkTopologyStrategy'
    and strategy_options=[{DC1:2, DC2:2}];
create keyspace Keyspace4
    with placement_strategy = 'org.apache.cassandra.locator.OldNetworkTopologyStrategy'
    and strategy_options = [{replication_factor:1}];

decr

decr <cf>['<key>']['<col>'] [by <value>];
decr <cf>['<key>']['<super>']['<col>'] [by <value>];

Decrement the specified column by the supplied value.

Note: Counter columns must be defined using a 'create column family' or 'update column family' statement in the column_metadata as using the ColumnCounterType validator.

Required Parameters

Optional Parameters

Examples

decr Counter1[ascii('testkey')][ascii('test col')];
decr SuperCounter1[ascii('testkey')][ascii('my super')][ascii('test col')] by 42;
decr Counter1[ascii('testkey')][ascii('test col')] by 10;

del

del <cf>['<key>'];
del <cf>['<key>']['<col>'];
del <cf>['<key>']['<super>'];
del <cf>['<key>']['<super>']['<col>'];
del <cf>[<function>(<key>)][<function>(<super>)][<function>(<col>)];

Deletes a row, a column, or a subcolumn.

Required Parameters

Optional Parameters

Examples

del Super1[ascii('testkey')][ascii('my_super')][ascii('test_col')];
del Standard1['testkey'][ascii('test col')];
del Standard1['testkey'];
del Standard1[utf8('testkey')];

describe cluster

describe cluster;

Describes the snitch, partitioner and schema versions for the currently connected cluster.

NOTE: The cluster should only report one schema version. Multiple versions may indicate a failed schema modification, consult the project documentation.

Examples

describe cluster;

describe keyspace

describe keyspace (<keyspace>)?;

Describes the settings for the current or named keyspace, and the settings for all column families in the keyspace.

Optional Parameters

Examples

describe keyspace;
describe keyspace system;

drop column family

drop column family <cf>;

Drops the specified column family.

A snapshot of the data is created in a sub directory of the Keyspace data directory. The files must be manually deleted using either "nodetool clearsnapshot" or the command line.

Required Parameters

Example:drop column family Standard2;

drop keyspace

drop keyspace <keyspace>;

Drops the specified keyspace.

A snapshot of the data is created in a sub directory of the Keyspace data directory. The files must be manually deleted using either "nodetool clearsnapshot" or the command line.

Required Parameters

Example:drop keyspace Keyspace1;

exit

exit;
quit;

Exit this utility.

Examples

exit;
quit;

get

get <cf>['<key>'];
get <cf>['<key>']['<col>'] (as <type>)*;
get <cf>['<key>']['<super>']['<col>'] (as <type>)*;
get <cf>['<key>']['<super>'];
get <cf>['<key>'][<function>];
get <cf>[function(<key>)][<function>(<super>)][<function>(<col>)];
get <cf> where <col> <operator> <value> [
    and <col> <operator> <value> and ...] [limit <limit>];
get <cf> where <col> <operator> <function>(<value>) [
    and <col> <operator> <function> and ...] [limit <limit>];

Gets columns or super columns for the specified column family and key. Or returns all columns from rows which meet the specified criteria when using the 'where' form.

Note: The implementation of secondary indexes in Cassandra 0.7 has some restrictions, see http://www.datastax.com/dev/blog/whats-new-Cassandra-07-secondary-indexes

Required Parameters

Optional Parameters

Examples

get Standard1[ascii('testkey')];
#tell cli to convert keys from ascii to bytes
assume Standard1 keys as ascii;
get Standard1[testkey][test_column] as IntegerType;
get Standard1[testkey][utf8(hello)];
get Indexed1 where birthdate=19750403;

help

help <command>;

Display the general help page with a list of available commands.;

incr

incr <cf>['<key>']['<col>'] [by <value>];
incr <cf>['<key>']['<super>']['<col>'] [by <value>];

Increment the specified counter column by the supplied value.

Note: Counter columns must be defined using a 'create column family' or 'update column family' statement in the column_metadata as using the ColumnCounterType validator.

Required Parameters

Optional Parameters

Examples

incr Counter1[ascii('testkey')][ascii('test col')];
incr SuperCounter1[ascii('testkey')][ascii('my super')][ascii('test col')] by 42;
incr Counter1[ascii('testkey')][ascii('test col')] by -4;

list

list <cf>;
list <cf>[<startKey>:];
list <cf>[<startKey>:<endKey>];
list <cf>[<startKey>:<endKey>] limit <limit>;

List a range of rows, and all of their columns, in the specified column family.

The order of rows returned is dependant on the Partitioner in use.

Required Parameters

Optional Parameters

Examples

list Standard1;
list Super1[j:];
list Standard1[j:k] limit 40;

set

set <cf>['<key>']['<col>'] = <value>;
set <cf>['<key>']['<super>']['<col>'] = <value>;
set <cf>['<key>']['<col>'] = <function>(<argument>);
set <cf>['<key>']['<super>']['<col>'] = <function>(<argument>);
set <cf>[<key>][<function>(<col>)] = <value> || <function>;
set <cf>[<function>(<key>)][<function>(<col>) || <col>] =
    <value> || <function> with ttl = <secs>;

Sets the column value for the specified column family and key.

Required Parameters

Optional Parameters

Examples

set Super1[ascii('testkey')][ascii('my super')][ascii('test col')]='this is a test';
set Standard1['testkey']['test col']='this is also a test';
set Standard1[testkey][testcol] = utf8('this is utf8 string.');
set Standard1[testkey][timeuuid()] = utf8('hello world');
set Standard1[testkey][timeuuid()] = utf8('hello world') with ttl = 30;

show api version

show api version;

Displays the API version number.

This version number is used by high level clients and is not the same as the server release version.

Examples

show api version;

show cluster name

show cluster name;

Displays the name of the currently connected cluster.

Examples

show cluster name;

show keyspaces

show keyspaces;

Describes the settings and the column families for all keyspaces on the currently connected cluster.

Examples

show keyspaces;

truncate

truncate <cf>;

Truncate specified column family.

Note: All nodes in the cluster must be up to truncate command to execute.

A snapshot of the data is created, which is deleted asyncronously during a 'graveyard' compaction.

Required Parameters

Examples

truncate Standard1;

update column family

update column family <name>;
update column family <name> with <att1>=<value1>;
update column family <name> with <att1>=<value1> and <att2>=<value2>...;

Updates the settings for a column family in the current keyspace.

Required Parameters

column family Attributes (all are optional):

Decreasing this will cause minor compactions to start more frequently andbe less intensive. The min_compaction_threshold and max_compaction_thresholdboundaries are the number of tables Cassandra attempts to merge together atonce.

Increasing this will cause minor compactions to start less frequently andbe more intensive. The min_compaction_threshold and max_compaction_thresholdboundaries are the number of tables Cassandra attempts to merge together atonce.

Supported values are:

It is also valid to specify the fully-qualified class name to a classthat implements org.apache.cassandra.cache.IRowCacheProvider.

ConcurrentLinkedHashCacheProvider provides the same features as the versionsprior to Cassandra v0.8. Row data is cached using the Java JVM heap.

SerializingCacheProvider serialises the contents of the row andstores the data off the JVM Heap. This may reduce the GC pressure.NOTE: Thsi provider requires JNA.jar to be in the class path toenable native methods.

Examples

update column family Super4
    with column_type = 'Super'
    and comparator = 'AsciiType'
    and rows_cached = 10000;
update column family Standard3
    with comparator = 'LongType'
    and rows_cached = 10000;
update column family Standard4
    with comparator = AsciiType
    and column_metadata =
    [{
        column_name : Test,
        validation_class : IntegerType,
        index_type : 0,
        index_name : IdxName},
    {
        column_name : 'other name',
        validation_class : LongType
    }];

update keyspace

update keyspace <keyspace>;
update keyspace <keyspace> with <att1>=<value1>;
update keyspace <keyspace> with <att1>=<value1> and <att2>=<value2> ...;

Update a keyspace with the specified attributes.

Note: updating some keyspace properties may require additional maintenance actions. Consult project documentation for more details.

Required Parameters

Keyspace Attributes (all are optional):

Examples

update keyspace Keyspace2
    with placement_strategy = 'org.apache.cassandra.locator.SimpleStrategy'
    and strategy_options = [{replication_factor:4}];
update keyspace Keyspace3
    with placement_strategy = 'org.apache.cassandra.locator.NetworkTopologyStrategy'
    and strategy_options=[{DC1:2, DC2:2}];
update keyspace Keyspace4
    with placement_strategy = 'org.apache.cassandra.locator.OldNetworkTopologyStrategy'
    and strategy_options = [{replication_factor:1}];

use

use <keyspace>;
use <keyspace> <username> '<password>';

Use the specified keyspace.

If a username and password are supplied they will be used to authorize against the keyspace. Otherwise the credentials supplied to the 'connect' statement will be used to authorize the user . If the server does not support authentication it will silently ignore credentials.

Required Parameters

Optional Parameters

Examples

use Keyspace1;
use Keyspace1 user 'badpasswd';

stats

CassandraCli08 (last edited 2013-11-13 01:15:59 by GehrigKunz)