Using the Stargate REST API

Stargate is a data gateway deployed between client applications and a database. The REST API plugin that exposes CRUD access to data stored in Cassandra tables.

Prerequisites

To use Stargate you need:

  • Docker installed and running, if using Docker

  • cURL to run REST queries

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.13

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.13

Swagger UI for the REST API

Once you have started the docker container, you can access the REST API in a browser at localhost:8082/swagger-ui. Adding parameter information, you can generate cURL commands to execute and display results that will return.

Using the Auth API to generate an auth token

In order to use the Stargate REST API, an authorization token must be generated to access the interface.

The step below uses cURL to access the REST interface to generate the needed token.

Generate an auth token

First generate an auth token that is required in each subsequent request in the X-Cassandra-Token header. Note the port for the auth service is 8081.

curl -L -X POST 'http://localhost:8081/v1/auth' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "username": "cassandra",
    "password": "cassandra"
}'

You should receive a token in the response.

{"authToken":"{auth-token}"}

Use the auth token

Store the auth token in an environment variable to make it easy to use with cURL.

export AUTH_TOKEN={auth-token}

Using Postman

If you prefer, you can use Postman as a client interface for exploring REST APIs (download here). We’ve provided a Stargate REST API Postman Collection that you can import in Postman to play with the examples shown in this walkthrough.

Now you’re ready to use the REST API for CRUD operations.

Creating or dropping keyspace and table schema

In order to use the REST API, you must create schema that defines at least one keyspace and one table that will store the data. A keyspace is a container for which a replication factor defines the number of data replicas the database will store. Tables consist of columns that each have a name and a defined data type. Multiple tables are contained in a keyspace, but a table cannot be contained in multiple keyspaces. If you are connecting to a Cassandra database with existing schema, you can skip this step.

For keyspaces, an optional setting, replicas, defines the number of data replicas the database will store for the keyspace. If no replica is defined, then for a keyspace in a single datacenter cluster, the default is 1, and for a multiple-datacenter cluster, the default is 3 for each datacenter.

Creating a keyspace

Simple keyspace

Send a POST request to /v2/schemas/keyspaces. In this example we use user_keyspace for the name, and no replicas setting, to default to 1.

  • cURL command (/v2)

  • Result

curl -s --location --request POST 'localhost:8082/v2/schemas/keyspaces' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "users_keyspace"
}'
{"name":"users_keyspace"}

The authorization token and the content type are passed with --header. The token must be identified as X-Cassandra-Token so that cluster recognizes the token and its value. The specified name for the keyspace is passed as JSON data using --data. For shorthand, cURL can use -L for --location, -X for --request, -H for --header, and -d for --data.

Set replicas in simple keyspace

Send a POST request to /v2/schemas/keyspaces. In this example we use users_keyspace for the name, and 1 for the number of data replicas.

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "name": "users_keyspace",
    "replicas": 1
}'
{"name":"users_keyspace"}

Keyspace for multiple datacenters

For a multiple-datacenter cluster, a keyspace is defined datacenters. Send a POST request to /v2/schemas/keyspaces. In this example we use users_keyspace-dcs for the name, the datacenters are dc1 and dc2, where dc1 defaults to 3 replicas and dc2 is set to 5 replicas.

  • cURL command (/v2)

  • Result

curl -s -L -X POST 'localhost:8082/v2/schemas/keyspaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "name": "users_keyspace_dcs",
    "datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'
{"name":"users_keyspace_dcs"}
curl -s -L -X POST 'localhost:8082/v2/schemas/keyspaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "name": "users_keyspace_dcs",
    "datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'

Checking keyspace existence

To check if a keyspaces exist, execute a REST API query with cURL to find all the keyspaces:

  • cURL command (/v2)

  • Result

curl -s -L -X GET localhost:8082/v2/schemas/keyspaces \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{
  "data":[
    {
      "name":"system_distributed"
    },
    {
      "name":"system"
    },
    {
      "name":"data_endpoint_auth"
    },
    {
      "name":"users_keyspace"
    },
    {
      "name":"system_schema"
    },
    {
      "name":"myworld"
    },
    {
      "name":"stargate_system"
    },
    {
      "name":"library"
    },
    {
      "name":"system_auth"
    },
    {
      "name":"system_traces"
    }
  ]
}

To get a particular keyspace, specify the keyspace in the URL:

  • cURL command (/v2)

  • Result

curl -s -L -X GET localhost:8082/v2/schemas/keyspaces/users_keyspace \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{"data":{"name":"users_keyspace"}}

