Using the CQL API

To use Stargate’s Cassandra Query Language (CQL) API you can use the same CQL syntax, tools and native language drivers that you would with a normal Cassandra deployment.

Popular Cassandra drivers are:

When using Cassandra drivers with Stargate you must:

  1. Use the addresses of the Stargate instances as contact points rather than the addresses of the Cassandra storage instances.

  2. Use the Round Robin policy in the driver for the Load Balancing Policy rather than the Token Aware Policy.


To use Stargate you need:

  • Docker installed and running, if using Docker

  • cURL to run REST, Document, or GraphQL queries

  • cqlsh (CQL shell) (standalone, or as part of a separate Cassandra installation)

If you are looking to just get started, DataStax Astra Database-as-a-Service can get you started with no install steps.

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with an Apache Cassandra 3.11 backend.

docker pull stargateio/stargate-3_11:v1.0.41

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate Cassandra instance and is meant for development and testing only.

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p \
  -d \
  -e CLUSTER_NAME=stargate \
  -e DEVELOPER_MODE=true \

Accessing the CQL API using cqlsh

Installing a standalone cqlsh using Docker

Install a standalone cqlsh docker image to access Stargate. First, pull the following docker image:

docker pull nuvo/docker-cqlsh

Get the IP address of your Stargate docker container (assuming the Stargate container name is "stargate"). This command assumes the stargate docker container is running:

docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' stargate

Connect to your Stargate container using cqlsh using the IP address from the last command:

docker run --rm -it nuvo/docker-cqlsh cqlsh {ip-address} --cqlversion=3.4.5

Now you are ready to interact with Cassandra!

Create a keyspace

Create a keyspace called users_keyspace.

CREATE KEYSPACE users_keyspace
  WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}
  AND durable_writes = true;

Create a table

CREATE TABLE users_keyspace.users (
    firstname text,
    lastname text,
    email text,
    "favorite color" text,
    PRIMARY KEY (firstname, lastname)

Insert data

INSERT INTO users_keyspace.users (
  "favorite color"

Retrieve data

To select all rows in the table:

SELECT * FROM users_keyspace.users;

To select a row using the primary key:

SELECT * FROM users_keyspace.users WHERE firstname = 'Mookie' AND lastname = 'Betts';

Update data

Update the email address:

UPDATE users_keyspace.users SET email = '' WHERE firstname = 'Mookie' AND lastname = 'Betts';

Verify that the row has the updated email address:

SELECT * FROM users_keyspace.users WHERE firstname = 'Mookie';

Delete data

Delete the row using the primary key:

DELETE FROM users_keyspace.users WHERE firstname = 'Mookie' AND lastname = 'Betts';

Using the CQL API with Cassandra drivers

Stargate can be used with any of the Cassandra drivers. Use the Stargate node as the contact point when connecting using Cassandra drivers, and use the Round Robin load balancing policy.

For example, to connect to Stargate running on your local machine using the Python driver:

from cassandra.cluster import Cluster

cluster = Cluster([''])

session = cluster.connect()


rows = session.execute('SELECT firstname, lastname, email FROM users')
for user_row in rows:
    print(user_row.firstname, user_row.lastname,