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, Document, or GraphQL 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.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 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.41
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.
Use 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}
Use Postman
If you prefer, you can use Postman as a client interface for exploring the REST API (download here). See Tooling Resources for links to downloadable collections and environments. Instructions for configuring the environments for Stargate OSS and Astra are available. You can immediately import the documentation code examples and explore!
Now you’re ready to use the REST API for CRUD operations.
Create or delete 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.
Create 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 -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
.
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 -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} ]
}'
Check keyspace existence
To check if a keyspaces exist, execute a
REST API query with cURL
to find all the keyspaces:
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:
Delete 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 schema.
curl -s --location \
--request DELETE localhost:8082/v2/schemas/keyspaces/users_keyspace \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"
Create a user-defined type (UDT)
A user-defined type, or UDT, consists of two or more values that can be retrieved together. UDTs are useful for associating items that are naturally grouped, like an address (street, city, zip code), or a review (item reviewed, rating, date reviewed).
UDTs are stored in a defined keyspace and can be used in other UDT definitions or table columns.
Send a POST
request to /v2/schemas/keyspaces/{keyspace_name}/types
.
In this example we use address_type
for the name
. The defined fields
describe
the included items and their data type.
curl -s -L -X POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/types \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "address_type",
"fields":[
{
"name": "street",
"typeDefinition": "text"
},
{
"name": "city",
"typeDefinition": "text"
},
{
"name": "state",
"typeDefinition": "text"
},
{
"name": "zip",
"typeDefinition": "text"
}
]
}'
{
"name": "address_type"
}
Check UDT existence
To check if your UDT exists as expected after creation, use a GET
request
to /v2/schemas/keyspaces/{keyspace_name}/types
.
curl --location --request GET http://localhost:8080/v2/schemas/keyspaces/users_keyspace/types \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'accept: application/json' \
-H 'content-type: application/json'
{
"data":[
{
"name":"address_type",
"keyspace":"users_keyspace",
"fields":[
{
"name":"street",
"typeDefinition":"varchar"
},
{
"name":"city",
"typeDefinition":"varchar"
},
{
"name":"state",
"typeDefinition":"varchar"
},
{
"name":"zip",
"typeDefinition":"varchar"
}
]
}
]
}
Delete a UDT
To delete a UDT, use a DELETE
request to /v2/schemas/keyspaces/{keyspace_name}/types/{type_name}
.
All UDT schema will be deleted along with the UDT data.
Create 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 -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.
Add 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 -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 -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 -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 -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 -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 -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 -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_type"
}'
{ "name": "address" }
Check table and column existence
To check if a table exists, execute a
REST API query with cURL
to find all the tables:
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 -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 -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 -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
}
}
Delete columns from table schema
If you find an attribute is no longer required in a table, you
can delete a column by sending a DELETE
request. 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"
Delete 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"
Create an index
Tables can contain partition keys and clustering keys, both of which define the primary key. A table can also include non-primary keys.
If you wish to create a table query that uses anything other than the partition key to define which row or rows are to be retrieved, a column index must be created on each column to read the data.
To use the REST API to create indexes, you’ll need the application token you generated to create other schema in your keyspace.
Send a POST
request to
/v2/schemas/keyspaces/{keyspace_name}/tables/{table_name}/indexes
to create an index.
Set the index definitions in the JSON body in the --data
. In this example,
an index name is defined as fav_books_idx
for the column favorite_books
in
the keyspace users_keyspace
and table users
.
An option to only create the index if it already exists is set with ifNotExists: true
;
the default is false
.
Two additional options are available:
-
type
can be defined to use SAI indexes if desired; the default is secondary indexes. -
kind
defines the kind of index for map collections; the choices available areVALUES/KEYS/ENTRIES/FULL
.
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "favorite_books",
"name": "fav_books_idx",
"ifNotExists": true
}'
{
"success": true
}
Here is an additional example, which creates indexes that are used in the REST API examples:
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "favorite_books",
"name": "fav_books_idex",
"ifNotExists": true
}'
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "top_three_tv_shows",
"name": "tv_idx",
"ifNotExists": true
}'
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "evaluations",
"name": "evalv_idx",
"ifNotExists": true
}'
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "evaluations",
"name": "evalk_idx",
"kind": "KEYS",
"ifNotExists": true
}'
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "evaluations",
"name": "evale_idx",
"kind": "ENTRIES",
"ifNotExists": true
}'
curl -s --location \
--request POST http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"column": "current_country",
"name": "country_idx",
"ifNotExists": true
}'
{
"success": true
}
{
"success": true
}
{
"success": true
}
{
"success": true
}
{
"success": true
}
{
"success": true
}
Note the use of the kind
in the definitions used for the map collection evaluations
.
Delete an index
You may wish to list all the indexes to verify the index name you wish to delete:
curl -s --location \
--request GET http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
[
{
"keyspace_name": "users_keyspace",
"options": [
{
"key": "target",
"value": "current_country"
}
],
"table_name": "users",
"index_name": "country_idx",
"kind": "COMPOSITES"
},
{
"keyspace_name": "users_keyspace",
"options": [
{
"key": "target",
"value": "entries(evaluations)"
}
],
"table_name": "users",
"index_name": "evale_idx",
"kind": "COMPOSITES"
},
{
"keyspace_name": "users_keyspace",
"options": [
{
"key": "target",
"value": "keys(evaluations)"
}
],
"table_name": "users",
"index_name": "evalk_idx",
"kind": "COMPOSITES"
},
{
"keyspace_name": "users_keyspace",
"options": [
{
"key": "target",
"value": "values(evaluations)"
}
],
"table_name": "users",
"index_name": "evalv_idx",
"kind": "COMPOSITES"
},
{
"keyspace_name": "users_keyspace",
"options": [
{
"key": "target",
"value": "values(favorite_books)"
}
],
"table_name": "users",
"index_name": "fav_books_idx",
"kind": "COMPOSITES"
},
{
"keyspace_name": "users_keyspace",
"options": [
{
"key": "target",
"value": "values(top_three_tv_shows)"
}
],
"table_name": "users",
"index_name": "tv_idx",
"kind": "COMPOSITES"
}
]
Send a DELETE
request to
/api/rest/v2/schemas/keyspaces/{keyspace_name}/tables/{table_name}/indexes/{index_name}
to delete an index. All index data will be deleted along with the index schema.
curl -s --location \
--request DELETE http://localhost:8080/v2/schemas/keyspaces/users_keyspace/tables/users/indexes/fav_books_idx \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
If the call is successful, a 204
message is returned.
Interact 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 -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 |
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 -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 -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 -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 -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 -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 -s -L -X GET '{base_url}{base_rest_schema}/{rkeyspace}/{rtable}?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.
Send a GET
request to /v2/keyspaces/{keyspace_name}/{table_name}
to retrieve the row for Mookie
using $eq
:
curl -s -L -X GET '{base_url}{base_rest_schema}/{rkeyspace}/{rtable}?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 -s -L -X GET '{base_url}{base_rest_schema}/{rkeyspace}/{rtable}?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"
]
}
]
}
A primary key can be supplied to retrieve a row:
curl -s -L -X GET {base_url}{base_rest_schema}/{rkeyspace}/{rtable}/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": []
}
]
}
Adding /rows
instead of a WHERE
clause or primary key returns all table rows.
Returning all rows in a large table can negatively impact your database.
The page-size parameter limits the number of results returned, and is recommended for large tables.
The pageState is useful for pagination of the results in queries.
|
curl -s -L -X GET {base_url}{base_rest_schema}/{rkeyspace}/{rtable}/rows \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
{
"count": 2,
"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": []
},
{
"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"
]
}
]
}
In this example both Mookie
and Betts
are supplied in the path. Mookie
is
the partition key firstname
and Betts
is the clustering key lastname
. Together
these keys form the primary key of a row. To retrieve any rows using the partition
keys and clustering keys, the primary key can be part of the request, in order
and separated by a forward slash, such as pk1/pk2/ck1/ck2/….
Each key must
be included in order, but subsequent clustering keys do not have to be included.
Note that the inclusion of clustering keys may return a range of rows.
To return only desired fields in a response object, use the fields
query parameter:
curl -s -L -X GET '{base_url}{base_rest_schema}/{rkeyspace}/{rtable}/Janesha/Doesha?fields=firstname,lastname,top_three_tv_shows \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"
{
"count": 1,
"data": [
{
"firstname": "Janesha",
"lastname": "Doesha",
"top_three_tv_shows": [
"The Magicians",
"The Librarians",
"Agents of SHIELD"
]
}
]
}
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 evalk_idx ON users_keyspace.users (KEYS (evaluations));
CREATE INDEX evalv_idx ON users_keyspace.users (VALUES (evaluations));
CREATE INDEX evale_idx ON users_keyspace.users (ENTRIES (evaluations));
CREATE INDEX country_idx ON users_keyspace.users (VALUES (current_country));
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 -s -L -G {base_url}{base_rest_schema}/{rkeyspace}/{rtable} \
-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 -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 -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 -s -G -L {base_url}{base_rest_schema}/{rkeyspace}/{rtable} \
-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 -s -L -G {base_url}{base_rest_schema}/{rkeyspace}/{rtable} \
-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 -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:
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"