Creating a table

Send a POST request to /v2/schemas/keyspaces/{keyspace_name}/tables to create a table. Set the table name and column definitions in the JSON body.

  • cURL command (/v2)

  • Result

curl -s --location \
--request POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
	"name": "users",
	"columnDefinitions":
	  [
        {
	      "name": "firstname",
	      "typeDefinition": "text"
	    },
        {
	      "name": "lastname",
	      "typeDefinition": "text"
	    },
        {
	      "name": "favorite color",
	      "typeDefinition": "text"
	    }
	  ],
	"primaryKey":
	  {
	    "partitionKey": ["firstname"],
	    "clusteringKey": ["lastname"]
	  },
	"tableOptions":
	  {
	    "defaultTimeToLive": 0,
	    "clusteringExpression":
	      [{ "column": "lastname", "order": "ASC" }]
	  }
}'
{"name":"users"}

Information about partition keys and clustering keys are found in the CQL reference.

Data types

Many common data types are supported by the REST API, such as collections (set, list, map), tuples, and user-defined types (UDTs). In addition, collections can be specified as frozen collections. Columns can be set to these data types in the original table creation, or be added later. Look in the next section for some examples of adding columns.

Adding columns to table schema

If you need to add an attribute to something you are storing in a table, you can add a column by sending a POST request to add the column.

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "name": "email",
   "typeDefinition": "text"
}'
{ "name": "email" }

To change the name or data type of an existing column, use a similar command, but sent a PUT request instead:

  • cURL command (/v2)

  • Result

curl -s -L \
-X PUT http://localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns/firstname \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{   "name": "first",   "typeDefinition": "varchar"}'
{
  "name": "first"
}

To add a set to a table, specify the data type set along with the data type of the set contents, such as text:

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "name": "favorite_books",
   "typeDefinition": "set<text>"
}'
{"name":"favorite_books"}

To add a set as a frozen set, specify "typeDefinition": "frozen<set<text>>" with the keyword frozen. In the following examples, both lists and maps can also be specified as frozen.

To add a list to a table, specify the data type list along with the data type of the set contents, such as text. The difference between a set and a list is that a set is unordered, whereas a list is ordered:

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "name": "top_three_tv_shows",
   "typeDefinition": "list<text>"
}'
{"name":"top_three_tv_shows"}

To add a map to a table, specify the data type map along with the data type of the map key and the may value:

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "name": "evaluations",
   "typeDefinition": "map<int,text>"
}'
{"name":"evaluations"}

To add a tuple to a table, specify the data type tuple along with the data type of the each item in the tuple. A tuple can consist of two or more values that can be retrieved together.

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "name": "current_country",
   "typeDefinition": "tuple<text, date, date>"
}'
{"name":"current_country"}

To add a user-defined type (UDT) to a table, specify the data type udt along with the data type of the each item in the UDT. A UDT can consist of two or more values that can be retrieved together.

UDTs must currently be created in CQL before specifying for a column in the REST API. For instance, for a UDT created with the following CQL statement:

CREATE TYPE IF NOT EXISTS users_keyspace.address (
  street text,
  zip int
);

we can add a UDT column to our table:

  • cURL command (/v2)

  • Result

curl -s -L -X POST localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "name": "address",
   "typeDefinition": "address"
}'
{ "name": "address" }

Checking table and column existence

To check if a table exists, execute a REST API query with cURL to find all the tables:

  • cURL command (/v2)

  • Result

curl -s -L -X GET localhost:8082/v2/schemas/keyspaces/users_keyspace/tables \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{
  "data": [
    {
      "name": "users",
      "keyspace": "users_keyspace",
      "columnDefinitions": [
        {
          "name": "firstname",
          "typeDefinition": "varchar",
          "static": false
        },
        {
          "name": "lastname",
          "typeDefinition": "varchar",
          "static": false
        },
        {
          "name": "email",
          "typeDefinition": "varchar",
          "static": false
        },
        {
          "name": "favorite color",
          "typeDefinition": "varchar",
          "static": false
        }
      ],
      "primaryKey": {
        "partitionKey": [
          "firstname"
        ],
        "clusteringKey": [
          "lastname"
        ]
      },
      "tableOptions": {
        "defaultTimeToLive": 0,
        "clusteringExpression": [
          {
            "order": "Asc",
            "column": "lastname"
          }
        ]
      }
    }
  ]
}

To get a particular table, specify the table in the URL:

  • cURL command (/v2)

  • Result

