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:

  1. Verify that pip is version 23.0 or later:

    pip --version
  2. If needed, upgrade pip:

    python -m pip install --upgrade pip
  3. Install the astrapy package Latest release. You must have Python 3.8 or later.

    pip install astrapy

Install the TypeScript client:

  1. Verify that Node is version 18 or later:

    node --version
  2. Install astra-db-ts Latest release 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

  1. Install Java 11 or later and Maven 3.9 or later.

  2. Create a pom.xml file in the root of your project, and then replace VERSION with the latest version of astra-db-java Maven Central.

    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>
  1. Install Gradle and Java 11 or later.

  2. Create a build.gradle file in the root of your project:

    build.gradle
    plugins {
        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.

  1. In the Mission Control UI navigation menu, select your project, and then select your database cluster.

  2. Click Connect.

  3. Click APIs to open the Active API gateways page.

  4. Create an API gateway for your datacenter:

    1. Click Add Gateway, and then select the datacenter you want to expose using the Data API.

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

    3. 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 a nodePort 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 a clusterIP 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.

    4. 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)")
Name Type Summary

username

str

A username for token creation. Example: cassandra.

password

str

A password for token creation. Example: cassandra.

Parameters for DataAPIClient:

Name Type Summary

token

Optional[Union[TokenProvider, str]]

The authentication token. It can be a string or an instance of an UsernamePasswordTokenProvider.

environment

str

The target Data API environment. Accepted values must be one of astrapy.constants.Environment or the equivalent string. For example, Environment.HCD or "hcd".

Parameters for get_database:

Name Type Summary

api_endpoint

str

The URL for the API endpoint base URL, such as "http://localhost:8181".

token

Optional[Union[TokenProvider, str]]

A specialized token, which overrides any token previously given to the client.

namespace

Optional[str]

Pass this argument to set a working namespace for the returned Database. If this argument isn’t provided, the database object won’t be able to perform some operations yet. See Create a namespace in the HCD or DSE documentation for a suggested pattern when the namespace is yet to be created, such as on a fresh instance.

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 astrapy objects have an asynchronous counterpart to use within the asyncio framework. To get an AsyncDatabase, use the get_async_database method of the client, or call the database.to_async() method on the synchronous database.

async_db = client.get_database(
    DB_API_ENDPOINT,
    namespace="the_namespace",
)
col_names = await async_db.list_collection_names()

my_collection = await async_db.get_collection("the_collection")
await my_collection.insert_one({"_id": 10})

See the API reference for AsyncDatabase to start exploring the async API.

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

str

A username for token creation. Example: cassandra.

password

str

A password for token creation. Example: cassandra.

options?

DataAPIClientOptions

The options to use for the client.

Name Type Summary

httpOptions?

DataAPIHttpOptions

Options related to the API requests the client makes.

dbOptions?

DbSpawnOptions

Allows default options for when spawning a Db instance.

adminOptions?

AdminSpawnOptions

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: Use fetch-h2 if available or fall back to fetch.

  • client: 'default' or unset: Use fetch-h2 if available or throw an error.

  • client: 'fetch': Only use the native fetch 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

str

A username for token creation. Example: cassandra.

password

str

A password for token creation. Example: cassandra.

options

DataAPIOptions

A class wrapping the advanced configuration of the client, such as HttpClient settings like timeouts.

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:

  • Keyspaces in the HCD or DSE documentation.

  • Collections in the HCD or DSE documentation.

  • Documents in the HCD or DSE documentation.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com