cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Cassandra Wiki] Update of "CassandraCli" by MatthewChurcher
Date Sun, 18 Dec 2011 00:59:48 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cassandra Wiki" for change notification.

The "CassandraCli" page has been changed by MatthewChurcher:
http://wiki.apache.org/cassandra/CassandraCli?action=diff&rev1=38&rev2=39

- Cassandra ships with a very basic interactive command line interface, or shell. Using the
CLI you can connect to remote nodes in the cluster, create or update your schema, set and
retrieve records and columns, or query node and cluster meta-data (i.e. cluster name, keyspace
listings and disposition, etc). This page is intended for those using Cassandra 0.7.x. For
CLI docs on 0.6.x, see [[CassandraCli06 | this page]].
+ Cassandra ships with a very basic interactive command line interface. Using the CLI you
can connect to remote nodes in the cluster to create or update your schema and set and retrieve
records. 
  
- You can start the CLI using the `bin/cassandra-cli` startup script in your Cassandra installation.
+ The examples below have been tested with Cassandra 1.0.6. For instructions for previous
versions of Cassandra see one of: [[CassandraCli07]], [[CassandraCli06]].
+ a
+ == Starting the CLI ==
+ You can start the CLI using the {{{bin/cassandra-cli}}} script in your Cassandra installation
({{{bin\cassandra-cli.bat}}} on windows). The example below assumes that you are evaluating
a local cassandra node. If this is true ensure your node has been correctly configured and
successfully started before running the CLI. If you want to run commands on a remote node
you will need to specify the {{{-host}}} command line argument. Use {{{bin/cassandra-cli -?}}}
for more information on CLI arguments.
  
+ If successful you will see output similar to this:
  {{{
- evans@achilles:~/cassandra$ bin/cassandra-cli
  Welcome to cassandra CLI.
  
  Type 'help;' or '?' for help. Type 'quit;' or 'exit;' to quit.
- [default@unknown] connect localhost/9160;
+ connect localhost/9160;
  Connected to: "Test Cluster" on localhost/9160
- [default@unknown] create keyspace Twissandra;
- d105c4f1-3c93-11e0-9fb5-e700f669bcfc
- [default@unknown] use Twissandra;
- Authenticated to keyspace: Twissandra
- [default@Twissandra] create column family User with comparator = UTF8Type;
- 00389812-3c94-11e0-9fb5-e700f669bcfc
- [default@Twissandra] quit;
- evans@achilles:~/cassandra$
- }}}
- In the above example we started the cli with no options. You can specify things like `-host`,
`-port`, `-keyspace`, `-username`, `-password`, etc. Use `bin/cassandra-cli -?` for a full
set of options.
- 
- We went on to connect to our local Cassandra node. We created keyspace `Twissandra` and
column family `User`. Note that with the column family, we used a UTF8Type comparator.  That
means that the columns will be sorted based on UTF8Type sorting.  It also means that when
the column names are displayed on the command-line, they will be displayed as UTF8Type (readable)
text. For more information and options for creating column families type `help create column
family;` on the command line. Finally, we exited from our cli shell.
- 
- ----
- 
- '''Note: As of Cassandra 0.8, values are interpreted as bytes by default, so we will need
to declare a key_validation_class for the column family so we can enter text keys:'''
- 
- {{{ 
- update column family User with key_validation_class=UTF8Type; 
  }}}
  
- or, you can wrap each value to specify how it should be interpreted, e.g:
+ == Creating a Keyspace ==
+ We first create a keyspace to run our examples in.
+ 
+ {{{ create keyspace Twissandra; }}}
+ 
+ == Selecting the keyspace to user ==
+ We must then select our example keyspace as our new context before we can run any queries.
+ 
+ {{{ use Twissandra; }}}
+ 
+ == To Create A Column ==
+ We can then create a column to play with.
+ 
+ {{{create column family User with comparator = UTF8Type;}}}
+ 
+ For the later examples to work you must also update the schema using the following command.
This will set the return type for the first and last name to make them human readable. It
will also add and index for the age field so that you filter your gets using the Users name
field.
+ {{{
+ update column family User with                                                         
                              
+ 	column_metadata = 
+ 	[
+ 	{column_name: first, validation_class: UTF8Type},
+ 	{column_name: last, validation_class: UTF8Type},
+ 	{column_name: age, validation_class: UTF8Type, index_type: KEYS}
+ 	];
+ }}}
+ 
+ == To Add Data ==
+ To add data we want to into our new column we must first specify our default key type otherwise
we would have to specify it for each key using the format {{{[utf8('keyname')]}}} this is
probably advisable if you have mixed key types but makes simple cases harder to read.
+ 
+ So we run the command below, which will last the length of you cli session. On quitting
and restarting we must run it again.
+ 
+ {{{assume User keys as utf8;}}} 
+ 
+ and then we add our data.
  
  {{{
- set User[utf8('jsmith')]['first'] = 'John';
+ set User['jsmith']['first'] = 'John';
+ set User['jsmith']['last'] = 'Smith';
+ set User['jsmith']['age'] = '38';
  }}}
  
- or, you can temporarily `assume` a type (this must be repeated every CLI session)
+ If you get the error like this {{{cannot parse 'John' as hex bytes}}}, then it likely you
either haven't set your default key type or you haven't updated your schema as in the create
column example.
  
