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.
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.
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 your Astra DB dashboard, select Create Database.
- If you don’t have an existing plan, select the free plan or a plan with annual savings.
- 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.
- Enter your basic details:
- 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.
- Select Create Database.
- 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.
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 Token Management.
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.
Copy your application token and let's go load some 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:
First, let's add a document to a specified collection.Send a POST request to /api/rest/v2/namespaces/undefined/collections/undefined to add data to the collection fitness .The data is passed in the JSON body.
Notice that the document-id returned is a UUID if not specified.
Next, let's add a document to a specified collection, but specify the document-id .Send a PUT request to /api/rest/v2/namespaces/undefined/collections/undefined/undefined to add data to the collection Janet .The document-id can be any string.The data is passed in the JSON body.
Note the difference between using POST and PUT .The POST request is used to insert new documents when you want the system toauto-generate the documentId.The PUT request is used to insert a new document when you want to specify thedocumentId.
PUT requests can also be used to update an existing document.Let's look at those examples, next.
You can also insert documents that have nested values, or sub-documents.Send a PUT request to /api/rest/v2/namespaces/undefined/collections/undefined/undefined to add data to the existing collection.The data is passed in the JSON body.
Now, let's 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.
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:
The page-size parameter is included to get all the documents, rather than thelast inserted document.The pageState is useful for pagination of the results in queries.
Let's check that the data was inserted for a particular document.Send a GET request to /api/rest/v2/namespaces/myworld/collections/fitness/undefined to retrieve the document:
It is possible to get a value for a particular field in a document using one oftwo methods, either a where clause or a document-path.These methods can retrieve information from a document or a sub-document.
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 beused with an operator.
Now let's search for a particular document using a WHERE clause.Send a GET request to`/api/rest/v2/namespaces/myworld/collections/fitness?undefined`to get the same information:
Note that the where clause must be url encoded, so curly brackets are escapedwith and spaces must be replaced with %20`.Also, the full document is returned, as opposed to the value of the field specified in the undefined like the next command.
You can also search with a multiple where clause.Send a GET request to`/api/rest/v2/namespaces/myworld/collections/fitness?undefined`to get the same information:
You can also retrieve documents using a WHERE clause that searches sub-documents:
Multiple where can be used in a variety of cases.Here, a numerical value between to values is sought:
To find a particular value, send a GET request to /api/rest/v2/namespaces/myworld/collections/fitness/undefined/undefined to retrieve the type of weights Joey has done in his workout:
In this case, the sub-document weights is the document-path specified to retrieve that data about the reps , type , and weight .
Let's add another record for the next example:
To find particular values, send a GET request to /api/rest/v2/namespaces/myworld/collections/fitnessundefined to retrieve all the users that have, say, weight reps between 11 and 16:
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