Java Client for Data API

A Java client for DataStax Astra DB.

This client library provides a simplified way to interact with the Data API for Astra DB Serverless, Hyper-Converged Database (HCD), or local instances.

Key Features

• 🚀 Zero-config: Connect to Astra DB in 3 lines of code.
• 🔍 Unified API: Seamless support for Collections (JSON Documents) and Tables (Structured Rows).
• 🧠 AI-Ready: Native support for Vector Search and Server-side Embeddings (Vectorize).
• ☕ Java-Centric: Fluent builders, POJO mapping, and Jackson support.
• ⚡ Sync & Async: Built on HttpClient with full support for synchronous and asynchronous operations.

---

Table of Contents

1. Quickstart
2. Architecture Overview
3. Connecting to a Database
4. Collections and Documents
5. Tables and POJO Mapping
6. Support Functions
7. Samples
8. Running Tests
9. Help & Support
10. Resources & Documentation

---

1. Quickstart

Prerequisites

• Java 17 or higher.
• An Astra DB API Endpoint and Token (get them at astra.datastax.com).

Installation

Maven

<dependency>
    <groupId>com.datastax.astra</groupId>
    <artifactId>astra-db-java</artifactId>
    <version>2.1.7</version>
</dependency>

Gradle

implementation 'com.datastax.astra:astra-db-java:2.1.7'

⚡ Connect and Query in 30 Seconds

Click to view required imports

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.vector.SimilarityMetric;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.core.query.FindOptions;
import java.util.List;
import java.util.UUID;

public class Quickstart {
    public static void main(String[] args) {
        // 1. Connect
        DataAPIClient client = new DataAPIClient("AstraCS:...");
        Database db = client.getDatabase("[https://01234567-....apps.astra.datastax.com](https://01234567-....apps.astra.datastax.com)");

        // 2. Create a vector collection
        Collection<Document> collection = db.createCollection(
            "dreams",
            CollectionDefinition.builder()
                .vector(3, SimilarityMetric.COSINE)
                .build()
        );

        // 3. Insert documents with vectors
        collection.insertMany(List.of(
            new Document()
                .id(UUID.fromString("018e65c9-e33d-749b-9386-e848739582f0"))
                .append("summary", "Riding the waves")
                .append("tags", List.of("sport"))
                .vector(new float[]{0f, 0.2f, 1f}),
            new Document()
                .append("summary", "Friendly aliens in town")
                .append("tags", List.of("scifi"))
                .vector(new float[]{-0.3f, 0f, 0.8f})
        ));

        // 4. Vector search
        List<Document> results = collection.find(
            new Document(),
            new FindOptions()
                .sort(Sort.vector(new float[]{0f, 0.2f, 0.4f}))
                .limit(2)
                .includeSimilarity(true)
        ).toList();

        results.forEach(doc ->
            System.out.println(doc.getString("summary") + ": " + doc.getSimilarity())
        );
    }
}

---

2. Architecture Overview

The SDK follows a layered hierarchy that mirrors the Data API itself.

graph TD
    A[DataAPIClient] -->|connects to| B[Database]
    A -->|manages| F[AstraDBAdmin]
    B -->|contains| C[Collection<T>]
    B -->|contains| D[Table<T>]
    F -->|manages| G[DatabaseAdmin]

    C -->|CRUD + Search| E["insert · find · update · delete"]
    D -->|CRUD + Search| E

    style A fill:#1a1a2e,stroke:#e94560,color:#fff
    style B fill:#16213e,stroke:#0f3460,color:#fff
    style C fill:#0f3460,stroke:#533483,color:#fff
    style D fill:#0f3460,stroke:#533483,color:#fff
    style F fill:#16213e,stroke:#0f3460,color:#fff
    style G fill:#0f3460,stroke:#533483,color:#fff

Loading

Layer	Purpose
Client	Entry point. Holds authentication token and HTTP configuration.
Database	Represents a single database/keyspace. Creates and retrieves collections and tables.
Collection	Document-oriented operations on schemaless JSON data (MongoDB-style).
Table	Row-oriented operations on structured, schema-defined data.

---

3. Connecting to a Database

3.1 Astra DB Serverless

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;

// Connect with your Astra token
DataAPIClient client = new DataAPIClient("AstraCS:...");
Database database = client.getDatabase("[https://01234567-....apps.astra.datastax.com](https://01234567-....apps.astra.datastax.com)");

3.2 HCD and Local Installations

Connect to a Hyper-Converged Database (HCD), local DSE, or any Data API-compatible instance using a UsernamePasswordTokenProvider.

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.auth.UsernamePasswordTokenProvider;

TokenProvider tp = new UsernamePasswordTokenProvider("cassandra", "cassandra");
DataAPIClient client = new DataAPIClient(tp);
Database database = client.getDatabase("http://localhost:8181");

