Get started with the Data API
You can use the Data API to programmatically interact with your databases.
The Data API provides an entry point for application development with Hyper-Converged Database (HCD) databases, including a variety of GenAI ecosystem integrations. It leverages the scalability, performance, and real-time indexing capabilities of Apache Cassandra® to support GenAI application development.
Get endpoint and token
The Data API requires your database’s API endpoint and an application token.
Get endpoint
The Data API endpoint for your database has the form: http://CLUSTER_HOST:GATEWAY_PORT
-
Replace CLUSTER_HOST with the external IP address of any node in your cluster. To find this, run
kubectl get nodes -o wide
and use any of the values listed under "EXTERNAL-IP" in the output. -
Replace GATEWAY_PORT with the port number for your API gateway service. To find this, run
kubectl get svc
and look for the "PORT(S)" value that corresponds toNodePort
.
Generate token
The Data API requires an application token in the following format: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD
.
The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations.
You set a username and password when you create a cluster.
If you didn’t provide superuser credentials when you created your cluster, they were generated automatically and saved in a superuser secret named CLUSTER_NAME-superuser
.
The CLUSTER_NAME-superuser
secret contains both the username and the password.
-
Python
-
TypeScript
-
Java
-
curl
You can use UsernamePasswordTokenProvider
from the client to generate the token.
Alternatively, you can build the token yourself as demonstrated in the curl
tab.
from astrapy.authentication import UsernamePasswordTokenProvider
token = UsernamePasswordTokenProvider("USERNAME", "PASSWORD")
You can use UsernamePasswordTokenProvider
from the client to generate the token.
Alternatively, you can build the token yourself as demonstrated in the curl
tab.
import { UsernamePasswordTokenProvider } from "@datastax/astra-db-ts";
const token = new UsernamePasswordTokenProvider("USERNAME", "PASSWORD");
You can use UsernamePasswordTokenProvider
from the client to generate the token.
Alternatively, you can build the token yourself as demonstrated in the curl
tab.
import com.datastax.astra.client.core.auth.UsernamePasswordTokenProvider;
public class Example {
public static void main(String[] args) {
String token =
new UsernamePasswordTokenProvider("USERNAME", "PASSWORD").getTokenAsString();
}
}
You can also inherently generate a token when you instantiate the client:
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
public class Example {
public static void main(String[] args) {
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
}
}
Run the following commands to get the username and password in base64 format:
kubectl get secret CLUSTER_NAME-superuser -n PROJECT_SLUG -o jsonpath="{.data.username}" | xargs
kubectl get secret CLUSTER_NAME-superuser -n PROJECT_SLUG -o jsonpath="{.data.password}" | xargs
Use the obtained values to create a token in the Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD
format.
Use a client
DataStax provides several clients to facilitate interaction with the Data API.
If there is no client for your preferred language, see Use HTTP.
Install a client
-
Python
-
TypeScript
-
Java
-
Update to Python version 3.8 or later if needed.
-
Update to pip version 23.0 or later if needed.
-
Install the latest version of the astrapy package
.
pip install "astrapy>=2.0,<3.0"
-
Update to Node version 18 or later if needed.
-
Update to TypeScript version 5 or later if needed. This is unnecessary if you are using JavaScript instead of TypeScript.
-
Install the latest version of the @datastax/astra-db-ts package
.
For example:
npm install @datastax/astra-db-ts
-
Maven
-
Gradle
-
Update to Java version 17 or later if needed. DataStax recommends Java 21.
-
Update to Maven version 3.9 or later if needed.
-
Add a dependency to the latest version of the astra-db-java package
.
pom.xml<dependencies> <dependency> <groupId>com.datastax.astra</groupId> <artifactId>astra-db-java</artifactId> <version>VERSION</version> </dependency> </dependencies>
-
Update to Java version 17 or later if needed. DataStax recommends Java 21.
-
Update to Gradle version 11 or later if needed.
-
Add a dependency to the latest version of the astra-db-java package
.
build.gradle(.kts)dependencies { implementation 'com.datastax.astra:astra-db-java:VERSION' }
Use the client to interact with data
In general, all scripts that use a client will do the following:
-
Instantiate a
DataAPIClient
object.All Data API interactions through a client start with a
DataAPIClient
object. -
Most Data API interactions through a client require you to connect to a database through a
DataAPIClient
object. -
Perform CRUD operations.
For example, you can create a collection or table, insert data, and find data. For a full list of operations, see the collection commands and table commands.
Here’s an example of a simple client script. For a more detailed demo, see the quickstart for collections and the quickstart for tables.
-
Python
-
TypeScript
-
Java
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Instantiate the client
client = DataAPIClient(environment=Environment.HCD)
# Connect to a database
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
# Get an existing collection
collection = database.get_collection(
"COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)
# Use vector search and filters to find a document
result = collection.find_one(
{
"$and": [
{"is_checked_out": False},
{"number_of_pages": {"$lt": 300}},
]
},
sort={"$vector": [0.12, -0.46, 0.35, 0.52, -0.32]},
)
print(result)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Instantiate the client
const client = new DataAPIClient({ environment: "hcd" });
// Connect to a database
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
// Get an existing collection
const collection = database.collection("COLLECTION_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Use vector search and filters to find a document
(async function () {
const result = await collection.findOne(
{
$and: [{ is_checked_out: false }, { number_of_pages: { $lt: 300 } }],
},
{ sort: { $vector: [0.12, -0.46, 0.35, 0.52, -0.32] } },
);
console.log(result);
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.databases.Database;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Instantiate the client
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
// Connect to a database
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
// Get an existing collection
Collection<Document> collection = database.getCollection("COLLECTION_NAME");
// Use vector search and filters to find a document
Filter filter =
Filters.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));
CollectionFindOneOptions options =
new CollectionFindOneOptions()
.sort(Sort.vector(new float[] {0.12f, -0.46f, 0.35f, 0.52f, -0.32f}));
Optional<Document> result = collection.findOne(filter, options);
System.out.println(result);
}
}
Use HTTP
You can interact directly with the Data API over HTTP using tools like curl or Go’s net/http
package.
Data API HTTP requests always use the POST
method, regardless of the actual CRUD operation performed by the command.
For a full list of commands, see the collection commands and table commands.
Most endpoints require you specify values:
Name | Summary |
---|---|
|
A database API endpoint URL. For information about how to find the endpoint, see Get endpoint and token. |
|
The target keyspace where you want to run the command. The target keyspace is also known as the working keyspace. |
|
The name of the collection or table where you want to run the command. |
|
An application token. The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations. For more information about how to generate a token, see Get endpoint and token. |
For example, use vector search and filters to find a document:
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"filter": {"$and": [
{"is_checked_out": false},
{"number_of_pages": {"$lt": 300}}
]},
"sort": { "$vector": [0.12, -0.46, 0.35, 0.52, -0.32] }
}
}'