curl -s -L \
-X GET localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{
  "data": {
    "name": "users",
    "keyspace": "users_keyspace",
    "columnDefinitions": [
      {
        "name": "firstname",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "lastname",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "current_country",
        "typeDefinition": "frozen<tuple<varchar, date, date>>",
        "static": false
      },
      {
        "name": "email",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "evaluations",
        "typeDefinition": "map<int, varchar>",
        "static": false
      },
      {
        "name": "favorite color",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "favorite_books",
        "typeDefinition": "set<varchar>",
        "static": false
      },
      {
        "name": "top_three_tv_shows",
        "typeDefinition": "list<varchar>",
        "static": false
      }
    ],
    "primaryKey": {
      "partitionKey": [
        "firstname"
      ],
      "clusteringKey": [
        "lastname"
      ]
    },
    "tableOptions": {
      "defaultTimeToLive": 0,
      "clusteringExpression": [
        {
          "order": "ASC",
          "column": "lastname"
        }
      ]
    }
  }
}

To check if a column exists, execute a REST API query with cURL to find all the columns:

  • cURL command (/v2)

  • Result

curl -s -L \
-X GET localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json"
{
  "data": [
    {
      "name": "firstname",
      "typeDefinition": "varchar",
      "static": false
    },
    {
      "name": "lastname",
      "typeDefinition": "varchar",
      "static": false
    },
    {
      "name": "current_country",
      "typeDefinition": "frozen<tuple<varchar, date, date>>",
      "static": false
    },
    {
      "name": "email",
      "typeDefinition": "varchar",
      "static": false
    },
    {
      "name": "evaluations",
      "typeDefinition": "map<int, varchar>",
      "static": false
    },
    {
      "name": "favorite color",
      "typeDefinition": "varchar",
      "static": false
    },
    {
      "name": "favorite_books",
      "typeDefinition": "set<varchar>",
      "static": false
    },
    {
      "name": "top_three_tv_shows",
      "typeDefinition": "list<varchar>",
      "static": false
    }
  ]
}

To get a particular column, specify the column in the URL:

  • cURL command (/v2)

  • Result

curl -s -L \
-X GET localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns/email \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{
  "data":{
    "name":"email",
    "typeDefinition":"varchar",
    "static":false
  }
}

Drop keyspaces, tables or columns

Dropping a keyspace

Send a DELETE request to /v2/schemas/keyspaces/{keyspace_name} to delete a keyspace. All data and all table schema will be deleted along with the keyspace scheam.

curl -s --location \
--request DELETE localhost:8082/v2/schemas/keyspaces/users_keyspace \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"

Dropping a table

Send a DELETE request to /v2/schemas/keyspaces/{keyspace_name}/tables/{table_name} to delete a table. All data will be deleted along with the table schema.

curl -s --location \
--request DELETE localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"

Removing columns from table schema

If you find an attribute is no longer required in a table, you can remove a column by sending a DELETE request to delete the column. All column data will be deleted along with the column schema.

curl -s --location \
--request DELETE localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns/email \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"

Modifying schema

Interacting with data stored in tables

All data written with the REST API is stored in columns in tables that were specified with the schema.

Write data

First, let’s add some data to the users table that you created. Send a POST request to /v2/keyspaces/{keyspace_name}/{table_name} to add data to the table. The column name/value pairs are passed in the JSON body.

  • cURL command (/v2)

  • Result

curl -s --location --request POST 'localhost:8082/v2/keyspaces/users_keyspace/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "firstname": "Mookie",
    "lastname": "Betts",
    "email": "mookie.betts@gmail.com",
    "favorite color": "blue"
}'
curl -s --location --request POST 'localhost:8082/v2/keyspaces/users_keyspace/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "firstname": "Janesha",
    "lastname": "Doesha",
    "email": "janesha.doesha@gmail.com",
    "favorite color": "grey"
}'
{"firstname":"Mookie","lastname":"Betts"}
{"firstname":"Janesha","lastname":"Doesha"}

Notice that, unlike schema creation, data queries do not require tables in the URI, only the {tableName}.

Collections, tuples, and UDTs

Some data types require special handling to write the data. Examples of set, list, map, tuple, and udt are shown, using the column schema created earlier.

SET:

  • cURL command (/v2)

  • Result

curl -s -X POST http://localhost:8082/v2/keyspaces/users_keyspace/users \
-H  "accept: application/json" \
-H  "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Content-Type: application/json" \
-d '{"firstname": "Janesha",
  "lastname": "Doesha",
  "favorite color": "grey",
  "favorite_books": [ "Emma", "The Color Purple" ]
}'
{"firstname":"Janesha","lastname":"Doesha"}

