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. -
