Extracting the Download

You can unpack the compressed file using any regular ZIP utility. On Unix-based systems such as Linux or MacOS, GZip extraction utilities should be pre-installed; on Windows, you’ll need to get a program such as WinZip, which is commercial, or something like 7-Zip, which is freeware.

Open your extracting program. You might have to extract the ZIP file and the TAR file in separate steps. Once you have a folder on your filesystem called apache-cassandra-x.x.x, you’re ready to run Cassandra.

What’s In There?

Once you decompress the tarball, you’ll see that the Cassandra binary distribution includes several files and directories.

The files include the NEWS.txt file, which includes the release notes describing features included in the current and prior releases, and the CHANGES.txt, which is similar but focuses on bug fixes. You’ll want to make sure to review these files whenever you are upgrading to a new version so you know what changes to expect. The LICENSE.txt and NOTICE.txt files contain the Apache 2.0 license used by Cassandra, and copyright notices for Cassandra and included software, respectively.

Let’s take a moment to look around in the directories and see what we have.

bin

This directory contains the executables to run Cassandra as well as clients, including the query language shell (cqlsh). It also has scripts to run the nodetool, which is a utility for inspecting a cluster to determine whether it is properly configured, and to perform a variety of maintenance operations. We look at nodetool in depth later. The directory also contains several utilities for performing operations on SSTables, the files in which Cassandra stores its data on disk. We’ll discuss these utilities in Chapter 12.

conf

This directory contains the files for configuring your Cassandra instance. The configuration files you may use most frequently include the cassandra.yaml file, which is the primary configuration for running Cassandra, and the logback.xml file, which lets you change the logging settings to suit your needs. Additional files can be used to configure Java Virtual Machine (JVM) settings, the network topology, metrics reporting, archival and restore commands, and triggers. We see how to use these configuration files when we discuss configuration in Chapter 10.

doc

Traditionally documentation has been one of the weaker areas of the project, but a concerted effort for the 4.0 release including sponsorship from the Google Season of Docs project yielded significant progress to the documentation included in the Cassandra distribution as well as the documentation on the Cassandra website at http://cassandra.apache.org/doc/latest/. The documentation includes a getting started guide, an architectural overview, and instructions for configuring and operating Cassandra.

javadoc

This directory contains a documentation website generated using Java’s JavaDoc tool. Note that JavaDoc reflects only the comments that are stored directly in the Java code, and as such does not represent comprehensive documentation. It’s helpful if you want to see how the code is laid out. Moreover, Cassandra is a wonderful project, but the code contains relatively few comments, so you might find the JavaDoc’s usefulness limited. It may be more fruitful to simply read the class files directly if you’re familiar with Java. Nonetheless, to read the JavaDoc, open the javadoc/index.html file in a browser.

lib

This directory contains all of the external libraries that Cassandra needs to run. For example, it uses two different JSON serialization libraries, the Google collections project, and several Apache Commons libraries.

pylib

This directory contains Python libraries that are used by cqlsh.

tools

This directory contains tools that are used to maintain your Cassandra nodes. We’ll look at these tools in Chapter 12.

Additional Build Targets

To compile the server, you can simply execute ant as shown previously. This command executes the default target, jar. This target will perform a complete build including unit tests and output a file into the build directory called apache-cassandra-x.x.x.jar.

If you want to see a list of all of the targets supported by the build file, simply pass Ant the -p option to get a description of each target. Here are a few others you might be interested in:

test

Users will probably find this the most helpful, as it executes the battery of unit tests. You can also check out the unit test sources themselves for some useful examples of how to interact with Cassandra.

stress-build

This target builds the Cassandra stress tool, which we will try out in Chapter 13.

clean

This target removes locally created artifacts such as generated source files and classes and unit test results. The related target realclean performs a clean and additionally removes the Cassandra distribution JAR files and JAR files downloaded by Maven.

Setting the environment

Once you have the binary (or the source downloaded and compiled), you’re ready to start the database server.

