Keyspaces and tables

This page explores keyspaces and tables in YCQL using the command line shell ycqlsh.

Before you start

The examples will run on any YugabyteDB universe.
To create a universe, see Set up YugabyteDB universe.

YCQL shell

Use the ycqlsh shell to interact with a Yugabyte database cluster using the YCQL API. Because ycqlsh is derived from the Apache Cassandra shell cqlsh, most cqlsh commands work as is in ycqlsh. Unsupported commands are listed at the end of this page.

Using ycqlsh, you can:

  • interactively enter YCQL DDL and DML and see the query results
  • input from a file or the command line
  • use tab completion to automatically complete commands
  • use a minimal command name as long as it can be distinguished from other commands (for example, desc instead of DESCRIBE)

ycqlsh is installed with YugabyteDB and is located in the bin directory of the YugabyteDB home directory.

Connect to a node

From your YugabyteDB home directory, connect to any node of the database cluster as follows:

$ ./bin/ycqlsh

This should bring up the following prompt, which prints the version of ycqlsh being used.

Connected to local cluster at
[ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.


By default, YugabyteDB has one admin user already created: cassandra (the recommended user), and you can check the existing user as follows:

ycqlsh> select * from system_auth.roles;

You should see an output similar to the following:

 role      | can_login | is_superuser | member_of | salted_hash
 cassandra |      True |         True |          [] | $2a$12$64A8Vo0R3K9XeUp26CSzpuWtvUBwOiGFjPAbXGt7wsxZIScGrcsDu\x00\x00\x00\x00


A keyspace is a container for a set of tables that belong together somehow. If multiple applications are using a single database, the tables belonging to each application can be grouped into a separate keyspace. In Apache Cassandra, replication configuration is done at the keyspace level. So, all tables that require the same replication configuration may be grouped into a keyspace. This pattern does not apply to YugabyteDB because in YugabyteDB replication configuration is done at the universe level.

To create a new keyspace testdb, run the following statement:

ycqlsh> CREATE KEYSPACE testdb;

To list all keyspaces, use the following command:

system_schema  system_auth  testdb  system

To use a specific keyspace, use the following command:

ycqlsh> USE testdb;

You should see the following output:


To drop the keyspace you just created, use the DROP command as follows:

ycqlsh> DROP KEYSPACE testdb;

Verify the keyspace is no longer present as follows:

system_schema  system_auth  system


Create a table using the CREATE TABLE statement.

  id UUID,
  username TEXT,
  enabled boolean,

To list all tables, use the following command:

ycqlsh:testdb> DESCRIBE TABLES;


To describe the table you created, enter the following:

ycqlsh> DESCRIBE TABLE users;
ycqlsh:testdb> describe table users;

CREATE TABLE testdb.users (
    id uuid PRIMARY KEY,
    username text,
    enabled boolean
) WITH default_time_to_live = 0
    AND transactions = {'enabled': 'false'};


Due to architectural differences, YugabyteDB does not support most of the Apache Cassandra table level properties. default_time_to_live is one of the supported properties and the transactions property is added by YugabyteDB. For more details, see table properties.
default_time_to_live is one of the supported properties. YugabyteDB adds the transactions property. See table properties for more details.

Quit ycqlsh

To quit the shell, enter the following command:

ycqlsh> quit;

Unsupported cqlsh commands

Command Alternative
LIST ROLES select * from system_auth.roles
SHOW SESSION Tracing from ycqlsh is not supported.
TRACING Tracing from ycqlsh is not supported.

Learn more