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 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 keyspacefitness
. -
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.
-
Click X at the top right of the screen to return to your Astra DB dashboard.
-
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. |
-
In Astra Portal, select Settings in the left navigation.
-
Select Token Management.
-
Click the dropdown arrow to select the role you want to attach to your token. The permissions for your selected role are displayed.
-
Select Generate Token. Astra DB generates your token and displays 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:
|
Writing documents
All data written with the Document API is stored as JSON documents stored in collections.
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/rest/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 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/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/rest/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 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/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/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}
to retrieve the document:
curl -L \
-X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/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/rest/v2/namespaces/{namespace_name}/collections/{collections_name}?{where-clause}
to get the same information:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/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
-
Browse other tutorials