Apache Cassandra 1.1 Documentation

Getting Started Using the Cassandra CLI

This document corresponds to an earlier product version. Make sure you are using the version that corresponds to your version.

Latest Cassandra documentation | Earlier Cassandra documentation

The Cassandra CLI client utility can be used to do basic data definition (DDL) and data manipulation (DML) within a Cassandra cluster. It is located in /usr/bin/cassandra-cli in packaged installations or <install_location>/bin/cassandra-cli in binary installations.

To start the CLI and connect to a particular Cassandra instance, launch the script together with -host and -port options. It will connect to the cluster name specified in the cassandra.yaml file (which is Test Cluster by default). For example, if you have a single-node cluster on localhost:

$ cassandra-cli -host localhost -port 9160

Or to connect to a node in a multi-node cluster, give the IP address of the node:

$ cassandra-cli -host 110.123.4.5 -port 9160

To see help on the various commands available:

[default@unknown] help;

For detailed help on a specific command, use help <command>;. For example:

[default@unknown] help SET;

Note

A command is not sent to the server unless it is terminated by a semicolon (;). Hitting the return key without a semicolon at the end of the line echos an ellipsis ( . . . ), which indicates that the CLI expects more input.

Creating a Keyspace

You can use the Cassandra CLI commands described in this section to create a keyspace. In this example, we create a keyspace called demo, with a replication factor of 1 and using the SimpleStrategy replica placement strategy.

Note the single quotes around the string value of placement_strategy:

[default@unknown] CREATE KEYSPACE demo
with placement_strategy = 'SimpleStrategy'
and strategy_options = {replication_factor:1};

You can verify the creation of a keyspace with the SHOW KEYSPACES command. The new keyspace is listed along with the system keyspace and any other existing keyspaces.

Creating a Column Family

First, connect to the keyspace where you want to define the column family with the USE command.

[default@unknown] USE demo;

In this example, we create a users column family in the demo keyspace. In this column family we are defining a few columns; full_name, email, state, gender, and birth_year. This is considered a static column family - we are defining the column names up front and most rows are expected to have more-or-less the same columns.

Notice the settings of comparator, key_validation_class and validation_class. These are setting the default encoding used for column names, row key values and column values. In the case of column names, the comparator also determines the sort order.

[default@unknown] USE demo;

[default@demo] CREATE COLUMN FAMILY users
WITH comparator = UTF8Type
AND key_validation_class=UTF8Type
AND column_metadata = [
{column_name: full_name, validation_class: UTF8Type}
{column_name: email, validation_class: UTF8Type}
{column_name: state, validation_class: UTF8Type}
{column_name: gender, validation_class: UTF8Type}
{column_name: birth_year, validation_class: LongType}
];

Next, create a dynamic column family called blog_entry. Notice that here we do not specify column definitions as the column names are expected to be supplied later by the client application.

[default@demo] CREATE COLUMN FAMILY blog_entry
WITH comparator = TimeUUIDType
AND key_validation_class=UTF8Type
AND default_validation_class = UTF8Type;

Creating a Counter Column Family

A counter column family contains counter columns. A counter column is a specific kind of column whose user-visible value is a 64-bit signed integer that can be incremented (or decremented) by a client application. The counter column tracks the most recent value (or count) of all updates made to it. A counter column cannot be mixed in with regular columns of a column family, you must create a column family specifically to hold counters.

To create a column family that holds counter columns, set the default_validation_class of the column family to CounterColumnType. For example:

[default@demo] CREATE COLUMN FAMILY page_view_counts
WITH default_validation_class=CounterColumnType
AND key_validation_class=UTF8Type AND comparator=UTF8Type;

To insert a row and counter column into the column family (with the initial counter value set to 0):

[default@demo] INCR page_view_counts['www.datastax.com'][home] BY 0;

To increment the counter:

[default@demo] INCR page_view_counts['www.datastax.com'][home] BY 1;

Inserting Rows and Columns

The following examples illustrate using the SET command to insert columns for a particular row key into the users column family. In this example, the row key is bobbyjo and we are setting each of the columns for this user. Notice that you can only set one column at a time in a SET command.

