From f4b6752b91653694c3b37570437b05ec1255fabb Mon Sep 17 00:00:00 2001 From: skedwards88 Date: Wed, 17 Dec 2025 13:36:20 -0700 Subject: [PATCH] link to docs instead of having examples, format/minor reorg of the other sections --- README.MD | 432 ++++++++++++------------------------------------------ 1 file changed, 92 insertions(+), 340 deletions(-) diff --git a/README.MD b/README.MD index 33b149c..09752d0 100644 --- a/README.MD +++ b/README.MD @@ -4,64 +4,64 @@ [![License Apache2](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0) [![Maven Central](https://img.shields.io/maven-central/v/com.datastax.astra/astra-db-java)](https://search.maven.org/artifact/com.datastax.astra/astra-db-java) -This client library provides a simplified way to interact with Data API for AstraDB or local instances. For detailed documentation, each operation comes with a detailed description and examples. +This client library provides a simplified way to interact with the Data API for Astra DB Serverless, Hyper-Converged Database (HCD), or local instances. -- [`astra-db-ts`](https://github.com/datastax/astra-db-ts) is the equivalent for typescript -- [`astrapy`](https://github.com/datastax/astrapy) is the equivalent in python +For client libraries in other languages, see [Get started with the Data API](https://docs.datastax.com/en/astra-db-serverless/api-reference/dataapiclient.html). -This library is under development and is available in Maven Central. -You can build it locally and install it in your local repository. +## Using the client -## 📋 Table Of Content +For Astra DB Serverless: -1. [Installation](#1-installation) - 1. [Prerequisites](#11-prerequisites) - 2. [Packaging](#12-packaging) -2. [QuickStart with Astra DB](#2-quickstart-with-astra-db) - 1. [Sign up for Astra DB](#21-sign-up-for-astra-db) - 2. [Create a Database](#22-create-a-database) - 3. [Get your credentials](#23-get-your-credentials) - 4. [Create a new project and add the dependency](#24-create-a-new-project-and-add-the-dependency) -3. [QuickStart with Local Instances](#3-quickstart-with-local-instances) -4. [Running Integration Tests](#4-running-integration-tests) - 1. [Running Against AstraDB](#41-astra-db) - 2. [Running Against HCD](#42-hcd) - -## 1. Installation +- [Quickstart for collections](https://docs.datastax.com/en/astra-db-serverless/get-started/quickstart.html) +- [Quickstart for tables](https://docs.datastax.com/en/astra-db-serverless/get-started/quickstart-tables.html) +- [Get started with the Data API](https://docs.datastax.com/en/astra-db-serverless/api-reference/dataapiclient.html) -### 1.1 Prerequisites +For Hyper-Converged Database (HCD): + +- [Quickstart for collections](https://docs.datastax.com/en/hyper-converged-database/1.2/api-reference/quickstart.html) +- [Quickstart for tables](https://docs.datastax.com/en/hyper-converged-database/1.2/api-reference/quickstart-tables.html) +- [Get started with the Data API](https://docs.datastax.com/en/hyper-converged-database/1.2/api-reference/dataapiclient.html) + +For local instances, see [Using the Java client with a local instance](#using-the-java-client-with-a-local-instance) below. + +## Contributing + +### Prerequisites for contributing #### 📦 Java Development Kit (JDK) 17 + - Use the [reference documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html) to install a **Java Development Kit** -- Validate your installation with +- Validate your installation with: -```bash -java --version -``` + ```bash + java --version + ``` #### 📦 Apache Maven + - Use the [reference documentation](https://maven.apache.org/install.html) to install **Apache Maven** -- Validate your installation with +- Validate your installation with: -```bash -mvn -version -``` + ```bash + mvn -version + ``` #### 📦 Docker (local Installation) Docker is an open-source project that automates the deployment of software applications inside containers by providing an additional layer of abstraction and automation of OS-level virtualization on Linux. -### 1.2 Packaging +### Packaging -- Clone the repository +- Clone the repository: -```console -git clone git@github.com:datastax/astra-db-java.git -``` + ```console + git clone git@github.com:datastax/astra-db-java.git + ``` -- Build the project (java 11 and Maven is required) +- Build the project (Java 11 and Maven is required) -> Note: You should skip the tests if you want to speed up the build, to run the test you need to have a bit of setup: +> Note: You should skip the tests if you want to speed up the build. To run the test you need a bit of setup: +> > - An environment variable `ASTRA_DB_APPLICATION_TOKEN` with your an Organization Administrator Astra token (PROD) > - An environment variable `ASTRA_DB_APPLICATION_TOKEN_DEV` with your an Organization Administrator Astra token (DEV) > - A running Data API locally with docker (see the `docker-compose.yml` in the root of the project) @@ -70,135 +70,39 @@ git clone git@github.com:datastax/astra-db-java.git mvn clean install -Dtest.skipped=true ``` -## 2. QuickStart with Astra DB - -### 2.1. Sign up for Astra DB - -- Access [https://astra.datastax.com](https://astra.datastax.com) and register with `Google` or `Github` account. It is free to use. There is free forever tiers of up to 25$ of consumption every month. - -![](https://awesome-astra.github.io/docs/img/astra/astra-signin-github-0.png) - -### 2.2. Create a Database - -> If you are creating a new account, you will be brought to the DB-creation form directly. - -- Get to the databases dashboard (by clicking on Databases in the left-hand navigation bar, expanding it if necessary), and click the `[Create Database]` button on the right. - -![](https://datastaxdevs.github.io/langchain4j/langchain4j-1.png) - -- **ℹ️ Fields Description** - -| Field | Description | -|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Vector Database vs Serverless Database** | Choose `Vector Database` In june 2023, Cassandra introduced the support of vector search to enable Generative AI use cases. | -| **Database name** | It does not need to be unique, is not used to initialize a connection, and is only a label (keep it between 2 and 50 characters). It is recommended to have a database for each of your applications. The free tier is limited to 5 databases. | -| **Cloud Provider** | Choose whatever you like. Click a cloud provider logo, pick an Area in the list and finally pick a region. We recommend choosing a region that is closest to you to reduce latency. In free tier, there is very little difference. | -| **Cloud Region** | Pick region close to you available for selected cloud provider and your plan. | - -If all fields are filled properly, clicking the "Create Database" button will start the process. - -![](https://datastaxdevs.github.io/langchain4j/langchain4j-2.png) - -It should take a couple of minutes for your database to become `Active`. - -![](https://datastaxdevs.github.io/langchain4j/langchain4j-3.png) - -### 2.3. Get your credentials - -To connect to your database, you need the API Endpoint and a token. The api endpoint is available on the database screen, there is a little icon to copy the URL in your clipboard. (it should look like `https://-.apps.astra.datastax.com`). - -![](https://datastaxdevs.github.io/langchain4j/langchain4j-4.png) - -To get a token click the `[Generate Token]` button on the right. It will generate a token that you can copy to your clipboard. - -### 2.4 Create a new project and add the dependency - -Add the following dependency to your `pom.xml` file: - -```xml - - com.datastax.astra - astra-db-java - 2.1.4 - -``` - -Here is a sample class that demonstrates how to use the library: +### Using the Java client with a local instance -```java -import com.datastax.astra.client.DataAPIClient; -import com.datastax.astra.client.collections.Collection; -import com.datastax.astra.client.databases.Database; -import com.datastax.astra.client.collections.documents.Document; -import com.datastax.astra.client.core.paging.FindIterable; - -import java.util.List; - -import static com.datastax.astra.client.core.query.Filters.eq; -import static com.datastax.astra.client.core.vector.SimilarityMetric.cosine; - -public class GettingStarted { - public static void main(String[] args) { - // Initializing client with a token - DataAPIClient client = new DataAPIClient("my_token"); - - // Accessing the Database through the HTTP endpoint - Database db = client.getDatabase("http://db-region.apps.astra.datastax.com"); - - // Create collection with vector support - Collection col = db.createCollection("demo", 2, cosine); - - // Insert records - col.insertMany(List.of( - new Document("doc1").vector(new float[]{.1f, 0.2f}).append("key", "value1"), - new Document().id("doc2").vector(new float[]{.2f, 0.4f}).append("hello", "world"), - new Document("doc3").vector(new float[]{.5f, 0.6f}).append("key", "value1")) - ); - - // Search - FindIterable docs = col.find( - eq("key", "value1"), // metadata filter - new float[]{.5f, .5f}, //vector - 10); // maxRecord - - // Iterate and print your results - for (Document doc : docs) System.out.println(doc); - } -} -``` +> Prerequisite: You need HCD, DSE, or CASSANDRA running on your machine and listening on `9042`. One good way is to run HCD as a docker image following [these instructions](https://github.com/stargate/data-api/tree/main/docker-compose). -## 3. QuickStart with Local Instances +#### Run the Data API locally -> Prequisite. You need HCD, DSE or CASSANDRA running on your machine and listening on `9042`. One good way is to run HCD as a docker image following the instruction [here](https://github.com/stargate/data-api/tree/main/docker-compose). +- Clone the Data API repository: -### 3.1 Start Data API + ``` + git clone git@github.com:stargate/data-api.git + ``` -- Clone the repository -``` -git clone git@github.com:stargate/data-api.git -``` +- Access the folder and start the Data API. Note the cassandra endpoint is `localhost` and the datacenter is `dc1`. -- Access the folder and start the data API. Note that we position cassandra endpoint to `localhost` and datacenter to `dc1`. + ``` + cd data-api -``` -cd data-api - -STARGATE_DATA_STORE_SAI_ENABLED=true \ -STARGATE_DATA_STORE_VECTOR_SEARCH_ENABLED=true \ -STARGATE_JSONAPI_OPERATIONS_VECTORIZE_ENABLED=true \ -STARGATE_DATA_STORE_IGNORE_BRIDGE=true \ -STARGATE_JSONAPI_OPERATIONS_DATABASE_CONFIG_LOCAL_DATACENTER=dc1 \ -STARGATE_JSONAPI_OPERATIONS_DATABASE_CONFIG_CASSANDRA_END_POINTS=localhost \ -QUARKUS_HTTP_ACCESS_LOG_ENABLED=FALSE \ -QUARKUS_LOG_LEVEL=INFO \ -JAVA_MAX_MEM_RATIO=75 \ -JAVA_INITIAL_MEM_RATIO=50 \ -GC_CONTAINER_OPTIONS="-XX:+UseG1GC" \ -JAVA_OPTS_APPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager" \ -mvn quarkus:dev -Dstargate.data-store.ignore-bridge=true -Dstargate.jsonapi.operations.vectorize-enabled=true -Dstargate.jsonapi.operations.database-config.local-datacenter=dc1 -Dquarkus.log.console.darken=2 -Dstargate.feature.flags.tables=true -Dstargate.jsonapi.operations.extend-error=true -Dstargate.feature.flags.reranking=true -``` + STARGATE_DATA_STORE_SAI_ENABLED=true \ + STARGATE_DATA_STORE_VECTOR_SEARCH_ENABLED=true \ + STARGATE_JSONAPI_OPERATIONS_VECTORIZE_ENABLED=true \ + STARGATE_DATA_STORE_IGNORE_BRIDGE=true \ + STARGATE_JSONAPI_OPERATIONS_DATABASE_CONFIG_LOCAL_DATACENTER=dc1 \ + STARGATE_JSONAPI_OPERATIONS_DATABASE_CONFIG_CASSANDRA_END_POINTS=localhost \ + QUARKUS_HTTP_ACCESS_LOG_ENABLED=FALSE \ + QUARKUS_LOG_LEVEL=INFO \ + JAVA_MAX_MEM_RATIO=75 \ + JAVA_INITIAL_MEM_RATIO=50 \ + GC_CONTAINER_OPTIONS="-XX:+UseG1GC" \ + JAVA_OPTS_APPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss. logmanager.LogManager" \ + mvn quarkus:dev -Dstargate.data-store.ignore-bridge=true -Dstargate.jsonapi.operations.vectorize-enabled=true -Dstargate.jsonapi.operations.database-config.local-datacenter=dc1 -Dquarkus.log.console.darken=2 -Dstargate.feature.flags.tables=true -Dstargate.jsonapi.operations.extend-error=true -Dstargate.feature.flags.reranking=true + ``` -- To check the Data API is running +- Check that the Data API is running: | Field | Description | |--------------------------------------------|-----------------------------------------------------------------------------------------| @@ -208,7 +112,7 @@ mvn quarkus:dev -Dstargate.data-store.ignore-bridge=true -Dstargate.jsonapi.oper | **Token Header Value** | `Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh` (aka `Cassandra:Base64(userName):Base64(password)`) | | **Authentication API Spec (before 1.0.6)** | http://localhost:8081/swagger-ui/#/ | -- The API will have 3 resources +- The API will have 3 resources: | Field | Url | Description | |-----------------------|--------------------------------|---------------------------------------------------| @@ -216,145 +120,10 @@ mvn quarkus:dev -Dstargate.data-store.ignore-bridge=true -Dstargate.jsonapi.oper | **Data API Endpoint** | `/v1/{namespace}` | Interact with collections of a namespace | | **Token Header Key** | `/v1/{namespace}/{collection}` |Interact with documents of a collection | -- Create a keyspace called `default_keyspace` +#### Use the Java client with a local instance -```console -curl --location 'http://localhost:8181//v1' \ ---header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \ ---header 'Content-Type: application/json' \ ---data '{"createKeyspace":{"name":"default_keyspace"}}' -``` - -- Create a collection `person` with CURL (indexing) - -```console -curl --location 'http://localhost:8181//v1/default_keyspace' \ ---header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \ ---header 'Content-Type: application/json' \ ---data '{ - "createCollection": { - "name": "collection_person", - "options": { - "indexing": { - "allow": [ - "firstname", - "lastname" - ] - } - } - } -}' -``` - -- List my collection it should be there - -```console -curl --location 'http://localhost:8181//v1/default_keyspace' \ ---header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \ ---header 'Content-Type: application/json' \ ---data '{ - "findCollections": {} -}' -``` -- Inserts a few documents - -```console -curl --location 'http://localhost:8181/v1/default_keyspace/collection_person' \ ---header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "insertMany": { - "documents": [ - { - "_id": 1, - "firstname": "Lucas", - "lastname": "Hernandez", - "age": 22 - }, - { - "_id": 2, - "firstname": "Antoine", - "lastname": "Griezmann", - "age": 25 - }, - { - "_id": 3, - "firstname": "N'\''Golo", - "lastname": "Kanté", - "age": 29 - }, - { - "_id": 4, - "firstname": "Tanguy", - "lastname": "Ndombele", - "age": 24 - }, - { - "_id": 5, - "firstname": "Raphaël", - "lastname": "Varane", - "age": 10 - }, - { - "_id": 6, - "firstname": "Hugo", - "lastname": "Lloris", - "age": 41 - }, - { - "_id": 7, - "firstname": "Olivier", - "lastname": "Giroud", - "age": 36 - } - ] - } -}' - -``` - -- Search on Valid property - -```console -curl --location 'http://localhost:8181/v1/default_keyspace/collection_person' \ ---header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "find": { - "filter": { - "lastname": "Varane" - }, - "projection": { - "lastname": true, - "firstname": true - }, - "sort": {"lastname":-1} - } -}' -``` - -- Search on inValid property (exception expected) - -```console -curl --location 'http://localhost:8181/v1/default_keyspace/collection_person' \ ---header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "find": { - "filter": { - "age": 24 - }, - "projection": { - "lastname": true, - "firstname": true - }, - "sort": {"lastname":-1} - } -}' -``` - - -### Using Java client with Local Instance +To authenticate, use `cassandra` as the username and password to get a token. +Use `http://localhost:8181` as the endpoint. ```java public class QuickStartLocal { @@ -374,7 +143,7 @@ public class QuickStartLocal { .getDatabase(dataApiUrl) .getDatabaseAdmin()).createNamespace(keyspaceName, NamespaceOptions.simpleStrategy(1)); System.out.println("Keyspace created "); - + Database db = client.getDatabase("http://localhost:8181", "default_keyspace"); System.out.println("Connected to Database"); @@ -393,27 +162,23 @@ public class QuickStartLocal { } ``` -## 4. Running Integration tests - -### 4.1 ASTRA DB +### Running integration tests -#### Overview - -The clients can target a distribution of Data API installed locally or Astra DB. +The clients can target a distribution of Data API installed locally or Astra DB. In case of Astra DB they can also target different environments (DEV, TEST, PROD). When we run a test suite we can specify the target with the following properties: - | Property | Description | |---------------------------------|----------------------------------------------------------------------| | `ASTRA_DB_JAVA_TEST_ENV` | `astra_dev`, `astra_test` or `astra_prod` (default) | | `ASTRA_DB_APPLICATION_TOKEN` | the token to use for authentication leverage an env var like `${var}` | | `ASTRA_CLOUD_PROVIDER` | `AWS`, `GCP` or `AZURE` | -| `ASTRA_CLOUD_REGION` | A valid region is selected provider us-east-1, us-east-2 +| `ASTRA_CLOUD_REGION` | A valid region is selected provider us-east-1, us-east-2| -> [!INFOS] +> [!NOTE] > No database is required, the test suite will create and delete databases as needed. -> To Know a valid region for a provider you can use the `[Astra CLI]` +> To Know a valid region for a provider you can use the `[Astra CLI]` +> > ``` > $ astra db list-regions-vector > +-----------------+-------------------------+------------------------------------+ @@ -436,21 +201,25 @@ When we run a test suite we can specify the target with the following properties > +-----------------+-------------------------+------------------------------------+ > ``` -#### Pre-Requisites +#### Prerequisites for testing > [!IMPORTANT] -> - To run the maven command you need to have build the project first -> ``` -> mvn clean install -Dtest.skipped=true -> ``` -> - You also need to position yourself in folder `astra-db-java` -> ``` -> cd astra-db-java -> ``` - -#### Astra DB Admin - -- Test operation to create/delete databases we need to use an Organization Administrator token. +> +> - To run the maven command you need to build the project first: +> +> ``` +> mvn clean install -Dtest.skipped=true +> ``` +> +> - You also need to position yourself in folder `astra-db-java`: +> +> ``` +> cd astra-db-java +> ``` + +#### Astra DB Admin test + +Test operation to create/delete databases we need to use an Organization Administrator token. ``` mvn test \ @@ -462,7 +231,7 @@ mvn test \ -Dtest.skipped=false ``` -#### DatabaseAdmin +#### DatabaseAdmin test ``` mvn test \ @@ -474,8 +243,7 @@ mvn test \ -Dtest.skipped=false ``` - -#### Database +#### Database test ``` mvn test \ @@ -487,11 +255,7 @@ mvn test \ -Dtest.skipped=false ``` - -#### Collections - - -#### Multiple in one go +#### Running multiple tests ``` mvn test \ @@ -502,15 +266,3 @@ mvn test \ -DASTRA_CLOUD_REGION=us-east1 \ -Dtest.skipped=false ``` - -### 4.2 HCD - -Authenticate to serve - - - - - - - -