cqlsh

Start the CQL interactive terminal.

Start the CQL interactive terminal.

Synopsis 

cqlsh [options] [host [port]]
python cqlsh [options] [host [port]]

Description 

The Apache Cassandra™ installation includes the cqlsh utility, a python-based command line client for executing Cassandra Query Language (CQL) commands. The cqlsh command is used on the Linux or Windows command line to start the cqlsh utility. On Windows, the keyword python is used if the PATH environment variable does not point to the python installation.

You can use cqlsh to execute CQL commands interactively. cqlsh supports tab completion. You can also execute cqlsh commands, such as TRACE.

Requirements 

In Cassandra 2.1, the cqlsh utility uses the native protocol. In Cassandra 2.1, which uses the Datastax python driver, the default cqlsh listen port is 9042.

In Cassandra 2.0, the cqlsh utility uses the Thrift transport. In Cassandra 2.0.x, the default cqlsh listen port is 9160. By default, Cassandra 2.0.x and earlier enables Thrift by configuring start_rpc to true in the cassandra.yaml file. The cqlsh utility uses the Thrift RPC service. Also, firewall configuration to allow access through the Thrift port might be required.

For more information about configuration, see the Cassandra 2.1 cassandra.yaml or Cassandra 2.0 cassandra.yaml file.

Options 

-C, --color 
Always use color output.
--debug 
Show additional debugging information.
--cqlshrc path 
Use an alternative cqlshrc file location, path. (Cassandra 2.1.1)
-e cql_statement, --execute cql_statement 
Accept and execute a CQL command in Cassandra 2.1 and later. Useful for saving CQL output to a file.
-f file_name, --file=file_name 
Execute commands from file_name, then exit.
-h, --help 
Show the online help about these options and exit.
-k keyspace_name 
Use the given keyspace. Equivalent to issuing a USE keyspace command immediately after starting cqlsh.
--no-color 
Never use color output.
-p password 
Authenticate using password. Default = cassandra.
-t transport_factory_name, --transport=transport_factory_name 
Use the provided Thrift transport factory function.
-u user_name 
Authenticate as user. Default = cassandra.
--version 
Show the cqlsh version.

Using CQL commands 

On startup, cqlsh shows the name of the cluster, IP address, and the port used for connection to the cqlsh utility. The cqlsh prompt initially is cqlsh>. After you specify a keyspace to use, the prompt includes the name of the keyspace. For example:

cqlsh 1.2.3.4 9042 -u jdoe -p mypassword
Connected to trace_consistency at 1.2.3.4:9042.
[cqlsh 5.0.1 | Cassandra 2.1.0 | CQL spec 3.2 | Native protocol v3]
Use HELP for help.
cqlsh>USE mykeyspace;
cqlsh:mykeyspace>
At the cqlsh prompt, type CQL commands. Use a semicolon to terminate a command. A new line does not terminate a command, so commands can be spread over several lines for clarity. 
cqlsh> USE demo_cl;
cqlsh:demo_cl> SELECT * FROM demo_table
           ... WHERE id = 0;
If a command is sent and executed successfully, results are sent to standard output.

The lexical structure of commands, covered earlier in this reference, includes how upper- and lower-case literals are treated in commands, when to use quotation marks in strings, and how to enter exponential notation.

Saving CQL output in a file 

Using the -e option to the cqlsh command followed by a CQL statement, enclosed in quotation marks, accepts and executes the CQL statement. For example, to save the output of a SELECT statement to myoutput.txt:

cqlsh -e "SELECT * FROM mytable" > myoutput.txt

Using files as input 

To execute CQL commands in a file, use the -f option and the path to the file on the operating system command line. Or, after you start cqlsh, use the SOURCE command and the path to the file on the cqlsh command line.

cqlsh environment variables

You can override the default cqlsh host and listen port by setting the CQLSH_HOST and CQLSH_PORT environment variables. You set the CQLSH_HOST to a host name or IP address. When configured, cqlsh uses the variables instead of the default values of localhost and port 9042 (Cassandra 2.1 or later) or 9160 (Cassandra 2.0.x). A host and port number given on the command line takes precedence over configured variables.