Key-Value

The simplest data model is key-value . You have probably already used this paradigm within a programming language. In a nutshell, it is a hash table.

Given a key, you can access the content (value), as demonstrated in Figure 5-4.

Figure 5-4. You can imagine this data model as a big hash. The key allows access to certain <content>. This <content> can be different types of data, which makes it a much more flexible structure.

Column-Family

An important part of this data model is that the storage and fetch processes are made from columns and not from rows. Also, a lot of the data model is done in memory, and you already know how important that is.

What’s a column? It is a tuple containing key-value pairs. In the case of several NoSQL, this tuple is formed by three pairs: name/key, value, and one timestamp.

In this model, several columns (the family) are grouped by a key called a row-key. Figure 5-5 shows this relationship.

Figure 5-5. A key (row-key) can access the column family. This group exemplifies the data model column-family

The main advantage of this model is that it substantially improves write operations, which improves their performance in distributed environments.⁶

Prerequisites

Apache Cassandra requires Java version 7 or 8, preferably the Oracle/Sun distribution. The documentation indicates that it is also compatible with OpenJDK, Zing, and IBM distributions.

File Download

The first step is to download the .zip file distribution downloaded from http://cassandra.apache.org/download/ .

On the Apache Cassandra project home page (see Figure 5-9 and http://cassandra.apache.org ), the project logo reminds us of the seeing ability of the mythological character.

Figure 5-9. Cassandra project home page

Locate the following file:

apache-cassandra-3.4-bin.tar.gz

It’s important to validate file integrity. You do not want it to fail while it’s running. This particular file has the following values to validate its integrity:

[MD5] e9f490211812b7db782fed09f20c5bb0
[SHA1]7d010b8cc92d5354f384b646b302407ab90be1f0

It’s easy to make this validation. Any flavor of Linux gives the md5 and sha1sum commands, as shown in the following:

%> md5sum apache-cassandra-3.4-bin.tar.gz
e9f490211812b7db782fed09f20c5bb0  apache-cassandra-3.4-bin.tar.gz

%> sha1sum apache-cassandra-3.4-bin.tar.gz
7d010b8cc92d5354f384b646b302407ab90be1f0  apache-cassandra-3.4-bin.tar.gz

%> ls -lrt apache-cassandra-3.4-bin.tar.gz
-rw-r--r--. 1 rugi rugi 34083682 Mar  7 22:06 apache-cassandra-3.4-bin.tar.gz

Once you have validated the file’s integrity, you can unzip it and continue.

Start

Starting Apache Cassandra is easy; you only execute the following:

./cassandra -f
INFO  18:06:58 Starting listening for CQL clients on localhost/127.0.0.1:9042 (unencrypted)...
INFO  18:06:58 Not starting RPC server as requested. Use JMX (StorageService->startRPCServer()) or nodetool (enablethrift) to start it
INFO  18:07:07 Scheduling approximate time-check task with a precision of 10 milliseconds
INFO  18:07:07 Created default superuser role 'cassandra'

With this command, your server Apache Cassandra is ready to receive requests. You must always keep in mind that Apache Cassandra runs with a client-server approach. You have launched the server; the server is responsible for receiving requests from clients and then giving them answers. So now you need to validate that clients can send requests.

The next step is to use the CLI validation tool, an Apache Cassandra client.

Validation

Now, let’s execute the CLI tool.

%> ./cqlsh
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 3.4 | CQL spec 3.4.0 | Native protocol v4]
Use HELP for help.
cqlsh>

The first step is to create a keyspace, an analogy with relational databases in which you define the database, per se.

%>CREATE KEYSPACE mykeyspace WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };

Once the keyspace is defined, indicate that you will use it.

USE mykeyspace;

This is a familiar sentence, isn’t?

Apache Cassandra, like other NoSQL frameworks, tries to use analogies with the SQL statements that you already know.

And if you have already defined the database, do you remember what is next? Now you create a test table.

%> CREATE TABLE users (  user_id int PRIMARY KEY,  fname text,  lname text);