Tip: Start a local HCD instance with docker-compose up -d using the docker-compose.yml included in this repository.

---

4. Collections and Documents

4.1 Working with Collections

Server-Side Embeddings (Vectorize)

Delegate embedding computation to the server by specifying a provider (e.g., OpenAI, NVIDIA, HuggingFace) at collection creation.

Collection<Document> collection = database.createCollection(
    "my_vectorize_collection",
    CollectionDefinition.builder()
        .vectorize("openai", "text-embedding-3-small")
        .build()
);

// Insert — the server generates the embedding automatically
collection.insertOne(new Document().append("$vectorize", "A text passage to embed"));

// Search using natural language
List<Document> results = collection.find(
    new FindOptions().sort(Sort.vectorize("search query"))
).toList();

Filtering and Updates

import com.datastax.astra.client.core.query.Filter;

// Find with a filter
List<Document> scifiDocs = collection.find(
    new Filter().where("tags", "scifi")
).toList();

// Update a document
collection.updateOne(
    new Filter().where("tags", "sport"),
    new Document().append("$set", new Document().append("summary", "Surfers' paradise"))
);

4.2 Working with Documents

The Document class is the primary data container for collections.

📖 Deep Dive: See the Document API Reference for full details on escaping rules, dot-notation access, and typed getters.

---

5. Tables and POJO Mapping

5.1 Working with Tables

Tables provide structured, schema-defined storage with full vector search support.

// Define the schema
TableDefinition tableDef = TableDefinition.builder()
    .addColumn("dream_id", ColumnTypes.INT)
    .addColumn("summary", ColumnTypes.TEXT)
    .addVectorColumn("dream_vector", 3, SimilarityMetric.COSINE)
    .addPartitionBy("dream_id")
    .build();

Table myTable = database.createTable("dreams_table", tableDef);

// Insert rows
myTable.insertOne(
    new Row()
        .add("dream_id", 103)
        .add("summary", "Riding the waves")
        .add("dream_vector", new float[]{0f, 0.2f, 1f})
);

5.2 POJO Mapping (Object Mapping)

Map collections and tables directly to Java classes using Jackson annotations.

public class Dream {
    @JsonProperty("_id")
    private int dreamId;

    @JsonProperty("$vector")
    private float[] vector;
    // ... getters/setters
}

// Get a typed collection
Collection<Dream> dreams = database.getCollection("dreams_collection", Dream.class);
dreams.insertOne(new Dream(500, ...));

---

6. Support Functions

• Administration: Use client.getAdmin() to manage databases and database.getDatabaseAdmin() to manage keyspaces.
• Logging: The client uses SLF4J. Configure Logback or Log4j2 to see debug logs.
• Error Handling: Catch DataAPIFaultyResponseException for API errors and DataAPIHttpException for network issues.

---

7. Samples

The astra-db-java-samples module contains runnable examples covering the main SDK features. Each sample is a standalone main() class you can run after setting your credentials.

Full index and tutorials: see the samples README for step-by-step tutorials and the complete list of samples.

Category	Sample	Description
Quickstart	SampleQuickstartHCD	End-to-end HCD quickstart: connect, create keyspace, vectorize query
Client	SampleClientConfiguration	Full configuration cookbook: HTTP settings, timeouts, proxies, observers
Collections	SampleCollectionInsertMany	Bulk insert with chunk size, concurrency, and ordering options
	SampleCollectionVectorize	Server-side embeddings (vectorize) for insert and search
	SampleCollectionDates	Working with Calendar, Date, and Instant fields
	SampleDocumentIds	All supported _id types: UUID, UUIDv6/v7, ObjectId, etc.
	SampleHybridCollectionDefinition	Hybrid collection with vector, lexical, and reranking
	SampleFindAndRerank	Hybrid search with findAndRerank API
Tables	SampleTableRows	Typed row builders and POJO mapping with @Column
	SampleTableVectorize	Vectorize on table columns with similarity search
	SampleTableUdtObjectMapping	User-Defined Types (UDT) with nested POJO mapping

---

8. Running Tests and Contributing

We welcome contributions!

For details on running the test suite (Local, Dev, Prod), configuring environment variables, and our coding standards, please see CONTRIBUTING.md.

---

9. Help & Support

If you encounter any issues or have questions:

• 🐛 Report Bugs: Open an issue on GitHub Issues.
• 💬 Community: Join the discussion on the DataStax Discord.
• 📚 StackOverflow: Tag questions with astra-db.

---

10. Resources & Documentation

Astra DB Serverless

• Quickstart: Collections
• Quickstart: Tables
• API Reference

Hyper-Converged Database (HCD)

• Quickstart: Collections
• Quickstart: Tables

---

Copyright © 2024 DataStax. Distributed under the Apache License 2.0.