Difficulty: Intermediate
Estimated Time: 15 minutes

Astra offers a GraphQL API, which allows you to create and modify tables as well as insert, query and change data within the database. Let's take a look at this helpful Astra feature!

As a prerequisite, be sure to setup an Astra account and create a database as detailed in the Creating an Astra Database scenario. We'll be using that account and database as we work through this GraphQL scenario.

In this scenario as we explore the GraphQL API, we'll create some tables and perform all four CRUD operations.

ver 0.003

Code Complete

You're all set! To try out further GraphQL Queries check out a tool like GraphiQL. It will provide a means to add header information, the token, and issue GraphQL queries, mutations, and provide standard GraphQL autocompletion through introspection.


GraphiQL is available in multiple formats, such as an installable Electron App, and example embedding is available at Code Sandbox. GraphiQL is all open source at graphiql.

For more information and details on using the Astra GraphQL API read the documentation at astra.readme.io.

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

Astra GraphQL

Step 1 of 6

Setting up Environment Variables

Login to Astra, select your database and click on the Connect tab. Then, select Connect using GraphQL.

Connect using GraphQL

In this first step, let's set up some environment variables following the instructions in the Connect using GraphQL section of the Astra dashboard. We'll use these variables in later steps.

Using the first step in the Connect using GraphQL section, copy the commands to the clipboard by clicking the copy icon.

Copy Commands

Now, paste the commands in the terminal.

NOTE: 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. After you have set the password, you can execute the final command.

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.

Want to know how this command works? 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 \ --request POST \ --url https://$ASTRA_CLUSTER_ID-$ASTRA_CLUSTER_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:
  • --request POST causes cURL to issue and HTTP POST command
  • --url https://$ASTRA_CLUSTER_ID-$ASTRA_CLUSTER_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 --request POST   --url https://$ASTRA_CLUSTER_ID-$ASTRA_CLUSTER_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')

Verify that we set the environment variables correctly, by running this command.

printf "${GREEN}Cluster ID is $ASTRA_CLUSTER_ID${NC}\n"
printf "${GREEN}Cluster region is $ASTRA_CLUSTER_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!