Setting the JAVA_HOME environment variable is recommended. To do this on a Windows system, click the Start button and then right-click on Computer. Click Advanced System Settings, and then click the Environment Variables… button. Click New… to create a new system variable. In the Variable Name field, type JAVA_HOME. In the Variable Value field, type the path to your Java installation. This is probably something like C:Program FilesJavajre1.8.0_25.

Once you’ve started the server for the first time, Cassandra will add directories to your system to store its data files. The default configuration creates directories under the CASSANDRA_HOME directory.

data

This directory is where Cassandra stores its data. By default, there are three sub-directories under the data directory, corresponding to the various data files Cassandra uses: commitlog, data, and saved_caches. We’ll explore the significance of each of these data files in Chapter 6. If you’ve been trying different versions of the database and aren’t worried about losing data, you can delete these directories and restart the server as a last resort.

logs

This directory is where Cassandra stores its logs in a file called system.log. If you encounter any difficulties, consult the log to see what might have happened.

Many users on Unix-based systems prefer to use the /var/lib directory for data storage. If you are changing this configuration, you will need to edit the conf/cassandra.yaml file and create the referenced directories for Cassandra to store its data, making sure to configure write permissions for the user that will be running Cassandra:

$ sudo mkdir -p /var/lib/cassandra
$ sudo chown -R username /var/lib/cassandra

Instead of username, substitute your own username, of course.

Starting the Server

To start the Cassandra server on any OS, open a command prompt or terminal window, navigate to the <cassandra-directory>/bin where you unpacked Cassandra, and run the command cassandra -f to start your server.

In a clean installation, you should see quite a few log statements as the server gets running. The exact syntax of logging statements will vary depending on the release you’re using, but there are a few highlights we can look for. If you search for cassandra.yaml, you’ll quickly run into the following:

INFO  [main] 2019-08-25 17:42:11,712 YamlConfigurationLoader.java:89 -
  Configuration location: file:/Users/jeffreycarpenter/cassandra/conf/cassandra.yaml
