Stargate!

5. Stargate!

Access K8assandra using the Stargate APIs Stargate provides APIs, data types and access methods that bring new capabilities to existing databases. Currently Stargate adds Document, REST and GraphQL APIs for CRUD access to data stored in Apache Cassandra® and there are many more APIs coming soon. Separating compute and storage also has benefits for maximizing resource consumption in cloud environments. When using Stargate with Cassandra, you can offload the request coordination overhead from your storage instances onto Stargate instances which has shown latency improvements in preliminary testing.

✅ Step 1: Access Stargate

To access Stargate in k8ssandra, generate a Stargate access token replacing and with the values you retrieved in the previous step:

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

OR

curl -L -X POST 'http://<YOURADDRESS>:8081/v1/auth' -H 'Content-Type: application/json' --data-raw '{"username": "k8ssandra-superuser", "password": "<k8ssandra-password>"}'

📃 output

{"authToken":"<access-token>"}     

✅ Step 2: Access Document Data API

The Stargate document APIs provide a way schemaless way to store and interact with data inside of Cassandra. The first step is to create a namespace. That can be done with a request to the /v2/schemas/namespaces API:

curl --location --request POST 'http://localhost:8082/v2/schemas/namespaces' \
--header "x-cassandra-token: <access-token>" \
--header 'Content-Type: application/json' \
--data '{
    "name": "myworld"
}'

OR

curl --location --request POST 'http://<YOURADDRESS>:8082/v2/schemas/namespaces' \
--header "x-cassandra-token: <access-token>" \
--header 'Content-Type: application/json' \
--data '{
    "name": "myworld"
}'

📃 output

{"name":"myworld"}   

✅ Step 3: Get all namespaces

curl -L -X GET 'localhost:8082/v2/schemas/namespaces' \
-H "X-Cassandra-Token: <access-token>" \
-H 'Content-Type: application/json'

OR

curl -L -X GET '<YOURADDRESS>:8082/v2/schemas/namespaces' \
-H "X-Cassandra-Token: <access-token>" \
-H 'Content-Type: application/json'

📃 output

{"data":[{"name":"system_schema"},{"name":"system"},{"name":"system_distributed","datacenters":[{"name":"dc1","replicas":1}]},{"name":"system_traces","datacenters":[{"name":"dc1","replicas":1}]},{"name":"system_auth","datacenters":[{"name":"dc1","replicas":1}]},{"name":"stargate_system"},{"name":"data_endpoint_auth"},{"name":"reaper_db","datacenters":[{"name":"dc1","replicas":1}]},{"name":"spring_petclinic"},{"name":"myworld"}]}

✅ Step 4: Writing documents

All data written with the Document API is stored as JSON documents stored in collections. First, let’s add a document to a specified collection. Send a POST request to /v2/namespaces/{namespace_name}/collections/{collections_name} to add data to the collection fitness. The data is passed in the JSON body.

curl --location \
--request POST 'localhost:8082/v2/namespaces/myworld/collections/fitness' \
--header "X-Cassandra-Token: <access-token>" \
--header 'Content-Type: application/json' \
--data '{
  "id": "some-stuff",
  "other": "This is nonsensical stuff."
}'

OR

curl --location \
--request POST '<YOURADDRESS>:8082/v2/namespaces/myworld/collections/fitness' \
--header "X-Cassandra-Token: <access-token>" \
--header 'Content-Type: application/json' \
--data '{
  "id": "some-stuff",
  "other": "This is nonsensical stuff."
}'

Notice that the document-id returned is a UUID if not specified. Let’s add a document to a specified collection, but specify the document-id. Send a PUT request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id} to add data to the collection Janet. The document-id can be any string. The data is passed in the JSON body.

curl -L -X PUT 'localhost:8082/v2/namespaces/myworld/collections/fitness/Janet' \
--header "X-Cassandra-Token: <access-token>" \
--header 'Content-Type: application/json' \
--data '{
  "firstname": "Janet",
  "lastname": "Doe",
  "email": "[email protected]",
  "favorite color": "grey"
}'

OR

curl -L -X PUT '<YOURADDRESS>:8082/v2/namespaces/myworld/collections/fitness/Janet' \
--header "X-Cassandra-Token: <access-token>" \
--header 'Content-Type: application/json' \
--data '{
  "firstname": "Janet",
  "lastname": "Doe",
  "email": "[email protected]",
  "favorite color": "grey"
}'

✅ Step 4: Reading documents

Let’s check that the document was inserted. Send a GET request to /v2/namespaces/{namespace_name}/collections/{collections_name} to retrieve all the documents:

curl --location \
--request GET 'localhost:8082/v2/namespaces/myworld/collections/fitness?page-size=3' \
--header "X-Cassandra-Token: <access-token>" \
--header 'Content-Type: application/json'

OR

curl --location \
--request GET '<YOURADDRESS>:8082/v2/namespaces/myworld/collections/fitness?page-size=3' \
--header "X-Cassandra-Token: <access-token>" \
--header 'Content-Type: application/json'

The page-size parameter is included to get all the documents, rather than the last inserted document. The pageState is useful for pagination of the results in queries.

Next Step

Proceed to the Step VI