LIST:

  • cURL command (/v2)

  • Result

curl -s -X POST http://localhost:8082/v2/keyspaces/users_keyspace/users \
-H  "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Content-Type: application/json" \
-H  "Accept: application/json" \
-d '{"firstname": "Janesha",
  "lastname": "Doesha",
  "favorite color": "grey",
  "top_three_tv_shows": [ "The Magicians", "The Librarians", "Agents of SHIELD" ]
}'
{"firstname":"Janesha","lastname":"Doesha"}

MAP:

  • cURL command (/v2)

  • Result

curl -s -L -X POST http://localhost:8082/v2/keyspaces/users_keyspace/users \
-H  "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Content-Type: application/json" \
-H  "Accept: application/json" \
-d '{"firstname": "Janesha",
  "lastname": "Doesha",
  "favorite color": "grey",
  "top_three_tv_shows": [ "The Magicians", "The Librarians", "Agents of SHIELD" ],
  "evaluations": [ {"key":"2020", "value":"good"}, {"key":"2019", "value":"okay"} ]
}'
{"firstname":"Janesha","lastname":"Doesha"}

TUPLE:

  • cURL command (/v2)

  • Result

curl -s -X POST http://localhost:8082/v2/keyspaces/users_keyspace/users \
-H  "accept: application/json" \
-H  "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Content-Type: application/json" \
-d '{"firstname": "Janesha",
  "lastname": "Doesha",
  "favorite color": "grey",
  "current_country": [ "France", "2016-01-01", "2020-02-02" ]
}'
{"firstname":"Janesha","lastname":"Doesha"}

UDT:

  • cURL command (/v2)

  • Result

curl -s -X POST http://localhost:8082/v2/keyspaces/users_keyspace/users \
-H  "accept: application/json" \
-H  "X-Cassandra-Token: $AUTH_TOKEN" \
-H  "Content-Type: application/json" \
-d '{"firstname": "Janesha",
  "lastname": "Doesha",
  "favorite color": "grey",
  "address": { "street": "1 Main St", "zip": 12345 }
}'
{"firstname":"Janesha","lastname":"Doesha"}

Read data

Let’s check that the data was inserted. Send a GET request to /v2/keyspaces/{keyspace_name}/{table_name}?where={searchPath} to retrieve the two users that were entered:

  • cURL command (/v2)

  • Result

curl -s -L -X GET 'http://localhost:8082/v2/keyspaces/users_keyspace/users?where=\{"firstname":\{"$in":\["Janesha","Mookie"\]\}\}' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"
{
  "count": 2,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        {
          "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }
      ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France",
        {
          "year": 2016,
          "month": "JANUARY",
          "dayOfMonth": 1,
          "dayOfWeek": "FRIDAY",
          "era": "CE",
          "dayOfYear": 1,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 1
        },
        {
          "year": 2020,
          "month": "FEBRUARY",
          "dayOfMonth": 2,
          "dayOfWeek": "SUNDAY",
          "era": "CE",
          "dayOfYear": 33,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 2
        }
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    },
    {
      "firstname": "Mookie",
      "evaluations": [],
      "top_three_tv_shows": [],
      "favorite color": "blue",
      "current_country": null,
      "email": "mookie.betts.new-email@email.com",
      "lastname": "Betts",
      "favorite_books": []
    }
  ]
}

This query uses $in to find the two users. The WHERE clause can be used with other valid search terms: $eq, $lt, $lte, $gt, $gte, $ne, and $exists, if applicable. The primary key of the table can be used in the WHERE clause, but non-primary key columns cannot be used unless indexed.

A query for table rows must include a WHERE clause or a primary key to retrieve rows.

Send a GET request to /v2/keyspaces/{keyspace_name}/{table_name} to retrieve the row for Mookie using $eq:

  • cURL command (/v2)

  • Result

curl -s -L -X GET 'http://localhost:8082/v2/keyspaces/users_keyspace/users?where=\{"firstname":\{"$eq":"Mookie"\}\}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"
{
  "count": 1,
  "data": [
    {
      "firstname": "Mookie",
      "evaluations": [],
      "top_three_tv_shows": [],
      "favorite color": "blue",
      "current_country": null,
      "email": "mookie.betts.new-email@email.com",
      "lastname": "Betts",
      "favorite_books": []
    }
  ]
}