INFO  [main] 2019-08-25 17:42:11,855 Config.java:598 - Node configuration:[
  allocate_tokens_for_keyspace=null;
  ...

These log statements indicate the location of the cassandra.yaml file containing the configured settings. The Node configuration statement lists out the settings read from the config file.

Now search for JVM and you’ll find something like this:

INFO  [main] 2019-08-25 17:42:12,308 CassandraDaemon.java:487 -
  JVM vendor/version: OpenJDK 64-Bit Server VM/12.0.1
INFO  [main] 2019-08-25 17:42:12,309 CassandraDaemon.java:488 -
  Heap size: 3.900GiB/3.900GiB

These log statements provide information describing the JVM being used, including memory settings.

Next, search for the versions in use—Cassandra version, CQL version, Native protocol supported versions:

INFO  [main] 2019-08-25 17:42:17,847 StorageService.java:610 -
  Cassandra version: 4.0-alpha3
INFO  [main] 2019-08-25 17:42:17,848 StorageService.java:611 -
  CQL version: 3.4.5
INFO  [main] 2019-08-25 17:42:17,848 StorageService.java:612 -
  Native protocol supported versions: 3/v3, 4/v4, 5/v5-beta (default: 4/v4)

We can also find statements where Cassandra is initializing internal data structures such as caches:

INFO [main] 2015-12-08 06:02:43,633 CacheService.java:115 -
  Initializing key cache with capacity of 24 MBs.
INFO [main] 2015-12-08 06:02:43,679 CacheService.java:137 -
  Initializing row cache with capacity of 0 MBs
INFO [main] 2015-12-08 06:02:43,686 CacheService.java:166 -
  Initializing counter cache with capacity of 12 MBs

If we search for terms like JMX, gossip, and listening, we can find statements like the following:

WARN  [main] 2019-08-25 17:42:12,363 StartupChecks.java:168 -
  JMX is not enabled to receive remote connections.
  Please see cassandra-env.sh for more info.
INFO  [main] 2019-08-25 17:42:18,354 StorageService.java:814 -
  Starting up server gossip
INFO  [main] 2019-08-25 17:42:18,070 InboundConnectionInitiator.java:130 -
  Listening on address: (127.0.0.1:7000), nic: lo0, encryption: enabled (openssl)

These log statements indicate the server is beginning to initiate communications with other servers in the cluster and expose publicly available interfaces. By default, the management interface via the Java Management Extensions (JMX) is disabled for remote access. We’ll explore the management interface in Chapter 11.

Finally, search for state jump and you’ll see the following:

INFO  [main] 2019-08-25 17:42:18,581 StorageService.java:1507 -
  JOINING: Finish joining ring
INFO  [main] 2019-08-25 17:42:18,591 StorageService.java:2508 -
  Node 127.0.0.1:7000 state jump to NORMAL

Congratulations! Now your Cassandra server should be up and running with a new single node cluster called Test Cluster ready to interact with other nodes and clients. If you continue to monitor the output, you’ll begin to see periodic output such as memtable flushing and compaction, which we’ll learn about soon.

Stopping Cassandra

Now that we’ve successfully started a Cassandra server, you may be wondering how to stop it. You may have noticed the stop-server command in the bin directory. Let’s try running that command. Here’s what you’ll see on Unix systems:

$ ./stop-server
please read the stop-server script before use

So you see that our server has not been stopped, but instead we are directed to read the script. Taking a look inside with your favorite code editor, you’ll learn that the way to stop Cassandra is to kill the JVM process that is running Cassandra. The file suggests a couple of different techniques by which you can identify the JVM process and kill it.

The first technique is to start Cassandra using the -p option, which provides Cassandra with the name of a file to which it should write the process identifier (PID) upon starting up. This is arguably the most straightforward approach to making sure we kill the right process.

However, because we did not start Cassandra with the -p option, we’ll need to find the process ourselves and kill it. The script suggests using pgrep to locate processes for the current user containing the term “cassandra”:

user=`whoami`
pgrep -u $user -f cassandra | xargs kill −9

cqlsh Help

To get help for cqlsh, type HELP or ? to see the list of available commands:

cqlsh> help

Documented shell commands:
===========================
CAPTURE  CLS          COPY  DESCRIBE  EXPAND  LOGIN   SERIAL  SOURCE   UNICODE
CLEAR    CONSISTENCY  DESC  EXIT      HELP    PAGING  SHOW    TRACING

CQL help topics:
================
AGGREGATES               CREATE_KEYSPACE           DROP_TRIGGER      TEXT
ALTER_KEYSPACE           CREATE_MATERIALIZED_VIEW  DROP_TYPE         TIME
ALTER_MATERIALIZED_VIEW  CREATE_ROLE               DROP_USER         TIMESTAMP
ALTER_TABLE              CREATE_TABLE              FUNCTIONS         TRUNCATE
ALTER_TYPE               CREATE_TRIGGER            GRANT             TYPES
ALTER_USER               CREATE_TYPE               INSERT            UPDATE
APPLY                    CREATE_USER               INSERT_JSON       USE
ASCII                    DATE                      INT               UUID
BATCH                    DELETE                    JSON
BEGIN                    DROP_AGGREGATE            KEYWORDS
BLOB                     DROP_COLUMNFAMILY         LIST_PERMISSIONS
BOOLEAN                  DROP_FUNCTION             LIST_ROLES
COUNTER                  DROP_INDEX                LIST_USERS
CREATE_AGGREGATE         DROP_KEYSPACE             PERMISSIONS
CREATE_COLUMNFAMILY      DROP_MATERIALIZED_VIEW    REVOKE
CREATE_FUNCTION          DROP_ROLE                 SELECT
CREATE_INDEX             DROP_TABLE                SELECT_JSON

To get additional documentation about a particular command, type HELP <command>. Many cqlsh commands may be used with no parameters, in which case they print out the current setting. Examples include CONSISTENCY, EXPAND, and PAGING.

Describing the Environment in cqlsh

Now that you have connected to your Cassandra instance Test Cluster, to learn more about the cluster you’re working in, type:

cqlsh> DESCRIBE CLUSTER;
Cluster: Test Cluster
Partitioner: Murmur3Partitioner

To see which keyspaces are available in the cluster, issue this command:

cqlsh> DESCRIBE KEYSPACES;
system_traces  system_auth  system_distributed     system_views
system_schema  system       system_virtual_schema

Initially this list will consist of several system keyspaces. Once you have created your own keyspaces, they will be shown as well. The system keyspaces are managed internally by Cassandra, and aren’t for us to put data into. In this way, these keyspaces are similar to the master and temp databases in Microsoft SQL Server. Cassandra uses these keyspaces to store the schema, tracing, and security information. We’ll learn more about these keyspaces in Chapter 6.

You can use the following command to learn the client, server, and protocol versions in use:

cqlsh> SHOW VERSION;
[cqlsh 5.0.1 | Cassandra 4.0-alpha3 | CQL spec 3.4.5 | Native protocol v4]

You may have noticed that this version info is printed out when cqlsh starts. 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 Table in cqlsh

A Cassandra keyspace is sort of like a relational database. It defines one or more tables. When you start cqlsh without specifying a keyspace, the prompt will look like this: cqlsh>, with no keyspace specified.

Let’s create our own keyspace so we have something to write data to. In creating our keyspace, there are some required options. To walk through these options, we could use the command HELP CREATE_KEYSPACE, but instead we’ll use the helpful command-completion features of cqlsh. Type the following and then hit the Tab key:

cqlsh> CREATE KEYSPACE my_keyspace WITH

When you hit the Tab key, cqlsh begins completing the syntax of our command:

cqlsh> CREATE KEYSPACE my_keyspace WITH replication = {'class': '

This is informing us that in order to specify a keyspace, we also need to specify a replication strategy. Let’s Tab again to see what options we have:

cqlsh> CREATE KEYSPACE my_keyspace WITH replication = {'class': '
NetworkTopologyStrategy    OldNetworkTopologyStrategy SimpleStrategy

Now cqlsh is giving us three strategies to choose from. We’ll learn more about these strategies in Chapter 6. For now, we will choose the SimpleStrategy by typing the name. We’ll indicate we’re done with a closing quote and Tab again:

cqlsh> CREATE KEYSPACE my_keyspace WITH replication = {'class':
  'SimpleStrategy', 'replication_factor':

The next option we’re presented with is a replication factor. For the simple strategy, this indicates how many nodes the data in this keyspace will be written to. For a production deployment, we’d want copies of our data stored on multiple nodes, but because we’re just running a single node at the moment, we’ll ask for a single copy. Let’s specify a value of “1” and a space and Tab again:

cqlsh> CREATE KEYSPACE my_keyspace WITH replication = {'class':
  'SimpleStrategy', 'replication_factor': 1};

We see that cqlsh has now added a closing bracket, indicating we’ve completed all of the required options. Let’s complete our command with a semicolon and return, and our keyspace will be created.

Let’s have a look at our keyspace using the DESCRIBE KEYSPACE command:

cqlsh> DESCRIBE KEYSPACE my_keyspace
CREATE KEYSPACE my_keyspace WITH replication = {'class':
  'SimpleStrategy', 'replication_factor': '1'} AND
  durable_writes = true;

We see that the table has been created with the SimpleStrategy, a replication_factor of one, and durable writes. Notice that our keyspace is described in much the same syntax that we used to create it, with one additional option that we did not specify: durable_writes = true. Don’t worry about this option now; we’ll return to it in Chapter 6.

After you have created your own keyspace, you can switch to it in the shell by typing:

cqlsh> USE my_keyspace;
cqlsh:my_keyspace>

Notice that the prompt has changed to indicate that we’re using the keyspace.

Now that we have a keyspace, we can create a table in our keyspace. To do this in cqlsh, use the following command:

cqlsh:my_keyspace> CREATE TABLE user ( first_name text ,
  last_name text, title text, PRIMARY KEY (last_name, first_name)) ;

This creates a new table called “user” in our current keyspace with three columns to store first and last names and a title, all of type text. The text and varchar types are synonymous and are used to store strings. We’ve specified a primary key for this table consisting of the first_name and last_name and taken the defaults for other table options. We’ll learn more about primary keys and the significance of our choice of primary key in Chapter 4, but for now let’s think of that combination of names as identifying unique rows in our table. The title column is the only one in our table that is not part of the primary key.

We can use cqlsh to get a description of a the table we just created using the DESCRIBE TABLE command:

cqlsh:my_keyspace> DESCRIBE TABLE user;
CREATE TABLE my_keyspace.user (
    first_name text,
    last_name text,
    title text,
    PRIMARY KEY (last_name, first_name)
) WITH bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.
      SizeTieredCompactionStrategy', 'max_threshold': '32',
      'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '16', 'class':
      'org.apache.cassandra.io.compress.LZ4Compressor'}
    AND crc_check_chance = 1.0
    AND dclocal_read_repair_chance = 0.0
    AND default_time_to_live = 0
    AND gc_grace_seconds = 864000
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND read_repair_chance = 0.0
    AND speculative_retry = '99p';

You’ll notice that cqlsh prints a nicely formatted version of the CREATE TABLE command that we just typed in but also includes default values for all of the available table options that we did not specify. We’ll worry about these settings later. For now, we have enough to get started.

Writing and Reading Data in cqlsh

Now that we have a keyspace and a table, 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 table, which holds columns, the atomic unit of data storage.

To write rows, we use the INSERT command:

cqlsh:my_keyspace> INSERT INTO user (first_name, last_name, title)
  VALUES ('Bill', 'Nguyen', 'Mr.');

Here we have created a new row with two columns for the key Bill, to store a set of related values. The column names are first_name and last_name.

Now that we have written some data, let’s read it, using the SELECT command:

cqlsh:my_keyspace> SELECT * FROM user WHERE first_name='Bill' and last_name='Nguyen';

 last_name | first_name | title
-----------+------------+-------
    Nguyen |       Bill |   Mr.

(1 rows)

In this command, we requested to return rows matching the primary key including all columns. For this query, we specified both of the columns referenced by the primary key. What happens when we only specify one of the values? Let’s find out.

cqlsh:my_keyspace> SELECT * FROM user where last_name = 'Nguyen';

 last_name | first_name | title
-----------+------------+-------
    Nguyen |       Bill |   Mr.

(1 rows)
cqlsh:my_keyspace> SELECT * FROM user where first_name = 'Bill';
InvalidRequest: Error from server: code=2200 [Invalid query] message="Cannot execute this
query as it might involve data filtering and thus may have unpredictable performance. If
you want to execute this query despite the performance unpredictability, use ALLOW FILTERING"

This behavior might not seem intuitive at first, but it has to do with the composition of the primary key we used for this table. This is our first clue that there might be something a bit different about accessing data in Cassandra as compared to what you might be used to in SQL. We’ll examine the significance of our primary key selection and the ALLOW FILTERING option in Chapter 4 and other chapters.

cqlsh:my_keyspace> SELECT COUNT (*) FROM user;
 count
-------
     1

(1 rows)

Warnings :
Aggregation query used without partition key

You can delete a column using the DELETE command. Here we will delete the title column from the row inserted above:

    cqlsh:my_keyspace> DELETE title FROM USER WHERE
      first_name='Bill' AND last_name='Nguyen';

We can perform this delete because the title column is not part of the primary key. To make sure that the value has been removed, we can query again:

cqlsh:my_keyspace> SELECT * FROM user WHERE first_name='Bill'
  AND last_name='Nguyen';

 last_name | first_name | title
-----------+------------+-------
    Nguyen |       Bill |  null

(1 rows)

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:

cqlsh:my_keyspace> DELETE FROM USER WHERE first_name='Bill'
  AND last_name='Nguyen';

To make sure that it’s removed, we can query again:

cqlsh:my_keyspace> SELECT * FROM user WHERE first_name='Bill'
  AND last_name='Nguyen';

 last_name | first_name | title
-----------+------------+-------

(0 rows)

If we really want to clean up after ourselves, we can remove all data from the table using the TRUNCATE command, or even delete the table schema using the DROP TABLE command.

cqlsh:my_keyspace> TRUNCATE user;
cqlsh:my_keyspace> DROP TABLE user;