And, having the table, inserting records is simple, as you can see in the following:

%>INSERT INTO users (user_id,  fname, lname)  VALUES (1745, 'john', 'smith');
%>INSERT INTO users (user_id,  fname, lname)  VALUES (1744, 'john', 'doe');
%>INSERT INTO users (user_id,  fname, lname)  VALUES (1746, 'john', 'smith');

You make a simple query, like this:

%>SELECT * FROM users;

And, you should have the following results (or similar, if you already modified the data with the inserts):

 user_id | fname | lname
---------+-------+-------
    1745 |  john | smith
    1744 |  john |   doe
    1746 |  john | smith

With Apache Cassandra, you can create indexes on the fly:

CREATE INDEX ON users (lname);

To facilitate searches on specific fields, do this:

SELECT * FROM users WHERE lname = 'smith';

This is the result:

 user_id | fname | lname
---------+-------+-------
    1745 |  john | smith
    1746 |  john | smith

And that’s it. This is enough to validate that communication between your CLI and your Cassandra server is working properly.

Here is the complete output from the previous commands:

{16-03-21 14:05}localhost:∼/opt/apache/cassandra/apache-cassandra-3.4/bin rugi% cd /home/rugi/opt/apache/cassandra/apache-cassandra-3.4/bin
{16-03-21 14:05}localhost:∼/opt/apache/cassandra/apache-cassandra-3.4/bin rugi% ./cqlsh
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 3.4 | CQL spec 3.4.0 | Native protocol v4]
Use HELP for help.
cqlsh> CREATE KEYSPACE mykeyspace WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
cqlsh> USE mykeyspace;
cqlsh:mykeyspace> CREATE TABLE users (  user_id int PRIMARY KEY,  fname text,  lname text);
cqlsh:mykeyspace> INSERT INTO users  (user_id,  fname, lname)  VALUES (1745, 'john', 'smith');
cqlsh:mykeyspace> INSERT INTO users  (user_id,  fname, lname)  VALUES (1744, 'john', 'doe');
cqlsh:mykeyspace> INSERT INTO users  (user_id,  fname, lname)  VALUES (1746, 'john', 'smith');

cqlsh:mykeyspace> SELECT * FROM users;
user_id | fname | lname
---------+-------+-------
    1745 |  john | smith
    1744 |  john |   doe
    1746 |  john | smith
(3 rows)

cqlsh:mykeyspace> CREATE INDEX ON users (lname);
cqlsh:mykeyspace> SELECT * FROM users WHERE lname = 'smith';
user_id | fname | lname
---------+-------+-------
    1745 |  john | smith
    1746 |  john | smith
(2 rows)

cqlsh:mykeyspace> exit
{16-03-21 15:24}localhost:∼/opt/apache/cassandra/apache-cassandra-3.4/bin rugi%

You should have two terminals open: one with the server running and the other one with CLI running. If you check the first one, you will see how CLI is processing the requests. Figure 5-10 shows the server running.

Figure 5-10. Cassandra server running

Figure 5-11 is a screenshot of running the test commands described earlier.

Figure 5-11. CQL running on CQLs

CQL

CQL (Cassandra Query Language) is a language similar to SQL. The queries on a keyspace are made in CQL.

http://docs.datastax.com/en/cql/3.1/cql/cql_reference/cqlshCommandsTOC.html

{16-04-15 23:54}localhost:∼/opt/apache/cassandra/apache-cassandra-3.4/bin rugi% ./cqlsh        
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 3.4 | CQL spec 3.4.0 | Native protocol v4]
Use HELP for help.

cqlsh> describe keyspaces

system_schema  system      system_distributed
system_auth    mykeyspace  system_traces    

cqlsh> describe mykeyspace

CREATE KEYSPACE mykeyspace WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;

CREATE TABLE mykeyspace.users (
    user_id int PRIMARY KEY,
    fname text,
    lname text
) 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': '64','class': 'org.apache.cassandra.io.compress.  LZ4Compressor'}
    AND crc_check_chance = 1.0
    AND dclocal_read_repair_chance = 0.1
    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 = '99PERCENTILE';