If the CQL indexes exist, a multiple WHERE can be used:

Send a GET request to /v2/keyspaces/{keyspace_name}/{table_name} to retrieve the row for Janesha using $eq, and Emma using $contains:

  • cURL command (/v2)

  • Result

curl -s -L -X GET 'http://localhost:8082/v2/keyspaces/users_keyspace/users?where=\{"firstname":\{"$eq":"Janesha"\},"favorite_books":\{"$contains":"Emma"\}\}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"
{
  "count": 1,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        {
          "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }
      ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France",
        {
          "year": 2016,
          "month": "JANUARY",
          "dayOfMonth": 1,
          "dayOfWeek": "FRIDAY",
          "era": "CE",
          "dayOfYear": 1,
          "leapYear": true,
          "monthValue": 1,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          }
        },
        {
          "year": 2020,
          "month": "FEBRUARY",
          "dayOfMonth": 2,
          "dayOfWeek": "SUNDAY",
          "era": "CE",
          "dayOfYear": 33,
          "leapYear": true,
          "monthValue": 2,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          }
        }
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    }
  ]
}

Finally, a primary key can be supplied to retrieve a row:

  • cURL command (/v2)

  • Result

curl -s -L -X GET localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{
  "count": 1,
  "data": [
    {
      "firstname": "Mookie",
      "evaluations": [],
      "top_three_tv_shows": [],
      "favorite color": "blue",
      "current_country": null,
      "email": "mookie.betts.new-email@email.com",
      "lastname": "Betts",
      "favorite_books": []
    }
  ]
}

Collections, tuples, and UDTs

Some data types require special handling to read the data. Examples of set, list, map, tuple, and udt are shown, using the column schema created earlier. Because these columns are not part of the partition or clustering key, an index is required to read the data. Currently, for Cassandra, those indexes must be created with CQL. Here are the indexes created for use in the following examples:

CREATE INDEX books_idx ON users_keyspace.users (values(favorite_books));
CREATE INDEX tv_idx ON users_keyspace.users (VALUES (top_three_tv_shows));
CREATE INDEX eval_idx ON users_keyspace.users (KEYS (evaluations));
CREATE INDEX tv_idx ON users_keyspace.users (VALUES (top_three_tv_shows));

If you are using DataStax Enterprise, you may optionally use Storage-Attached Indexing (SAI):

CREATE CUSTOM INDEX books_idx
  ON users_keyspace.users (VALUES(favorite_books))
  USING 'StorageAttachedIndex'
  WITH OPTIONS = ('case_sensitive': 'false');
CREATE CUSTOM INDEX tv_idx
  ON users_keyspace.users (VALUES(top_three_tv_shows))
  USING 'StorageAttachedIndex'
  WITH OPTIONS = ('case_sensitive': 'false');
CREATE CUSTOM INDEX eval_idx
  ON users_keyspace.users (KEYS(evaluations))
  USING 'StorageAttachedIndex'
  WITH OPTIONS = ('case_sensitive': 'false');

SAI does not support tuples. Searches using SAI do not support the operator $in.

SET:

  • cURL command (/v2)

  • Result

curl -s -L -G http://localhost:8082/v2/keyspaces/users_keyspace/users \
   -H "X-Cassandra-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   --data-urlencode 'where={
     "firstname": {"$eq": "Janesha"},
     "lastname": {"$eq": "Doesha"},
     "favorite_books": {"$contains": "Emma"}
   }'
{
  "count": 1,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        {
          "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }
      ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France",
        {
          "year": 2016,
          "month": "JANUARY",
          "dayOfMonth": 1,
          "dayOfWeek": "FRIDAY",
          "era": "CE",
          "dayOfYear": 1,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 1
        },
        {
          "year": 2020,
          "month": "FEBRUARY",
          "dayOfMonth": 2,
          "dayOfWeek": "SUNDAY",
          "era": "CE",
          "dayOfYear": 33,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 2
        }
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    }
  ]
}

LIST:

  • cURL command (/v2)

  • Result