+ ''' The set command uses [[API#insert]]'''
+ == To Update Data ==
+ If we need to update a value we simply set it again.
- {{{
- assume User keys as utf8;
- set User['jsmith']['first'] = 'John';
- }}}
  
- ----
+ {{{set User['jsmith']['first'] = 'Jack';}}}
  
+ == To Get Data ==
- Let's get back into the shell with some options specified and create some data. You should
be aware that using the right assumption for your column family keys is 'essential' for the
CLI to work correctly. None of the data retrieval/manipulation commands will work as expected
if the key assumption is wrong. If you are just exploring cassandra from the CLI, you can
leave the assumptions at their defaults, though.
- 
- {{{
- tblose@quasar:~/dev/workspaces/cassandra$ bin/cassandra-cli -host localhost -port 9160
- Connected to localhost/9160
- Welcome to cassandra CLI.
- 
- Type 'help;' or '?' for help. Type 'quit;' or 'exit;' to quit.
- [default@unknown] use Twissandra;
- Authenticated to keyspace: Twissandra
- [default@Twissandra] set User['jsmith']['first'] = 'John';
- Value inserted.
- [default@Twissandra] set User['jsmith']['last'] = 'Smith';
- Value inserted.
- [default@Twissandra] set User['jsmith']['age'] = '39';
- Value inserted.
- }}}
- Note that before we can start adding data, we have to `use Twissandra;` to set our context.
We created a record in the `User` column family using the key `jsmith`. This record has three
columns, `first`, `last`, and `age`. Each of these commands is the equivalent to an `insert()`
using the [[API|Thrift API]].
- 
  Now let's read back the `jsmith` row to see what it contains:
  
+ {{{get User['jsmith'];}}}
- {{{
- [default@Twissandra] get User['jsmith'];
- => (column=age, value=3339, timestamp=1298504259386000)
- => (column=first, value=4a6f686e, timestamp=1298504239938000)
- => (column=last, value=536d697468, timestamp=1298504248570000)
- Returned 3 results.
- }}}
- Note: Using the `get` command in this form is the equivalent to a `get_slice()` using the
[[API|Thrift API]].
  
- Why are the values all hex? It's because the default validation class is !BytesType, which
displays in hex in the output. Let's update the column metadata of the column family to not
only make them output in a readable format, but also add a secondary index on age. We'll also
add another record so that we can see the secondary index work.
+ ''' The get command uses [[API#get_slice]]'''
  
+ == To Query Data ==
+ {{{ get User where age = '12'; }}}
- {{{
- [default@Twissandra] update column family User with                                    
                                                   
- ...	column_metadata = 
- ...	[
- ...	{column_name: first, validation_class: UTF8Type},
- ...	{column_name: last, validation_class: UTF8Type},
- ...	{column_name: age, validation_class: UTF8Type, index_type: KEYS}
- ...	];
- fd98427f-3fa6-11e0-8f42-e700f669bcfc
- [default@Twissandra] set User['zaphod']['first'] = 'Zaphod';
- Value inserted.
- [default@Twissandra] set User['zaphod']['last'] = 'Beeblebrox';
- Value inserted.
- [default@Twissandra] set User['zaphod']['age'] = '42';
- Value inserted.
- [default@Twissandra] get User where age = '42';
- -------------------
- RowKey: zaphod
- => (column=age, value=42, timestamp=1298504874382000)
- => (column=first, value=Zaphod, timestamp=1298504803709000)
- => (column=last, value=Beeblebrox, timestamp=1298504848982000)
  
+ == For  help ==
+ {{{ help; }}}
- 1 Row Returned.
- }}}
- In the above example, you can see that we can span commands over multiple lines. We add
column metadata that validates the column data as well as display value unencoded in the cli
output. We also add an index on age. The `KEYS` index type means that we can only perform
equality operations over it. We add one more row with an age of '42' and finally query the
column family for rows with an age of 42.
  
- One final thing that is very handy about the cassandra-cli, you can script your schema creation
in a file and run it through the cli. You just create a text file with any number of creation
commands and run the cli with the `-f` option:
+ == To Quit ==
+ {{{ quit; }}}
  
+ == To Execute Script ==
+ {{{bin/cassandra-cli -host localhost -port 9160 -f script.txt}}}
- {{{
- tblose@quasar:~/dev/workspaces/cassandra$ bin/cassandra-cli -host localhost -port 9160 -f
~/cassandra-schema.txt
- Connected to: "Test Cluster" on localhost/9160
- 1eafa8f4-3faf-11e0-a627-e700f669bcfc
- Authenticated to keyspace: Twissandra
- 1f09fdf5-3faf-11e0-a627-e700f669bcfc
- }}}
  
- with `cassandra-schema.txt`:
- 
- {{{
- create keyspace Twissandra;
- use Twissandra;
- 
- create column family User with
-   comparator = UTF8Type and
-   column_metadata =
-   [
-     {column_name: first, validation_class: UTF8Type},
-     {column_name: last, validation_class: UTF8Type},
-     {column_name: age, validation_class: UTF8Type, index_type: KEYS}
-   ];
- }}}
- 
- This has just been a brief introduction with a couple of examples. For more information
on how things work, type `help;` on the cli by itself or with any of the commands you're interested
in.
- 

Mime
View raw message