CREATE INDEX users_lname_idx ON mykeyspace.users (lname);

cqlsh> show version
[cqlsh 5.0.1 | Cassandra 3.4 | CQL spec 3.4.0 | Native protocol v4]
cqlsh>

http://docs.datastax.com/en/cql/3.1/cql/cql_reference/cqlCommandsTOC.html

{16-04-16 6:19}localhost:∼/opt/apache/cassandra/apache-cassandra-3.4/bin rugi% ./cqlsh
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 3.4 | CQL spec 3.4.0 | Native protocol v4]
Use HELP for help.

cqlsh> use mykeyspace;

cqlsh:mykeyspace> describe tables users

cqlsh:mykeyspace> describe users

CREATE TABLE mykeyspace.users (
    user_id int PRIMARY KEY,
    fname text,
    lname text
) 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': '64', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
    AND crc_check_chance = 1.0
    AND dclocal_read_repair_chance = 0.1
    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 = '99PERCENTILE';
CREATE INDEX users_lname_idx ON mykeyspace.users (lname);
cqlsh:mykeyspace> exit

Drivers

A driveris a software component that allows access to a keyspace to run CQL statements.

Figure 5-13 illustrates accessing clients through the use of a driver. A driver can access a keyspace and also allows the execution of CQL sentences.

Figure 5-13. To access a Cassandra server, a driver is required

Fortunately, there are a lot of these drivers for Cassandra in almost any modern programming language. You can see an extensive list at http://wiki.apache.org/cassandra/ClientOptions .

Currently, there are different drivers to access a keyspace in almost all modern programming languages. Typically, in a client-server architecture, there are clients accessing the server from different clients, which are distributed in different networks, therefore, Figure 5-13 may now look like what’s shown in Figure 5-14.

Figure 5-14. Different clients connecting to a Cassandra server through the cloud

The Figure 5-14 illustrates that given the distributed characteristics that modern systems require, the clients actually are in different points and access the Cassandra server through public and private networks.

Your implementation needs will dictate the required clients.

All languages offer a similar API through the driver. Consider the following code snippets in Java, Ruby, and Node.

<dependency>
    <groupId>com.datastax.cassandra</groupId>
    <artifactId>cassandra-driver-core</artifactId>
    <version>3.0.2</version>
</dependency>

import com.datastax.driver.core.Cluster;
import com.datastax.driver.core.ResultSet;
import com.datastax.driver.core.Row;
import com.datastax.driver.core.Session;
import java.util.Iterator;

...

    public static void main(String[] args) {
        Cluster cluster = Cluster.builder().addContactPoint("127.0.0.1").build();
        Session session = cluster.connect("mykeyspace");
        ResultSet results = session.execute("SELECT * FROM users");
        StringBuilder line = new StringBuilder();

        for (Iterator<Row> iterator = results.iterator(); iterator.hasNext();) {
            Row row = iterator.next();
            line.delete(0, line.length());
            line.append("FirstName = ").                  
                    append(row.getString("fname")).
                    append(",").append(" ").
                    append("LastName = ").
                    append(row.getString("lname"));
            System.out.println(line.toString());
        }
    }

%>gem install cassandra-driver

require 'cassandra'

node = '127.0.0.1'
cluster = Cassandra.cluster(hosts: node)
keyspace = 'mykeyspace'
session  = cluster.connect(keyspace)
session.execute("SELECT fname, lname FROM users").each do |row|
            p "FirstName = #{row['fname']}, LastName = #{row['lname']}"
end

%>npm install cassandra-driver
%>npm install async

var cassandra = require('cassandra-driver');
var async = require('async');

var client = new cassandra.Client({contactPoints: ['127.0.0.1'], keyspace: 'mykeyspace'});
client.stream('SELECT fname, lname FROM users', [])
  .on('readable', function () {
               var row;
                   while (row = this.read()) {
                                 console.log('FirstName =  %s , LastName= %s', row.fname, row.lname);
                                     }
                     })
  .on('end', function () {
             //todo
             })
  .on('error', function (err) {
                // todo
             });
