AttentionThis page documents an earlier version. Go to the latest (v2.3) version.
The YCQL shell (
ycqlsh) provides a CLI for interacting with YugabyteDB using YCQL.
cqlsh, the YCQL shell is now named
ycqlsh. Although the
cqlshbinary is available in the
bindirectory, it is deprecated and will be removed in a future release.
The YCQL shell (
ycqlsh) is installed as part of YugabyteDB and is located in the
bin directory of YugabyteDB home. It is also available for download and install from YugabyteDB's GitHub repository.
$ ./bin/ycqlsh --execute "select cluster_name, data_center, rack from system.local" 127.0.0.1 cluster_name | data_center | rack ---------------+-------------+------- local cluster | datacenter1 | rack1
ycqlsh --help to display the online help.
ycqlsh [flags] [host [port]]
hostis the IP address of the host on which YB-TServer is run. The default is local host at
portis the TCP port at which YB-TServer listens for YCQL connections. The default is
||Force color output|
||Disable color output|
||Specify the browser to use for displaying
||Use SSL when connecting to YugabyteDB|
||Username to authenticate against YugabyteDB with|
||Password to authenticate against YugabyteDB with, should be used in conjunction with
||Keyspace to authenticate to, should be used in conjunction with
||Execute commands from the given file, then exit|
||Print additional debugging information|
||UTF-8||Specify a non-default encoding for output.|
||Specify the location for the
||Execute the given statement, then exit|
||2||Specify the connection timeout in seconds|
||10||Specify the request timeout in seconds|
||Force tty mode (command prompt)|
In addition to supporting regular YCQL statements,
ycqlsh also supports the following special commands.
CONSISTENCY <consistency level>
Sets the consistency level for the read operations that follow. Valid arguments include:
||Read the strongly consistent results from the tablet's quorum. The read request will be processed by the tablet leader only. This is the default consistency level.|
||Read from a follower with relaxed consistency guarantees.|
To inspect the current consistency level, use
CONSISTENCY with no arguments.
ycqlsh, Cassandra, CQL, and native protocol versions in use. Example:
ycqlsh> SHOW VERSION
[ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Prints the IP address and port of the YB-TServer server that
ycqlsh is connected to in addition to the cluster name. Example:
ycqlsh> SHOW HOST
Connected to local cluster at 127.0.0.1:9042.
Reads the contents of a file and executes each line as a YCQL statement or special
ycqlsh> SOURCE '/home/yugabyte/commands.cql'
Begins capturing command output and appending it to a specified file. Output will not be shown at the console while it is captured.
CAPTURE '<file>' CAPTURE OFF CAPTURE
- The path to the file to be appended to must be given inside a string literal. The path is interpreted relative to the current working directory. The tilde shorthand notation (
~/mydir) is supported for referring to
- Only query result output is captured. Errors and output from ycqlsh-only commands will still be shown in the
- To stop capturing output and show it in the
ycqlshsession again, use
- To inspect the current capture configuration, use
CAPTUREwith no arguments.
Gives information about
ycqlsh commands. To see available topics, enter
HELP without any arguments. To see help on a topic, use
HELP <topic>. Also see the
--browser argument for controlling what browser is used to display help.
Enables paging, disables paging, or sets the page size for read queries. When paging is enabled, only one page of data will be fetched at a time and a prompt will appear to fetch the next page. Generally, it’s a good idea to leave paging enabled in an interactive session to avoid fetching and printing large amounts of data at once.
PAGING ON PAGING OFF PAGING <page size in rows>
To inspect the current paging setting, use
PAGING with no arguments.
Enables or disables vertical printing of rows. Enabling EXPAND is useful when many columns are fetched, or the contents of a single column are large.
EXPAND ON EXPAND OFF
To inspect the current expand setting, use
EXPAND with no arguments.
Authenticate as a specified YugabyteDB user for the current session.
LOGIN <username> [<password>]
Ends the current session and terminates the
Clears the console.
Prints a description (typically a series of DDL statements) of a schema element or the cluster. This is useful for dumping all or portions of the schema.
DESCRIBE CLUSTER DESCRIBE SCHEMA DESCRIBE KEYSPACES DESCRIBE KEYSPACE <keyspace name> DESCRIBE TABLES DESCRIBE TABLE <table name> DESCRIBE INDEX <index name> DESCRIBE TYPES DESCRIBE TYPE <type name>
In any of the commands,
DESC may be used in place of
DESCRIBE CLUSTER command prints the cluster namer:
ycqlsh> DESCRIBE CLUSTER
Cluster: local cluster
DESCRIBE SCHEMA command prints the DDL statements needed to recreate the entire schema. This is especially useful for dumping the schema in order to clone a cluster or restore from a backup.
Copies data from a table to a CSV file.
COPY <table name> [(<column>, ...)] TO <file name> WITH <copy flag> [AND <copy flag> ...]
If no columns are specified, all columns from the table will be copied to the CSV file. A subset of columns to copy may be specified by adding a comma-separated list of column names surrounded by parenthesis after the table name.
file name should be a string literal (with single quotes) representing a path to the destination file. This can also the special value
STDOUT (without single quotes) to print the CSV to stdout.
||6||The maximum number token ranges to fetch simultaneously.|
||1000||The number of rows to fetch in a single page.|
||10||The timeout in seconds per 1000 entries in the page size or smaller.|
||Token range to export. Defaults to exporting the full ring.|
||-1||The maximum size of the output file measured in number of lines; beyond this maximum the output file will be split into segments. -1 means unlimited.|
||utf8||The encoding used for characters.|
The following flags are common to both
COPY TO and
||The string placeholder for null values.|
||The character that is used as the decimal point separator.|
||The character that is used to separate thousands. Defaults to the empty string.|
||The string literal format for boolean values.|
||The number of child worker processes to create for
||5||The maximum number of failed attempts to fetch a range of data (when using
||0.25||How often status updates are refreshed, in seconds.|
||An optional file to output rate statistics to. By default, statistics are not output to a file.|
Copies data from a CSV file to table.
COPY <table name> [(<column>, ...)] FROM <file name> WITH <copy flag> [AND <copy flag> ...]
If no columns are specified, all columns from the CSV file will be copied to the table. A subset of columns to copy may be specified by adding a comma-separated list of column names surrounded by parenthesis after the table name.
file name should be a string literal (with single quotes) representing a path to the source file. This can also the special value
STDIN (without single quotes) to read the CSV data from stdin.
||100000||The maximum number of rows to process per second.|
||-1||The maximum number of rows to import. -1 means unlimited.|
||0||A number of initial rows to skip.|
||A comma-separated list of column names to ignore. By default, no columns are skipped.|
||-1||The maximum global number of parsing errors to ignore. -1 means unlimited.|
||1000||The maximum global number of insert errors to ignore. -1 means unlimited.|
||A file to store all rows that could not be imported, by default this is
||20||The max number of rows inserted in a single batch.|
||2||The min number of rows inserted in a single batch.|
||1000||The number of rows that are passed to child worker processes from the main process at a time.|
COPY TO for additional flags common to both
COPY TO and