cassandra/README.asc

Executive summary
-----------------

Cassandra is a partitioned row store.  Rows are organized into tables with a required primary key.

https://cwiki.apache.org/confluence/display/CASSANDRA2/Partitioners[Partitioning] means that Cassandra can distribute your data across multiple machines in an application-transparent matter. Cassandra will automatically repartition as machines are added and removed from the cluster.

https://cwiki.apache.org/confluence/display/CASSANDRA2/DataModel[Row store] means that like relational databases, Cassandra organizes data by rows and columns. The Cassandra Query Language (CQL) is a close relative of SQL.

For more information, see http://cassandra.apache.org/[the Apache Cassandra web site].

Requirements
------------
. Java >= 1.8 (OpenJDK and Oracle JVMS have been tested)
. Python 2.7 (for cqlsh)

Getting started
---------------

This short guide will walk you through getting a basic one node cluster up
and running, and demonstrate some simple reads and writes.

First, we'll unpack our archive:

  $ tar -zxvf apache-cassandra-$VERSION.tar.gz
  $ cd apache-cassandra-$VERSION

After that we start the server.  Running the startup script with the -f argument will cause
Cassandra to remain in the foreground and log to standard out; it can be stopped with ctrl-C.

  $ bin/cassandra -f

****
Note for Windows users: to install Cassandra as a service, download
http://commons.apache.org/daemon/procrun.html[Procrun], set the
PRUNSRV environment variable to the full path of prunsrv (e.g.,
C:\procrun\prunsrv.exe), and run "bin\cassandra.bat install".
Similarly, "uninstall" will remove the service.
****

Now let's try to read and write some data using the Cassandra Query Language:

  $ bin/cqlsh

The command line client is interactive so if everything worked you should
be sitting in front of a prompt:

----
Connected to Test Cluster at localhost:9160.
[cqlsh 2.2.0 | Cassandra 1.2.0 | CQL spec 3.0.0 | Thrift protocol 19.35.0]
Use HELP for help.
cqlsh>
----

As the banner says, you can use 'help;' or '?' to see what CQL has to
offer, and 'quit;' or 'exit;' when you've had enough fun. But lets try
something slightly more interesting:

----
cqlsh> CREATE KEYSPACE schema1
       WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
cqlsh> USE schema1;
cqlsh:Schema1> CREATE TABLE users (
                 user_id varchar PRIMARY KEY,
                 first varchar,
                 last varchar,
                 age int
               );
cqlsh:Schema1> INSERT INTO users (user_id, first, last, age)
               VALUES ('jsmith', 'John', 'Smith', 42);
cqlsh:Schema1> SELECT * FROM users;
 user_id | age | first | last
---------+-----+-------+-------
  jsmith |  42 |  john | smith
cqlsh:Schema1>
----

If your session looks similar to what's above, congrats, your single node
cluster is operational!

For more on what commands are supported by CQL, see
https://github.com/apache/cassandra/blob/trunk/doc/cql3/CQL.textile[the CQL reference].  A
reasonable way to think of it is as, "SQL minus joins and subqueries, plus collections."

Wondering where to go from here?

  * Getting started: http://wiki.apache.org/cassandra/GettingStarted
  * Join us in #cassandra on irc.freenode.net and ask questions
  * Subscribe to the Users mailing list by sending a mail to
    user-subscribe@cassandra.apache.org
  * Planet Cassandra aggregates Cassandra articles and news:
    http://planetcassandra.org/