cqlsh (startup options)
Describes the options for starting the CQL shell.
Execute the cqlsh
Python script to start the CQL
shell. The CQL shell is a Python-based command line interface for running CQL commands interactively. The CQL shell
supports tab completion. The cqlsh
command run in either Python 2
or 3.
Synopsis
cqlsh [ options ] [ host_name[:port_number] ]
Syntax conventions | Description |
---|---|
UPPERCASE | Literal keyword. |
Lowercase | Not literal. |
Italics |
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. |
<datatype1,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. |
- --browser="launch_browser_cmd %s"
- Browser to display the CQL command help. See Web Browser Control for a list of supported browsers. 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.Note: After starting cqlsh, use the SOURCE command and the path to the file using the cqlsh command line.
- -h, --help
- Show help.
- 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.
- -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
. - --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
- CQLSH_SEARCH_MANAGEMENT_TIMEOUT_SECONDS
- Overwrite the default 600 seconds (10 minutes) request timeout for search-specific
CQL statements. To prevent timeouts, increase the timeout value. Typical use case is
to ensure that no timeouts occur when large indexes are reloaded. The timeout applies only to these search CQL index management commands:
- ALTER SEARCH INDEX
- COMMIT SEARCH INDEX
- CREATE SEARCH INDEX
- DESCRIBE SEARCH INDEX
- DROP SEARCH INDEX
- RELOAD SEARCH INDEX
- REBUILD SEARCH INDEX
The timeout is used only if the cqlsh request timeout is equal to the default value of 10 seconds:cqlsh --request-timeout 10
To increase the timeout request timeout for search-specific CQL statements to 15 minutes (900 seconds):export CQLSH_SEARCH_MANAGEMENT_TIMEOUT_SECONDS=900;
Examples
Starting 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>
Querying using CQL commands
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
Understanding the CQL command syntax describes:
- How upper- and lower-case literals are treated in commands.
- When to use quotation marks in strings.
- How to enter exponential notation.
Saving 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
Connecting 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.