Get started with the Data API
Mission Control allows you to view Data API connection details in the UI to interact with the databases in your datacenter. On the Connect page, you can learn how to connect to the Data API and access the API documentation.
The Data API allows you to interact with your database using JSON payloads. You can interact with the Data API through clients or HTTP.
Prerequisites
-
An active Hyper-Converged Database (HCD) or DataStax Enterprise (DSE) license
-
A running HCD or DSE cluster
Install a client
Use a package manager to install the client library for your preferred language.
-
Python
-
TypeScript
-
Java
-
curl
Install the Python client with pip:
-
Verify that pip is version 23.0 or later:
pip --version
-
If needed, upgrade pip:
python -m pip install --upgrade pip
-
Install the astrapy package . You must have Python 3.8 or later.
pip install astrapy
Install the TypeScript client:
-
Verify that Node is version 18 or later:
node --version
-
Install astra-db-ts with your preferred package manager:
-
npm
-
Yarn
-
pnpm
npm install @datastax/astra-db-ts
yarn add @datastax/astra-db-ts
pnpm add @datastax/astra-db-ts
-
Install the Java client with Maven or Gradle.
-
Maven
-
Gradle
-
Install Java 11 or later and Maven 3.9 or later.
-
Create a
pom.xml
file in the root of your project, and then replaceVERSION
with the latest version of astra-db-java .pom.xml<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>test-java-client</artifactId> <version>1.0-SNAPSHOT</version> <!-- The Java client --> <dependencies> <dependency> <groupId>com.datastax.astra</groupId> <artifactId>astra-db-java</artifactId> <version>VERSION</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <version>3.0.0</version> <configuration> <executable>java</executable> <mainClass>com.example.Quickstart</mainClass> </configuration> <executions> <execution> <goals> <goal>java</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>11</source> <target>11</target> </configuration> </plugin> </plugins> </build> </project>
-
Install Gradle and Java 11 or later.
-
Create a
build.gradle
file in the root of your project:build.gradleplugins { id 'java' id 'application' } repositories { mavenCentral() } dependencies { implementation 'com.datastax.astra:astra-db-java:1.+' } application { mainClassName = 'com.example.Quickstart' }
To interact with the Data API directly through HTTP, install a tool to handle API calls, such as curl.
Upgrade a client
When a new client version is released, upgrade your client to get the latest features, improvements, and bug fixes.
-
Python
-
TypeScript
-
Java
-
curl
# verbose
pip install astrapy --upgrade
# shorthand
pip install -U astrapy
Reinstall the TypeScript client at the latest version.
For the TypeScript client, DataStax recommends reinstallation instead of upgrade
and update
commands, such as npm update @datastax/astra-db-ts
, that install the latest version allowed by your package.json
.
If your package.json
pins a version that is earlier than the actual latest version, then upgrade
and update
won’t install the actual latest version.
# npm
npm install @datastax/astra-db-ts@latest
# Yarn
yarn add @datastax/astra-db-ts@latest
# pnpm
pnpm add @datastax/astra-db-ts@latest
To upgrade your Java client, modify the astra-db-java
version in your project’s build.gradle
or pom.xml
.
For information about upgrading a utility like curl, see the documentation for that tool.
Connect with the Data API
The Data API allows you to programmatically load, delete, and find data in your database. You can view and manage the API gateways for your datacenter in the Mission Control UI.
-
In the Mission Control UI navigation menu, select your project, and then select your database cluster.
-
Click Connect.
-
Click APIs to open the Active API gateways page.
-
Create an API gateway for your datacenter:
-
Click Add Gateway, and then select the datacenter you want to expose using the Data API.
-
Under Replicas, enter the number of replicas. DataStax recommends a single replica for development and testing purposes and at least two replicas for production environments.
-
Select a Service Type from the list: nodePort or clusterIP.
-
nodePort service
-
clusterIP service
A
nodePort
service exposes the gateway outside Kubernetes on all nodes in the cluster through the specified port. For anodePort
service, you can access the Data API from all configured VMs/worker nodes in the Mission Control cluster:http://DNS_NAME_OR_IP_ADDRESS_OF_CLUSTER_NODE:CONFIGURED_PORT
Replace the following:
-
DNS_NAME_OR_IP_ADDRESS_OF_CLUSTER_NODE
: DNS name or IP address of a node in the Mission Control cluster -
CONFIGURED_PORT
: Port number configured for the Data API service
The port must be in the 30000-32767 range.
A
clusterIP
service exposes the gateway inside the Kubernetes cluster only. For aclusterIP
service, use the following address to access the Data API from within the cluster:http://CLUSTER_NAME-DC_NAME-data-api-cip.PROJECT_SLUG.svc:CONFIGURED_PORT
Replace the following:
-
CLUSTER_NAME
: Name of the Mission Control cluster -
*DC_NAME:
: Name of the datacenter -
PROJECT_SLUG
: Name of the project -
CONFIGURED_PORT
: Port number configured for the Data API service
The generated service name is:
<GATEWAY_NAME>-data-api-cip
. -
-
Enter a Port Number, and then click Add Gateway. The port must be in the 30000-32767 range.
-
Create a Data API token
The Data API expects a token in the following format: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD
.
You set these credentials when you create a cluster in Mission Control.
If you didn’t provide superuser credentials when you created your cluster, Mission Control generated them automatically and saved then in a superuser secret named CLUSTER_NAME-superuser
.
The CLUSTER_NAME-superuser
secret contains both the username and the 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.
If you are using the Python, TypeScript, or Java client, you can also use the UsernamePasswordTokenProvider
class to create a token.
For more information, see Instantiate a client object.
Connect to a database
This operation is the basis of Data API calls. It is one of the first operations you need in any client script, and you’ll encounter these commands at the beginning of many code examples throughout the HCD and DSE documentation.
You inherently connect to a database when you send curl requests to the Data API. The first part of the endpoint URL specifies the target database, and the path parameter specifies the working namespace.
curl -sS --location -X POST "DATA_API_ENDPOINT/v1/NAMESPACE_NAME" \
--header "Token: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD" \
--header "Content-Type: application/json" \
--data '{}'
Replace the following:
-
DATA_API_ENDPOINT:
The database’s API endpoint URL -
NAMESPACE_NAME:
The working namespace to use -
BASE64-ENCODED_USERNAME:
Base64-encoded username -
BASE64_ENCODED_PASSWORD:
Base64-encoded password
Instantiate a client object
When you create apps using the Data API clients for Python, TypeScript, and Java, your main entry point is the DataAPIClient
object.
Using an authentication token, the client can produce a reference to a database.
For Mission Control databases, you can specify the authentication token using the UsernamePasswordTokenProvider
class.
-
Python
-
TypeScript
-
Java
View this topic in more detail on the API Reference.
token_provider = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)
# Initialize the client and get a "Database" object
database = DataAPIClient(
token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
Returns:
database
- An instance of the Database
class.
Example response
Database(api_endpoint="http://localhost:8181", token="Cassandra:dX...", namespace="(not set)")
Parameters for UsernamePasswordTokenProvider
:
Name | Type | Summary |
---|---|---|
username |
|
A username for token creation. Example: |
password |
|
A password for token creation. Example: |
Parameters for DataAPIClient
:
Name | Type | Summary |
---|---|---|
token |
|
The authentication token. It can be a string or an instance of an |
environment |
|
The target Data API environment. Accepted values must be one of |
Parameters for get_database
:
Name | Type | Summary |
---|---|---|
api_endpoint |
|
The URL for the API endpoint base URL, such as |
token |
|
A specialized token, which overrides any token previously given to the client. |
namespace |
|
Pass this argument to set a working namespace for the returned |
Example:
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Database settings
DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"
DB_API_ENDPOINT = "http://localhost:8181"
# Prepare a token provider
token_provider = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)
# Initialize the client and get a "Database" object
client = DataAPIClient(token=token_provider, environment=Environment.HCD)
database = client.get_database(DB_API_ENDPOINT)
Most
See the API reference for |
View this topic in more detail on the API Reference.
// Build a token in the required format
const tokenProvider = new UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD);
// Initialize the client and get a "Db" object
const client = new DataAPIClient({ environment: 'hcd' });
Returns:
DataAPIClient
- An instance of the client class.
Parameters:
Name | Type | Summary |
---|---|---|
username |
|
A username for token creation. Example: |
password |
|
A password for token creation. Example: |
options? |
The options to use for the client. |
Options (DataAPIClientOptions
):
Name | Type | Summary |
---|---|---|
Options related to the API requests the client makes. |
||
Allows default options for when spawning a Db instance. |
||
Allows default options for when spawning some Admin instance. |
Http options (DataAPIHttpOptions
):
The DataAPIHttpOptions
type is a discriminated
union on the client
field.
There are four available behaviors for the client
field:
-
httpOptions
not set: Usefetch-h2
if available or fall back tofetch
. -
client: 'default'
or unset: Usefetch-h2
if available or throw an error. -
client: 'fetch'
: Only use the nativefetch
API. -
client: 'custom'
: Pass a custom Fetcher implementation to the client.
fetch-h2
is generally available by default on node runtimes only.
On other runtimes, you might need to use the native fetch
API or, if your code is minified, pass in the fetch-h2
module manually.
For more information on http clients, see the astra-db-ts README and the API reference.
For information on setting up commands monitoring, see the astra-db-ts README.
Example:
import { DataAPIClient, UsernamePasswordTokenProvider, VectorDoc, UUID } from '@datastax/astra-db-ts';
// Database settings
// Database settings, assuming that you exported them as environment variables
const DB_USERNAME = process.env.DB_USERNAME;
const DB_PASSWORD = process.env.DB_PASSWORD;
const DB_API_ENDPOINT = process.env.DB_API_ENDPOINT;
const DB_ENVIRONMENT = process.env.DB_ENVIRONMENT;
const DB_NAMESPACE = process.env.DB_NAMESPACE;
// Build a token in the required format
const tokenProvider = new UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD);
// Initialize the client and get a "Db" object
const client = new DataAPIClient({ environment: 'hcd' });
const db = client.db(DB_API_ENDPOINT, { token: tp });
const dbAdmin = db.admin({ environment: 'hcd' });
// Build a token in the form of Cassandra:base64(username):base64(password)
String token = new UsernamePasswordTokenProvider(cassandraUserName, cassandraPassword).getTokenAsString();
// Initialize the client
DataAPIClient client = new DataAPIClient(token, builder().withDestination(databaseEnvironment).build());
Returns:
DataAPIClient
- An instance of the client class.
Parameters:
Name | Type | Summary |
---|---|---|
username |
|
A username for token creation. Example: |
password |
|
A password for token creation. Example: |
options |
A class wrapping the advanced configuration of the client, such as |
Example:
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.Database;
import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
import com.datastax.astra.client.model.CollectionOptions;
import com.datastax.astra.client.model.CommandOptions;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.FindOneOptions;
import com.datastax.astra.client.model.NamespaceOptions;
import com.datastax.astra.client.model.SimilarityMetric;
import com.datastax.astra.internal.auth.UsernamePasswordTokenProvider;
import java.util.Optional;
import static com.datastax.astra.client.DataAPIClients.DEFAULT_ENDPOINT_LOCAL;
import static com.datastax.astra.client.DataAPIOptions.DataAPIDestination.HCD;
import static com.datastax.astra.client.DataAPIOptions.builder;
import static com.datastax.astra.client.model.Filters.eq;
public class QuickStartHCD {
public static void main(String[] args) {
// Database Settings
String cassandraUserName = "cassandra";
String cassandraPassword = "cassandra";
String dataApiUrl = DEFAULT_ENDPOINT_LOCAL; // http://localhost:8181
String databaseEnvironment = "HCD" // DSE, HCD, or ASTRA
String keyspaceName = "ks1";
String collectionName = "lyrics";
// Database settings if you export them as environment variables
// String cassandraUserName = System.getenv("DB_USERNAME");
// String cassandraPassword = System.getenv("DB_PASSWORD");
// String dataApiUrl = System.getenv("DB_API_ENDPOINT");
// OpenAI Embeddings
String openAiProvider = "openai";
String openAiKey = System.getenv("OPENAI_API_KEY"); // Need to export OPENAI_API_KEY
String openAiModel = "text-embedding-3-small";
int openAiEmbeddingDimension = 1536;
// Build a token in the form of Cassandra:base64(username):base64(password)
String token = new UsernamePasswordTokenProvider(cassandraUserName, cassandraPassword).getTokenAsString();
System.out.println("1/7 - Creating Token: " + token);
// Initialize the client
DataAPIClient client = new DataAPIClient(token, builder().withDestination(databaseEnvironment).build());
System.out.println("2/7 - Connected to Data API");
Create a keyspace for your collections
Run the following commands to create a keyspace:
curl -sS --location -X POST "DATA_API_ENDPOINT/v1/" \
--header "Token: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD" \
--header "Content-Type: application/json" \
--data '{"createKeyspace": {"name": "KEYSPACE_NAME"}}'
Replace the following:
-
DATA_API_ENDPOINT
: The endpoint of the Data API service -
BASE64-ENCODED_USERNAME
: The base64-encoded username -
BASE64_ENCODED_PASSWORD
: The base64-encoded password -
KEYSPACE_NAME
: The name of the keyspace
Create a collection in a keyspace
Once your keyspace is created, you can create a collection in the keyspace. Run the following command:
curl -sS --location -X POST "DATA_API_ENDPOINT/v1/KEYSPACE_NAME" \
--header "Token: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD" \
--header "Content-Type: application/json" \
--data '{"createCollection": {"name": "COLLECTION_NAME"}}'
Create a document in a collection
Replace the following:
-
DATA_API_ENDPOINT
: The endpoint of the Data API service -
KEYSPACE_NAME
: The name of the keyspace -
BASE64-ENCODED_USERNAME
: The base64-encoded username -
BASE64_ENCODED_PASSWORD
: The base64-encoded password -
COLLECTION_NAME
: The name of the collection
Once your collection is created, you can run the following command to create a document in the collection:
curl -sS --location -X POST "DATA_API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD" \
--header "Content-Type: application/json" \
--data '{"insertOne": {"document": {"foo": "bar"}}}'
Replace the following:
-
DATA_API_ENDPOINT
: The endpoint of the Data API service -
KEYSPACE_NAME
: The name of the keyspace -
BASE64-ENCODED_USERNAME
: The base64-encoded username -
BASE64_ENCODED_PASSWORD
: The base64-encoded password -
COLLECTION_NAME
: The name of the collection
You can also use a keyspace and/or collection that you previously created without using the API.
See also
The Data API organizes data into collections within keyspaces in the current version. Documents are stored in collections.
For more information, see the following topics: