Load and retrieve data

This quick start will help you so you can load and retrieve your data in your DataStax Astra DB database with ease. For this example, we’ll use the Document API.

Here are the basic steps:

Create your Astra DB account.
Create your database.
Get your application token.
Load data to your database.
Get data from your database.

If you want to create multiple databases, create a new organization first.

Create your Astra DB account

Register for a new Astra DB account. You can use your business email and a password, or create an account with GitHub or Google.

Wasn’t that easy? Now you can create your database.

Create your database

You’ve already created your Astra DB account. Let’s create a database where you’ll be able to load and get your data for your application.

Here are a few key things you should know as you create your database:

Your database stores all of your information. For this example, name your database example.
A keyspace stores your group of tables, like a schema in a relational database. This helps keep related tables of information in a single place within your database.
For this example, name your keyspace fitness.
Select a region that is geographically close to your users to optimize performance.

Procedure

In Astra Portal, select Create Database.
Select a plan if you do not have an existing plan.

See plan options for the benefits of each plan. You can upgrade from a free or pay as you go plan to a committed plan as your needs might change.

If you need more options, contact DataStax Support.
If you are creating a database with a pay as you go or an annual commitment plan, enter your payment method to continue. If you are creating a free plan, you do not have to enter a credit card. You can get started for free with your $25 credit. You can enter a payment method later to move to a pay as you go plan or annual commitment plan if needed.
Enter your basic details:
- Database Name: Name your database something meaningful. The database name cannot be altered after the database is created. Use only alphanumeric characters; there is no character limit.
- Keyspace Name: Name your keyspace to reflect your data model. You cannot name your keyspace “dse” or “system”. Use only alphanumeric characters and no more than 48 total characters.
Select your cloud provider and then the region where you want to launch your database from the region menu, which reflects the available regions based on your selected cloud provider. Regions with the lock symbol require payment.

You can preview the costs for the database based on read and write requests, storage, and data transfer.

Select Create Database.
1. Click X at the top right of the screen to return to your Astra DB dashboard.
2. Click Generate Token to download tokens generated for you.
An alert appears at the top of the screen when your database is created.

Congrats! You have a database! Before you can load data into your database, you need to get a new application token.

Get an application token

Before you can load data into your newly created database, you need to create your application token.

You can also create an application token using the DevOps API.

From any page in Astra DB, select the Organizations dropdown.
In the main dropdown, select Organization Settings.
From your Organization page, select the Tokens tab.
Select the role you want to attach to your token. The permissions for your selected role will be displayed.
Select Generate Token. Astra DB will generate your token and display the Client ID, Client Secret, and Token.
Download your Client ID, Client Secret, and Token.

After you navigate away from the page, you won’t be able to download your Client ID, Client Secret, and Token again. These tokens do not automatically expire, but can be destroyed in case they are compromised or no longer needed.

Copy your application token and let’s go load some data into your database.

Load data into your database

You’ve already created your database and created your application token. Let’s take a look at loading data into your Astra DB database.

For this example, we will use the Document API.

You can also load data into your Astra DB database with any of these methods:

DataStax Bulk Loader to load data from csv or json files.
Data Loader feature in Astra Portal, which presents options to load CSV data; or load data from the provided sample datasets; or load data from your Amazon S3 bucket that contains exported DynamoDB data.
REST API calls to load data.
GraphQL API calls to load data.
Cassandra Query Language (CQL) statements to load data.
Drivers to load data via apps.

Writing documents

All data written with the Document API is stored as JSON documents stored in collections.

The maximum size of a document is 1 MB.

For more information about the database design of the Document API, see the blog post on the Documents API.

Add document specifying a collection name

First, let’s add a document to a specified collection. Send a POST request to /api/docs/v2/namespaces/{namespace_name}/collections/{collections_name} to add data to the collection fitness. The data is passed in the JSON body.

cURL command (/v2)
Result

curl --location \
--request POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/namespaces/myworld/collections/fitness' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "some-stuff",
  "other": "This is nonsensical stuff."
}'

{"documentId":"{docid}"}

Notice that the document-id returned is a UUID if not specified.

Add document specifying collection name and document-id

Next, let’s add a document to a specified collection, but specify the document-id. Send a PUT request to /api/docs/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 command (/v2)
Result

curl -L -X PUT 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/namespaces/myworld/collections/fitness/Janet' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "firstname": "Janet",
  "lastname": "Doe",
  "email": "janet.doe@gmail.com",
  "favorite color": "grey"
}'

{"documentId":"Janet"}

Note the difference between using POST and PUT. The POST request is used to insert new documents when you want the system to auto-generate the documentId. The PUT request is used to insert a new document when you want to specify the documentId.

PUT requests can also be used to update an existing document. Let’s look at those examples, next.

Now, let’s get data from your database.

Get data from your database

So far, we’ve created a database, created an application token, and loaded data into your database. Next, let’s get your data from your database.

Retrieving a specified document

Let’s check that the data was inserted for a particular document. Send a GET request to /api/docs/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id} to retrieve the document:

cURL command (/v2)
Result

curl -L \
-X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/namespaces/myworld/collections/fitness/{docid}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'

{
	"documentId":"{docid}",
	"data":{
		"id":"some-stuff",
		"other":"This is nonsensical stuff."
	}
}

It is possible to get a value for a particular field in a document using one of two methods, either a where clause or a document-path. These methods can retrieve information from a document or a sub-document.

Retrieving a document using a where clause

Now let’s search for a particular document using a where clause. Send a GET request to /api/docs/v2/namespaces/{namespace_name}/collections/{collections_name}?{where-clause} to get the same information:

cURL command (/v2)
Result

curl -L -X  GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/namespaces/myworld/collections/fitness?where=\{"firstname":\{"$eq":"Janet"\}\}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'

{
	"data":{
		"Janet":{
			"email":"janet.doe@gmail.com",
			"favorite color":"grey",
			"firstname":"Janet",
			"lastname":"Doe"
		}
	}
}

Note that the where clause must be url encoded, so curly brackets are escaped with \ and spaces must be replaced with %20. Also, the full document is returned, as opposed to the value of the field specified in the {document-path} like the next command.

What’s next?

Are you ready to explore more in Astra DB? Check out these topics:

Ways to get data into and out of your database
Learn how to create and manage an organization
- Invite users to your organization
- Create application tokens
Browse other tutorials
- Build a sample application