Starting Cassandra Command Line Interface (Cassandra CLI mode)

Running the Command-Line Client Interface

Now that you have a Cassandra installation up and running, let’s give it a quick try to make sure everything is set up properly. On Linux, running the command-line interface just works. On Windows, you might have to do a little additional work.

On Windows, navigate to the Cassandra home directory and open a new terminal in which to run our client process:

>bin\cassandra-cli

It’s possible that on Windows you will see an error like this when starting the client:
Starting Cassandra Client
Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/cassandra/cli/CliMain

This probably means that you started Cassandra directly from within the bin directory, and it therefore sets up its Java classpath incorrectly and can’t find the CliMain file to start the client. You can define an environment variable called CASSANDRA_HOME that points to the top-level directory where you have placed or built Cassandra, so you don’t have to pay as much attention to where you’re starting Cassandra from.

To run the command-line interface program on Linux, navigate to the Cassandra home directory and run the cassandra-cli program in the bin directory:

>bin/cassandra-cli

The Cassandra client will start:

eben@morpheus$ bin/cassandra-cli
Welcome to cassandra CLI.
Type 'help' or '?' for help. Type 'quit' or 'exit' to quit.
[default@unknown]

You now have an interactive shell at which you can issue commands. Note, however, that if you’re used to Oracle’s SQL*Plus or similar command-line database clients, you may become frustrated. The Cassandra CLI is not intended to be used as a full-blown client, as it’s really for development. That makes it a good way to get started using Cassandra, because you don’t have to write lots of code to test interactions
with your database and get used to the environment.

Basic CLI Commands

Before we get too deep into how Cassandra works, let’s get an overview of the client API so that you can see what kinds of commands you can send to the server. We’ll see how to use the basic environment commands and how to do a round trip of inserting and retrieving some data.

Help

To get help for the command-line interface, type help or ? to see the list of available commands. The following list shows only the commands related to metadata and configuration; there are other commands for getting and setting values that we explore later.

[default@Keyspace1] help
List of all CLI commands:
? Display this message.
help Display this help.
help Display detailed, command-specific help.
connect / Connect to thrift service.
use [ 'password'] Switch to a keyspace.
describe keyspace Describe keyspace.
exit Exit CLI.
quit Exit CLI.
show cluster name Display cluster name.
show keyspaces Show list of keyspaces.
show api version Show server API version.
create keyspace [with = [and = ...]]
Add a new keyspace with the specified attribute and value(s).
create column family [with = [and = ...]]
Create a new column family with the specified attribute and value(s).
drop keyspace Delete a keyspace.
drop column family Delete a column family.
rename keyspace Rename a keyspace.
rename column family Rename a column family.


Connecting to a Server


Starting the client this way does not automatically connect to a Cassandra server instance. So to connect to a particular server after you have started Cassandra this way, use the connect command:


eben@morpheus:~/books/cassandra/dist/apache-cassandra-0.7.0-beta1$ 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]


As a shortcut, you can start the client and connect to a particular server instance by passing the host and port parameters at startup, like this:
eben@morpheus:~/books/cassandra/dist/apache-cassandra-0.7.0-beta1$ bin/
cassandra-cli localhost/9160
Welcome to cassandra CLI.
Type 'help' or '?' for help. Type 'quit' or 'exit' to quit.
[default@unknown]

If you see this error while trying to connect to a server:
Exception connecting to localhost/9160 - java.net.ConnectException:
Connection refused: connect


make sure that a Cassandra instance is started at that host and port and that you can ping the host you’re trying to reach. There may be firewall rules preventing you from connecting. Also make sure that you’re using
the new 0.7 syntax as described earlier, as it has changed from previous versions.


The CLI indicates that you’re connected to a Cassandra server cluster called “Test Cluster”. That’s because this cluster of one node at localhost is set up for you by default.
In a production environment, be sure to remove the Test Cluster from the configuration.


Describing the Environment


After connecting to your Cassandra instance Test Cluster, if you’re using the binary distribution, an empty keyspace, or Cassandra database, is set up for you to test with.

To see the name of the current cluster you’re working in, type:
[default@unknown] show cluster name
Test Cluster


To see which keyspaces are available in the cluster, issue this command:
[default@unknown] show keyspaces
system


