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.

Prerequisites

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

If you’re looking to just get started, you can try DataStax Astra DB and skip the installation steps.

The base URL will be https://DATABASE_ID-REGION.apps.astra.datastax.com/api/rest/v2. See the FAQ to learn where to find your DATABASE_ID and REGION.

  • Install cURL, a utility for running REST, Document, or GraphQL queries on the command line.

  • [Optional] If you prefer, you can use Postman as a client interface for exploring the APIs

    • You will also find links to downloadable collections and environments in Using Postman

  • [Optional] If you going to use the GraphQL API, you will want to use the GraphQL Playground to deploy schema and execute mutations and queries.

  • [Optional] For the REST and Document APIs, you can use the Swagger UI.

  • Install Docker for Desktop

  • Pull a Stargate Docker image

  • Cassandra 4.0

  • Cassandra 3.x

  • DSE 6.8

v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra™ backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-4_0:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

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

docker pull stargateio/stargate-4_0:v1.0.57
v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra™ backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-3_11:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

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.57
v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra™ backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-dse-68:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with a DataStax Enterprise™ 6.8 backend.

docker pull stargateio/stargate-dse-68:v1.0.57

  • Run the Stargate Docker image

  • Cassandra 4.0

  • Cassandra 3.x

  • DSE 6.8

v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_4_0_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

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 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=4.0 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-4_0:v1.0.57
v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_3_11_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

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 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=3.11 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-3_11:v1.0.57
v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_dse_68_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

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

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=6.8 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-dse-68:v1.0.57

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!

Interact with CQL

You can now add and retrieve schema and data using CQL.

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)
) WITH CLUSTERING ORDER BY (lastname ASC);

Insert data

INSERT INTO users_keyspace.users (
  firstname,
  lastname,
  email,
  "favorite color"
) VALUES (
  'Mookie',
  'Betts',
  'mookie.betts@gmail.com',
  'blue'
);

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 = 'mookie.betts-new-email@gmail.com' 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 {datastax} running on your local machine using the Python driver, replacing the IP address with an appropriate address:

from cassandra.cluster import Cluster

cluster = Cluster(['127.0.0.1'])

session = cluster.connect()

session.set_keyspace('users_keyspace')

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