Difficulty: Beginner
Estimated Time: 10 minutes

Built around JSON-like documents, document model databases are both natural and flexible for developers to work with.

The Stargate open source project provides an API layer that allows you to expose a document-style API on top of any Cassandra database.

Astra now offers offers a Document API via Stargate, which allows you to use your Astra database as a document database. Create collections, add documents and modify them within your database.

In this scenario we will:

  • Create a new collection and add a document
  • Read the document back from the database
  • Read a subdocument from the database
  • Update a document
  • Replace a subdocument
  • Delete a document from the database

Before we begin

As a prerequisite, be sure to setup an Astra account and create a Cassandra as a Service database at astra.datastax.com.

Let's get started with Stargate Document API on Astra!

This scenario is also available on our datastax.com/dev site, where you can find many more resources to help you succeed with Apache Cassandra™.


Code Complete

Thanks for taking a tour of Stargate's Document API on Astra! For more details and elaboration of the Document API features check out the Stargate documentation.

For more information and details on using the Document API on Astra read the documentation.

Please give this scenario a rating (click on the stars near the top).

Have questions or more feedback? Send us a message.

Getting Started with Stargate Document API for Cassandra™

Step 1 of 7

Setting up Environment Variables

Ok, here we go!

New to our scenarios? Click here for three easy tips.
Tip 1 - You can click lines that begin with a triangle (like the following) to see further explanation.
Try clicking on this line. This is where you would find further explanation.

Tip 2 - To paste content into the terminal, click on the right-hand side of the screen and select Paste. Paste to terminal
Tip 3 - If a dark box has a bent arrow at the end, you can execute the command in that box by clicking on the box. The scenario will copy the command to the terminal and begin execution. Execute command
After you execute the command, the bent arrow changes to a check mark.

Thats it! You're good to go!

This scenario follows the instructions found on the Astra dashboard. We'll set up some environment variables to help simplify our Document API access.

Step 1. Go to the Document API Connection section of your Astra database. Login to Astra, select your database and click on the Connect tab. Then, select Connect using Document API.

Connect using Doc

Step 2. Copy the export commands from the Astra web page. We'll follow the instructions in the Connect using the Document API section of the Astra dashboard. Using the first step in the Connect using the Document API section, copy the commands to the clipboard by clicking the copy icon.

Copy Commands

Step 3. Paste the export commands in the terminal. You just copied several export commands to the clipboard. Paste the contents of the clipboard in the terminal, BUT DO NOT EXECUTE THE FINAL COMMAND YET

Paste Export Commands

Step 4. Set the correct value for ASTRA_DB_PASSWORD. The last command will require you to replace "<database_password>" with the password you used when you created the database. When you paste the commands, this last command will not execute, which gives you a chance to set the password.

Set Password

Step 5. Execute the final export command. Once you have set the correct value for ASTRA_DB_PASSWORD, you can execute the command by hitting Enter in the terminal.

Press Enter

Step 6. Save the authorization token in an environment variable. The last environment variable we need is one that contains the database authorization token. We'll use the following command to retrieve the token and set the variable. This command looks complicated, so let's break it down for you.

There are actually three commands here that work together. The outer command has the following form and creates an environment variable. export ASTRA_AUTHORIZATION_TOKEN=<variable's value goes here>

There are two inner commands surrounded by $(), which causes the commands to execute and the result to be the value of the variable.

The first of the two inner commands is a cURL command to retrieve info from the Astra website. The second jq command parses the result of the cURL command and isolates the token value. The two inner commands have this form: curl \ -L -X POST \ https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth \ --header 'Content-Type: application/json' \ --data '{"username":"'"$ASTRA_DB_USERNAME"'", "password":"'"$ASTRA_DB_PASSWORD"'"}' \ | jq -r '.authToken'

Here's an explanation of the cURL command options:
  • POST causes cURL to issue and HTTP POST command
  • https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth specifies the target of the POST command
  • --header 'Content-Type: application/json' tells cURL to use JSON syntax
  • --data '{"username":"'"$ASTRA_DB_USERNAME"'", "password":"'"$ASTRA_DB_PASSWORD"'"}' is the JSON containing the database credentials that cURL uses to access the token
export ASTRA_AUTHORIZATION_TOKEN=$(curl -L -X POST https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth --header 'Content-Type: application/json' --data '{"username":"'"$ASTRA_DB_USERNAME"'", "password":"'"$ASTRA_DB_PASSWORD"'"}' | jq -r '.authToken')
Step 7. Verify that we set the environment variables correctly. Here, we just want to review the values of the environment variables to make sure they are correct. You can run the following command, which prints the values in green. Astra filled in most of the values for you, but pay special attention to the password value and the token. The token should look like a random string of characters.
printf "${GREEN}DB ID is $ASTRA_DB_ID${NC}\n"
printf "${GREEN}DB region is $ASTRA_DB_REGION${NC}\n"
printf "${GREEN}Keyspace is $ASTRA_DB_KEYSPACE${NC}\n"
printf "${GREEN}Username is $ASTRA_DB_USERNAME${NC}\n"
printf "${GREEN}Password is $ASTRA_DB_PASSWORD${NC}\n"
printf "${GREEN}Authorization token is $ASTRA_AUTHORIZATION_TOKEN${NC}\n"

The environment variables are all set!