[default@demo] SET users['bobbyjo']['full_name']='Robert Jones';

[default@demo] SET users['bobbyjo']['email']='bobjones@gmail.com';

[default@demo] SET users['bobbyjo']['state']='TX';

[default@demo] SET users['bobbyjo']['gender']='M';

[default@demo] SET users['bobbyjo']['birth_year']='1975';

In this example, the row key is yomama and we are just setting some of the columns for this user.

[default@demo] SET users['yomama']['full_name']='Cathy Smith';

[default@demo] SET users['yomama']['state']='CA';

[default@demo] SET users['yomama']['gender']='F';

[default@demo] SET users['yomama']['birth_year']='1969';

In this example, we are creating an entry in the blog_entry column family for row key yomama:

[default@demo] SET blog_entry['yomama'][timeuuid()] = 'I love my new shoes!';

Note

The Cassandra CLI sets the consistency level for the client. The level defaults to ONE for all write and read operations. For more information, see About Data Consistency in Cassandra.

Reading Rows and Columns

Use the GET command within Cassandra CLI to retrieve a particular row from a column family. Use the LIST command to return a batch of rows and their associated columns (default limit of rows returned is 100).

For example, to return the first 100 rows (and all associated columns) from the users column family:

[default@demo] LIST users;

Cassandra stores all data internally as hex byte arrays by default. If you do not specify a default row key validation class, column comparator and column validation class when you define the column family, Cassandra CLI will expect input data for row keys, column names, and column values to be in hex format (and data will be returned in hex format).

To pass and return data in human-readable format, you can pass a value through an encoding function. Available encodings are:

  • ascii
  • bytes
  • integer (a generic variable-length integer type)
  • lexicalUUID
  • long
  • utf8

For example to return a particular row key and column in UTF8 format:

[default@demo] GET users[utf8('bobbyjo')][utf8('full_name')];

You can also use the ASSUME command to specify the encoding in which column family data should be returned for the entire client session. For example, to return row keys, column names, and column values in ASCII-encoded format:

[default@demo] ASSUME users KEYS AS ascii;
[default@demo] ASSUME users COMPARATOR AS ascii;
[default@demo] ASSUME users VALIDATOR AS ascii;

Setting an Expiring Column

When you set a column in Cassandra, you can optionally set an expiration time, or time-to-live (TTL) attribute for it.

For example, suppose we are tracking coupon codes for our users that expire after 10 days. We can define a coupon_code column and set an expiration date on that column. For example:

[default@demo] SET users['bobbyjo']
[utf8('coupon_code')] = utf8('SAVE20') WITH ttl=864000;

After ten days, or 864,000 seconds have elapsed since the setting of this column, its value will be marked as deleted and no longer be returned by read operations. Note, however, that the value is not actually deleted from disk until normal Cassandra compaction processes are completed.

Indexing a Column

The CLI can be used to create secondary indexes (indexes on column values). You can add a secondary index when you create a column family or add it later using the UPDATE COLUMN FAMILY command.

For example, to add a secondary index to the birth_year column of the users column family:

[default@demo] UPDATE COLUMN FAMILY users
WITH comparator = UTF8Type
AND column_metadata = [{column_name: birth_year, validation_class: LongType, index_type: KEYS}];

Because of the secondary index created for the column birth_year, its values can be queried directly for users born in a given year as follows:

[default@demo] GET users WHERE birth_year = 1969;

Deleting Rows and Columns

The Cassandra CLI provides the DEL command to delete a row or column (or subcolumn).

For example, to delete the coupon_code column for the yomama row key in the users column family:

[default@demo] DEL users ['yomama']['coupon_code'];

[default@demo] GET users ['yomama'];

Or to delete an entire row:

[default@demo] DEL users ['yomama'];

Dropping Column Families and Keyspaces

With Cassandra CLI commands you can drop column families and keyspaces in much the same way that tables and databases are dropped in a relational database. This example shows the commands to drop our example users column family and then drop the demo keyspace altogether:

[default@demo] DROP COLUMN FAMILY users;

[default@demo] DROP KEYSPACE demo;