Get started with the Data API

You can interact with the Data API directly or through the clients. Clients are available for Python, TypeScript, and Java.

Review the prerequisites and other information about the available APIs in the API reference overview.

Install a client

Install the client for your preferred language:

When you create apps using the Data API clients for Python, TypeScript, and Java, your main entry point is the DataAPIClient object. The client only needs a token, as it is not specific to a database. For self-managed databases, the token is created using UsernamePasswordTokenProvider.

Initialize the Python client

View this topic in more detail on the API Reference.

# Build a token
tp = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
client = DataAPIClient(token=tp, environment=Environment.DB_ENVIRONMENT)

Parameters:

Name Type Summary

Name	Type	Summary
username	`str`	A username for token creation. Example: `cassandra`.
password	`str`	A password for token creation. Example: `cassandra`.
environment	`str`	The environment to use with `Environment`. Example: `DSE`.

username

str

A username for token creation. Example: cassandra.

password

str

A password for token creation. Example: cassandra.

environment

str

The environment to use with Environment. Example: DSE.

Returns DataAPIClient, which is an instance of the client class.

Examples:

import os

from astrapy import DataAPIClient
from astrapy.constants import Environment
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import VectorMetric
from astrapy.ids import UUID
from astrapy.exceptions import InsertManyException
from astrapy.info import CollectionVectorServiceOptions

# Database settings
DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"
DB_API_ENDPOINT = "http://localhost:8181"
DB_KEYSPACE = "my_keyspace"
DB_COLLECTION = "vector_test"

# Database settings if you exported them as environment variables
# DB_USERNAME = os.environ.get("DB_USERNAME")
# DB_PASSWORD = os.environ.get("DB_PASSWORD")
# DB_API_ENDPOINT = os.environ.get("DB_API_ENDPOINT")

# Embedding provider settings
EMBEDDING_PROVIDER = "openai";
EMBEDDING_MODEL_NAME = "text-embedding-3-small";
EMBEDDING_DIMENSIONS = 1024
EMBEDDING_API_KEY = os.environ.get("EMBEDDING_API_KEY");

# Build a token
tp = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
client = DataAPIClient(environment=Environment.DSE)
database = client.get_database(DB_API_ENDPOINT, token=tp)
database.get_database_admin().create_keyspace(DB_KEYSPACE, update_db_keyspace=True)

DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"

# Build a token
tp = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
client = DataAPIClient(token=tp, environment=Environment.DSE)

Initialize the TypeScript client

View this topic in more detail on the API Reference.

// Build a token in the required format
const tp = new UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD);

// Initialize the client and get a "Db" object
const client = new DataAPIClient({ environment: DB_ENVIRONMENT });

Parameters:

General

Name Type Summary

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, including defaults.

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, including defaults.

Options (DataAPIClientOptions)

Name Type Summary

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.

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.

Monitoring/logging

For information on setting up commands monitoring, see the astra-db-ts README.

Returns DataAPIClient, which is an instance of the client class.

Examples:

import { DataAPIClient, UsernamePasswordTokenProvider, VectorDoc, UUID } from '@datastax/astra-db-ts';

// Database settings
const DB_USERNAME = "cassandra";
const DB_PASSWORD = "cassandra";
const DB_API_ENDPOINT = "http://localhost:8181";
const DB_ENVIRONMENT = "dse";
const DB_KEYSPACE = "cycling";

// Database settings if 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;

// OpenAI settings
const OPEN_AI_PROVIDER = "openai";
const OPENAI_API_KEY = process.env.OPENAI_API_KEY
const MODEL_NAME = "text-embedding-3-small";

// Build a token in the required format
const tp = new UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD);

// Initialize the client and get a "Db" object
const client = new DataAPIClient({ environment: DB_ENVIRONMENT });
const db = client.db(DB_API_ENDPOINT, { token: tp });
const dbAdmin = db.admin({ environment: DB_ENVIRONMENT });

DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"
DB_ENVIRONMENT = "dse"

# Build a token
tp = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
client = DataAPIClient(token=tp, environment=Environment.DB_ENVIRONMENT)

Initialize the Java client

// 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());

Parameters:

Name Type Summary

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 as `HttpClient` settings (timeouts…).

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 as HttpClient settings (timeouts…).

Returns DataAPIClient, which is an instance of the client class.

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.KeyspaceOptions;
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 QuickStartDSE69 {

    public static void main(String[] args) {

        // Database Settings
        String cassandraUserName     = "cassandra";
        String cassandraPassword     = "cassandra";
        String dataApiUrl            = DEFAULT_ENDPOINT_LOCAL;  // http://localhost:8181
        String databaseEnvironment   = "DSE" // 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");

Get started with the Data API

Install a client

Instantiate a client object

Initialize the Python client

Initialize the TypeScript client

Initialize the Java client

Was this helpful?

Give Feedback