Get started: Load and retrieve data in your database

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:

  1. Create your Astra DB account.

  2. Create your database.

  3. Get your application token.

  4. Load data to your database.

  5. 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

  1. In your Astra DB dashboard, select Create Database.

  2. If you don’t have an existing plan, select the free plan or a plan with annual savings.

    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 than the free or annual plan, contact DataStax Support.
  3. If you are creating a database with annual savings, enter your payment method to continue. If you are creating a free plan, you don’t 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 if needed.

  4. 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 can’t name your keyspace “dse” or “system”. Use only alphanumeric characters and no more than 48 total characters.

  5. 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.

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

  7. You will see a screen highlighting your selected plan. Select Continue.

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.

  1. From any page in Astra DB, select the Organizations dropdown.

    Organization Selection
  2. In the main dropdown, select Organization Settings.

  3. From your Organization page, select Token Management.

  4. Select the role you want to attach to your token. The permissions for your selected role will be displayed.

  5. Select Generate Token. Astra DB will generate your token and display the Client ID, Client Secret, and Token.

  6. 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.

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 database with these methods:

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 command (/v2)

  • Result

curl -sL \
--request POST --url http://$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 command (/v2)

  • Result

curl -sL -X PUT 'http://$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 all documents

Let’s check that the document was inserted. Send a GET request to /api/rest/v2/namespaces/myworld/collections/fitness to retrieve all the documents:

  • cURL command (/v2)

  • Result

curl -sL \
--request GET --url http://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?page-size=3 \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
  "data":{
     "Joey":{
	"firstname":"Joey",
	"lastname":"Doe",
	"weights":{
		"reps":15,
		"type":"bench press",
		"weight":150
	}
     },
     "Janet":{
	"email":"janet.doe@gmail.com",
	"favorite color":"grey",
	"firstname":"Janet",
	"lastname":"Doe"
     },
     "{docid}":{
	"id":"some-stuff",
	"other":"This is nonsensical stuff."
     }
  }
}

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.

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/myworld/collections/fitness/{document-id} to retrieve the document:

  • cURL command (/v2)

  • Result

curl -sL \
-X GET --url http://$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'
{
  "documentId": "Janet",
  "data": {
    "email": "janet.doe@gmail.com",
    "favorite color": "grey",
    "firstname": "Janet",
    "lastname": "Doe"
  }
}

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.

Operator options for reading with a WHERE clause

Most data retrieval uses a WHERE clause containing operators to designate a range of rows to return.

The operators available are:

  • eq (equal)

  • notEq (not equal) - limited use

  • gt (greater than)

  • gte (greater than or equal to)

  • lt (less than)

  • lte (less than or equal to)

  • in (within) - limited use

  • nin (not within) - limited use

The WHERE clause can use any of these operators, as applicable to the data type defined. The storage schema used by the Document API internally indexes all values, so any column can be used with an operator.

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/myworld/collections/fitness?{where-clause} to get the same information:

  • cURL command (/v2)

  • Result

curl -sL -X  GET --url 'http://$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: