Cassandra cqlsh Basics

cqlsh is the command-line interface for Cassandra. It stands for Cassandra Query Language Shell. You use it to run CQL commands, inspect your data, and manage keyspaces and tables. Think of cqlsh as the terminal window you use to talk directly to your Cassandra database.

Starting cqlsh

Open a terminal and type:

cqlsh

By default, cqlsh connects to 127.0.0.1 on port 9042. To connect to a remote node:

cqlsh 192.168.1.10 9042

Connect with a Username and Password

cqlsh -u cassandra -p cassandra

The default username and password for a fresh Cassandra installation are both cassandra.

The cqlsh Prompt

Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 6.1.0 | Cassandra 4.1.x | CQL spec 3.4.6]
Use HELP for help.
cqlsh>

The cqlsh> prompt tells you the shell is ready for your command. Every CQL statement ends with a semicolon (;).

Essential cqlsh Commands

DESCRIBE KEYSPACES

Lists all keyspaces in the cluster. A keyspace in Cassandra is equivalent to a database in MySQL.

cqlsh> DESCRIBE KEYSPACES;

system_auth  system  system_distributed  system_traces

USE a Keyspace

Switch to a keyspace so you do not have to prefix every table name with the keyspace name.

cqlsh> USE system;
cqlsh:system>

Notice the prompt changes to cqlsh:system> to show the active keyspace.

DESCRIBE TABLES

Lists all tables in the current keyspace.

cqlsh:system> DESCRIBE TABLES;

DESCRIBE TABLE

Shows the full structure of a specific table including columns, types, and primary key definition.

cqlsh:system> DESCRIBE TABLE local;

SELECT

Retrieves data from a table.

cqlsh> SELECT * FROM system.local;

Create Your First Keyspace and Table

Walk through this short exercise to see how cqlsh feels in practice.

Step 1: Create a Keyspace

cqlsh> CREATE KEYSPACE school
  WITH replication = {
    'class': 'SimpleStrategy',
    'replication_factor': 1
  };

Step 2: Switch to the Keyspace

cqlsh> USE school;
cqlsh:school>

Step 3: Create a Table

cqlsh:school> CREATE TABLE students (
  student_id UUID PRIMARY KEY,
  name TEXT,
  age INT,
  grade TEXT
);

Step 4: Insert a Row

cqlsh:school> INSERT INTO students (student_id, name, age, grade)
  VALUES (uuid(), 'Alice', 20, 'A');

Step 5: Read the Data

cqlsh:school> SELECT * FROM students;

 student_id                           | age | grade | name
--------------------------------------+-----+-------+-------
 3a2f1b00-4e7d-11ee-8000-000000000001 |  20 |     A | Alice

Useful cqlsh Meta-Commands

Meta-commands start with a backslash and control the shell itself rather than the database.

Command             What It Does
─────────────────────────────────────────────────────────────
HELP                Lists all available commands
EXIT or QUIT        Closes cqlsh
SOURCE 'file.cql'   Runs CQL commands from a file
COPY                Imports or exports CSV data
TRACING ON/OFF      Shows detailed query execution steps
PAGING ON/OFF       Controls how results are paginated
EXPAND ON/OFF       Shows each row in vertical format

EXPAND ON Example

Wide rows are hard to read in the default horizontal layout. EXPAND ON shows each column on its own line.

cqlsh:school> EXPAND ON;
cqlsh:school> SELECT * FROM students;

@ Row 1
------------+--------------------------------------
 student_id | 3a2f1b00-4e7d-11ee-8000-000000000001
 age        | 20
 grade      | A
 name       | Alice

COPY — Import CSV Data

cqlsh:school> COPY students (student_id, name, age, grade)
  FROM '/home/user/students.csv' WITH HEADER = true;

COPY — Export to CSV

cqlsh:school> COPY students TO '/home/user/students_export.csv'
  WITH HEADER = true;

TRACING ON

Use TRACING to understand how Cassandra executes a query — which nodes it contacted, how long each step took, and which SSTables it read.

cqlsh:school> TRACING ON;
cqlsh:school> SELECT * FROM students WHERE student_id = 3a2f1b00-...;

Tracing session: ...
 activity                              | timestamp  | source    | elapsed (µs)
 Execute CQL3 query                   | 14:02:01   | /127.0.0.1| 0
 Parsing SELECT ...                   | 14:02:01   | /127.0.0.1| 100
 ...

SOURCE — Run a CQL Script

Write your CQL commands in a text file and run the whole file at once.

cqlsh> SOURCE '/home/user/setup.cql';

Check Cassandra Version from cqlsh

cqlsh> SHOW VERSION;

[cqlsh 6.1.0 | Cassandra 4.1.x | CQL spec 3.4.6 | Native protocol v5]

Keyboard Shortcuts in cqlsh

Shortcut      Action
──────────────────────────────────────────
Up Arrow      Recall previous command
Ctrl + A      Move cursor to start of line
Ctrl + E      Move cursor to end of line
Ctrl + C      Cancel current input
Ctrl + D      Exit cqlsh

Summary

cqlsh is your primary tool for interacting with Cassandra from the command line. You connect, switch keyspaces, create tables, insert rows, query data, and export results — all from the cqlsh> prompt. Mastering cqlsh makes every other Cassandra topic more practical and concrete.