cqlsh startup options

Synopsis

cqlsh [ <options> ] [ <host_name>[:<port_number>] ]

Syntax legend

Legend
Syntax conventions	Description
UPPERCASE	Literal keyword.
Lowercase	Not literal.
`< >`	Variable value. Replace with a user-defined value.
`[]`	Optional. Square brackets (`[]`) surround optional command arguments. Do not type the square brackets.
`( )`	Group. Parentheses ( `( )` ) identify a group to choose from. Do not type the parentheses.
`\|`	Or. A vertical bar (`\|`) separates alternative elements. Type any one of the elements. Do not type the vertical bar.
`...`	Repeatable. An ellipsis ( `...` ) indicates that you can repeat the syntax element as often as required.
`'<Literal string>'`	Single quotation (`'`) marks must surround literal strings in CQL statements. Use single quotation marks to preserve upper case.
`{ <key> : <value> }`	Map collection. Braces (`{ }`) enclose map collections or key value pairs. A colon separates the key and the value.
`<datatype2`	Set, list, map, or tuple. Angle brackets ( `< >` ) enclose data types in a set, list, map, or tuple. Separate the data types with a comma.
`<cql_statement>;`	End CQL statement. A semicolon (`;`) terminates all CQL statements.
`[--]`	Separate the command line options from the command arguments with two hyphens ( `--` ). This syntax is useful when arguments might be mistaken for command line options.
`' <<schema\> ... </schema\>> '`	Search CQL only: Single quotation marks (`'`) surround an entire XML schema declaration.
`@<xml_entity>='<xml_entity_type>'`	Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.

Required parameters

host_name:port: To connect the CQL session to a specified node, specify a hostname or IP address and optional port after the cqlsh command, along with any additional CQL shell options.

By default, the CQL shell launches a session with the local host on address 127.0.0.1. You can connect the CQL shell to remote hosts that have a higher or equal CQL shell version than the local CQL shell version. When no port is specified, the connection uses the default port of 9042.

Options

Option

Description

--browser="<launch_browser_cmd> %s"

Browser to display the CQL command help. Replace the URL in the command with %s.

-C, --color

Always use color output.

--connect-timeout="<timeout>"

Connection timeout in seconds.

Default: 5

--cqlshrc="/<folder_name>"

Folder that contains the cqlshrc file. Use tilde (~) for paths relative to the user’s home directory.

--cqlversion="<version_number>"

CQL version to use. The CQL version displays after starting cqlsh.

--debug

Show additional debugging information.

--disable-history

Disables saving history to disk for current execution.

--dse-protocol-version=<DSE_PROTOCOL_VERSION>

Specify a specific DSE protocol version; otherwise the client will default and downgrade as necessary. Mutually exclusive with --protocol-version.

--encoding="<output_encoding>"

Output encoding.

Default encoding: utf8

--execute="<cql_statement>"

Execute the CQL statement, then exit. To direct the command output to a file, see saving CQL output.

-f <file_name>, --file=<file_name>

Execute commands from a CQL file, then exit.

After starting cqlsh, use the SOURCE command and the path to the file using the cqlsh command line.

-h, --help

Show help.

-k <keyspace_name>, --keyspace=<keyspace_name>

Automatically use the specified keyspace after starting the CQL shell.

--no-color

Do not display color output.

-p <password>, --password="<password>"

Connect with the specified user’s password.

--protocol-version=<PROTOCOL_VERSION>

Specify a specific protocol version. If omitted, the client will use a default, and possibly lower version protocol, as needed.Mutually exclusive with --dse-protocol-version.

--request-timeout="<timeout>"

CQL request timeout in seconds.

Default: 10

--consistency-level <consistency_level>

Specify the initial consistency level.

Default: ONE

--serial-consistency-level <serial_consistency_level>

Specify the initial serial consistency level.

Default: SERIAL

--ssl

Use SSL.

-t, --tty

Force TTY command prompt mode.

-u <user_name>, --username="<user_name>"

Connect with the specified user account.

--version

Show the cqlsh version number.

Environment variables

You can use environment variables to overwrite default values for cqlsh commands. For example, increase the timeout values of a user running cqlsh on a particular computer.

Examples

Start the CQL shell

On start up, cqlsh shows the name of the cluster, IP address, and connection port. The cqlsh prompt initially is cqlsh>. If you specify a keyspace, it is added after the prompt.

Start the CQL shell:

cqlsh

The cluster and host information appears. For example:

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

Use the cycling keyspace:
```
USE cycling;
```
The prompt now includes the keyspace name:
```
cqlsh:cycling>
```

Query using CQL commands

At the cqlsh prompt, you can enter CQL commands. Use a semicolon to terminate a command. A new line does not terminate a command, and commands can be spread over several lines. For example:

SELECT *
FROM calendar
WHERE race_id = 201;

The returned results are shown in the standard output:

 race_id | race_start_date                 | race_end_date                   | race_name
---------+---------------------------------+---------------------------------+-----------------------------
     201 | 2015-02-18 08:00:00.000000+0000 | 2015-02-22 08:00:00.000000+0000 | Women's Tour of New Zealand

For more information about writing CQL queries, see CQL command syntax.

Save CQL output in a file

To save output from a CQL statement to a file, use the cqlsh -e option, followed by the CQL statement placed inside quotation marks, and redirect the output to a file.

For example, to save the output of a SELECT statement to myoutput.txt:

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

Connect to a remote node

Specify a remote node IP address:

cqlsh 10.0.0.30

Connected to West CS Cluster at 10.0.0.30:9042.
[cqlsh 5.0.1 | Cassandra 3.3.0 | CQL spec 3.4.0 | Native protocol v4]
Use HELP for help.