If you have created any of your own keyspaces, they will be shown as well. The system keyspace is used internally by Cassandra, and isn’t for us to put data into. In this way, it’s similar to the master and temp databases in Microsoft SQL Server. This keyspace contains the schema definitions and is aware of any modifications to the schema made at runtime. It can propagate any changes made in one node to the rest of the cluster based on timestamps.

To see the version of the API you’re using, type:
[default@Keyspace1] show api version
10.0.0


There are a variety of other commands with which you can experiment. For now, let’s add some data to the database and get it back out again. Creating a Keyspace and Column Family A Cassandra keyspace is sort of like a relational database. It defines one or more column families, which are very roughly analogous to tables in the relational world. When you start the CLI client without specifying a keyspace, the output will look like this:

>bin/cassandra-cli --host localhost --port 9160
Starting Cassandra Client
Connected to: "Test Cluster" on localhost/9160
Welcome to cassandra CLI.
Type 'help' or '?' for help. Type 'quit' or 'exit' to quit.
[default@unknown]


Your shell prompt is for default@unknown because you haven’t authenticated as a particular user (which we’ll see how to do in Chapter 6) and you didn’t specify a keyspace. This authentication scheme is familiar if you’ve used MySQL before.Authentication and authorization are very much works in progress at
the time of this writing. The recommended deployment is to put a firewall around your cluster.


Let’s create our own keyspace so we have something to write data to:
[default@unknown] create keyspace MyKeyspace with replication_factor=1
ab67bad0-ae2c-11df-b642-e700f669bcfc

Don’t worry about the replication_factor for now. That’s a setting we’ll look at in detail later. After you have created your own keyspace, you can switch to it in the shell by typing:
[default@unknown] use MyKeyspace
Authenticated to keyspace: MyKeyspace
[default@MyKeyspace]

We’re “authorized” to the keyspace because MyKeyspace doesn’t require credentials.

Now we can create a column family in our keyspace. To do this on the CLI, use the following command:

[default@MyKeyspace] create column family User
991590d3-ae2e-11df-b642-e700f669bcfc
[default@MyKeyspace]

This creates a new column family called “User” in our current keyspace, and takes the defaults for column family settings. We can use the CLI to get a description of a keyspace using the describe keyspace command, and make sure it has our column family definition, as shown here:

[default@MyKeyspace] describe keyspace MyKeyspace
Keyspace: MyKeyspace
Column Family Name: User
Column Family Type: Standard
Column Sorted By: org.apache.cassandra.db.marshal.BytesType
flush period: null minutes
------
[default@MyKeyspace]


We’ll worry about the Type, Sorted By, and flush period settings later. For now, we have enough to get started.

Writing and Reading Data


Now that we have a keyspace and a column family, we’ll write some data to the database and read it back out again. It’s OK at this point not to know quite what’s going on. We’ll come to understand Cassandra’s data model in depth later. For now, you have a keyspace (database), which has a column family. For our purposes here, it’s enough to think of a column family as a multidimensional ordered map that you don’t have to define further ahead of time. Column families hold columns, and columns are the atomic unit of data storage.

To write a value, use the set command:
[default@MyKeyspace] set User['ehewitt']['fname']='Eben'
Value inserted.
[default@MyKeyspace] set User['ehewitt']['email']='me@example.com'
Value inserted.
[default@MyKeyspace]


Here we have created two columns for the key ehewitt, to store a set of related values. The column names are fname and email. We can use the count command to make sure that we have written two columns for our single key:

[default@MyKeyspace] count User['ehewitt']
2 columns
Now that we know the data is there, let’s read it, using the get command:

[default@MyKeyspace] get User['ehewitt']
=> (column=666e616d65, value=Eben, timestamp=1282510290343000)
=> (column=656d61696c, value=me@example.com, timestamp=1282510313429000)
Returned 2 results.


You can delete a column using the del command. Here we will delete the email column for the ehewitt row key:

[default@MyKeyspace] del User['ehewitt']['email']
column removed.


Now we’ll clean up after ourselves by deleting the entire row. It’s the same command, but we don’t specify a column name:

[default@MyKeyspace] del User['ehewitt']
row removed.
To make sure that it’s removed, we can query again:
[default@Keyspace1] get User['ehewitt']
Returned 0 results.


Summary


Now you should have a Cassandra installation up and running. You’ve worked with the CLI client to insert and retrieve some data, and you’re ready to take a step back and get the big picture on Cassandra before really diving into the details.