</code>

"FirstName = john, LastName = smith"
"FirstName = john, LastName = doe"
"FirstName = john, LastName = smith"

 http://www.planetcassandra.org/apache-cassandra-client-drivers/

Machine01

Our first machine has the address 107.170.38.238 and it is the seed. It starts first when you finish setting up the three machines.

Locate the CASSANDRA HOME/conf/cassandra.yaml file and make the following modifications. All nodes in the cluster must have the same cluster_name.

cluster_name: 'BedxheCluster'
num_tokens: 256
seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
          - seeds: “107.170.38.238”
listen_address: 107.170.38.238
rpc_address: 0.0.0.0
broadcast_rpc_address: 1.2.3.4
endpoint_snitch: RackInferringSnitch

Machine02

Our second machine has the address 107.170.112.81. Its setting only changes the value of listen_address.

cluster_name: 'BedxheCluster'
num_tokens: 256
seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
          - seeds: "107.170.38.238"
listen_address: 107.170.112.81
rpc_address: 0.0.0.0
broadcast_rpc_address: 1.2.3.4
endpoint_snitch: RackInferringSnitch

Machine03

Our third machine has the address 107.170.115.161. Its setting also only changes the value of listen_address.

cluster_name: 'BedxheCluster'
num_tokens: 256
seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
          - seeds: "107.170.38.238"
listen_address: 107.170.115.161
rpc_address: 0.0.0.0
broadcast_rpc_address: 1.2.3.4
endpoint_snitch: RackInferringSnitch

You have now finished the configuration of the nodes.

Booting the Cluster

You first started Cassandra in the seed node (removing the -f flag, Cassandra starts the process and passes the background).

MACHINE01/CASSANDRA_HOME/bin%>./cassandra
After you started cassandra in the other two nodes.
MACHINE02/CASSANDRA_HOME/bin%>./cassandra
MACHINE03/CASSANDRA_HOME/bin%>./cassandra

Now, if you execute nodetool in any of the machines, you see something like the following.

CASSANDRA_HOME/bin>./nodetool status
Datacenter: 170
===============
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address         Load         Tokens  Owns        Host ID                              Rack                                       (effective)                    
UN  107.170.38.238    107.95 KiB   256     68.4%       23e16126-8c7f-4eb8-9ea0-40ae488127e8  38
UN  107.170.115.161   15.3 KiB     256     63.7%       b3a9970a-ff77-43b2-ad4e-594deb04e7f7  115
UN  107.170.112.81    102.49 KiB   256     67.9%       ece8b83f-d51d-43ce-b9f2-89b79a0a2097  112

Now, if you repeat the creation of the keyspace example in the seed node, you will see how the keyspace is available in the other nodes. And conversely, if you apply a change to the keyspace in any node, it is immediately reflected in the others.

Execute the following in machine01 (the seed machine):

MACHINE01_CASSANDRA_HOME/bin%> ./cqlsh

cqlsh>CREATE KEYSPACE mykeyspace WITH REPLICATION = { ‘class’ : ‘SimpleStrategy’, ‘replication_factor’ : 1 };
cqlsh>USE mykeyspace;
cqlsh>CREATE TABLE users (user_id int PRIMARY KEY,  fname text,  lname text);
cqlsh>INSERT INTO users (user_id,  fname, lname)  VALUES (1745, ‘john’, ‘smith’);
cqlsh>INSERT INTO users (user_id,  fname, lname)  VALUES (1744, ‘john’, ‘doe’);
cqlsh>INSERT INTO users (user_id,  fname, lname)  VALUES (1746, ‘john’, ‘smith’);

Execute the following in machine02 or machine03:

CASSANDRA_HOME/bin%>./cqlsh
cqlsh> use mykeyspace;
cqlsh:mykeyspace> select * from users;

 user_id | fname | lname
---------+-------+-------
    1745 |  john | smith
    1744 |  john |   doe
    1746 |  john | smith

(3 rows)

That’s it. You have a cluster of three nodes working properly.