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

To use Stargate you need:

  • Docker installed and running

  • cURL to run REST queries

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

Pull the Docker image

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

docker pull stargateio/stargate-3_11:v0.0.8

Start the Stargate container

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:v0.0.8

The ports align to the following services and interfaces:

Table 1. Default Port assignments for Stargate
Port Service/Interface

Port 8080

GraphQL interface for CRUD

Port 8081

REST authorization service for generating tokens

Port 8082

REST interface for CRUD

Port 9042

CQL service

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)
) 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 Stargate running on your local machine using the Python driver:

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)