curl -s -L -G http://localhost:8082/v2/keyspaces/users_keyspace/users \
   -H  "X-Cassandra-Token: $AUTH_TOKEN" \
   -H  "Content-Type: application/json" \
   -H "Accept: application/json" \
   --data-urlencode 'where={
     "firstname": {"$eq": "Janesha"},
     "lastname": {"$eq": "Doesha"},
     "top_three_tv_shows": {"$contains": "The Magicians"}
   }'
{
  "count": 1,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        {
          "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }
      ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France",
        {
          "year": 2016,
          "month": "JANUARY",
          "dayOfMonth": 1,
          "dayOfWeek": "FRIDAY",
          "era": "CE",
          "dayOfYear": 1,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 1
        },
        {
          "year": 2020,
          "month": "FEBRUARY",
          "dayOfMonth": 2,
          "dayOfWeek": "SUNDAY",
          "era": "CE",
          "dayOfYear": 33,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 2
        }
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    }
  ]
}

MAP:

  • cURL command (/v2)

  • Result

curl -s -L -G http://localhost:8082/v2/keyspaces/users_keyspace/users \
   -H  "X-Cassandra-Token: $AUTH_TOKEN" \
   -H  "Content-Type: application/json" \
    -H "Accept: application/json" \
   --data-urlencode 'where={
     "firstname": {"$eq": "Janesha"},
     "lastname": {"$eq": "Doesha"},
     "evaluations": {"$containsKey": "2020"}
   }'
{
  "count": 1,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        {
          "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }
      ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France",
        {
          "year": 2016,
          "month": "JANUARY",
          "dayOfMonth": 1,
          "dayOfWeek": "FRIDAY",
          "era": "CE",
          "dayOfYear": 1,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 1
        },
        {
          "year": 2020,
          "month": "FEBRUARY",
          "dayOfMonth": 2,
          "dayOfWeek": "SUNDAY",
          "era": "CE",
          "dayOfYear": 33,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 2
        }
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    }
  ]
}

TUPLE:

  • cURL command (/v2)

  • Result

# current_country currently uses a v1 style query
curl -s -G -L "http://localhost:8082/v2/keyspaces/users_keyspace/users" \
   -H  "X-Cassandra-Token: $AUTH_TOKEN" \
   -H  "Content-Type: application/json" \
   --data-urlencode 'where={
     "firstname": {"$eq": "Janesha"},
     "lastname": {"$eq": "Doesha"},
     "current_country": {"$eq": "( 'France', '2016-01-01', '2020-02-02' )"}
   }'
{
  "count": 1,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        {
          "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }
      ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France",
        {
          "year": 2016,
          "month": "JANUARY",
          "dayOfMonth": 1,
          "dayOfWeek": "FRIDAY",
          "era": "CE",
          "dayOfYear": 1,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 1
        },
        {
          "year": 2020,
          "month": "FEBRUARY",
          "dayOfMonth": 2,
          "dayOfWeek": "SUNDAY",
          "era": "CE",
          "dayOfYear": 33,
          "leapYear": true,
          "chronology": {
            "calendarType": "iso8601",
            "id": "ISO"
          },
          "monthValue": 2
        }
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    }
  ]
}

UDT:

  • cURL command (/v2)

  • Result

curl -s -L -G http://localhost:8082/v2/keyspaces/users_keyspace/users \
   -H "X-Cassandra-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   --data-urlencode 'where={
     "firstname": {"$eq": "Janesha"},
     "lastname": {"$eq": "Doesha"},
     "address": {\"$eq\": { \"street\": \"1, Main St\", \"zip\": 12345 }}
   }'
Example coming

Update data

Data changes, so often it is necessary to update an entire row. To update a row, send a PUT request to /v2/keyspaces/{keyspace_name}/{table_name}/{path}. The {path} is comprised of the primary key values. In this example, the partition key is firstname "Mookie" and the clustering key is lastname "Betts"; thus, we use /Mookie/Betts as the {path} in our request.

  • cURL command (/v2)

  • Result

curl -s -L -X PUT 'localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "email": "mookie.betts.new-email@email.com"
}'
{"data":{"email":"mookie.betts.new-email@email.com"}}

Updates are upserts. If the row doesn’t exist, it will be created. If it does exist, it will be updated with the new row data.

It is also possible to update only part of a row. To partially update, send a PATCH request to /v2/keyspaces/{keyspace_name}/{table_name}/{path}. In this example, we realize we should not have changed the email address, and we want to only change that one column:

  • cURL command (/v2)

  • Result

curl -s -L -X PATCH 'localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "email": "mookie.betts.email@email.com"
}'
{"data":{"email":"mookie.betts.email@email.com"}}

Delete data

To delete a row, send a DELETE request to /v2/keyspaces/{keyspace_name}/{table_name}/{primaryKey}. For this example, the primary key consists of a partition key firstname and clustering column lastname, so we delete all data with Mookie/Betts:

curl -s -L -X DELETE localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json"