{"id":19704687,"url":"https://github.com/datastax/astra-db-java","last_synced_at":"2025-04-29T14:31:44.610Z","repository":{"id":229094040,"uuid":"775535209","full_name":"datastax/astra-db-java","owner":"datastax","description":"Java Client for DataStax Astra DB and the Data API","archived":false,"fork":false,"pushed_at":"2025-04-11T11:32:06.000Z","size":5280,"stargazers_count":11,"open_issues_count":2,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-26T03:45:44.584Z","etag":null,"topics":["api","client","sdk"],"latest_commit_sha":null,"homepage":"https://datastaxdevs.github.io/astra-db-java/latest/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datastax.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-21T15:13:11.000Z","updated_at":"2025-04-11T11:29:17.000Z","dependencies_parsed_at":"2024-04-11T08:46:32.229Z","dependency_job_id":"7e7fce8a-21dc-475c-b321-eb54ff6e4349","html_url":"https://github.com/datastax/astra-db-java","commit_stats":null,"previous_names":["datastax/astra-db-java"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fastra-db-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fastra-db-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fastra-db-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fastra-db-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastax","download_url":"https://codeload.github.com/datastax/astra-db-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251519190,"owners_count":21602296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","sdk"],"created_at":"2024-11-11T21:24:03.863Z","updated_at":"2025-04-29T14:31:39.593Z","avatar_url":"https://github.com/datastax.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Java Client for Data API\n\n[![License Apache2](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n[![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)\n\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=clun_db-java)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=clun_astra-db-java)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=clun_astra-db-java)\n\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=clun_astra-db-java)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/overall?id=clun_astra-db-java)\n[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=clun_astra-db-java)\n\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=ncloc)](https://sonarcloud.io/summary/new_code?id=clun_astra-db-java)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=clun_astra-db-java\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=clun_astra-db-java)\n\n\nThis 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.\n\n- [`astra-db-ts`](https://github.com/datastax/astra-db-ts) is the equivalent for typescript\n- [`astrapy`](https://github.com/datastax/astrapy) is the equivalent in python\n\nThis library is under development and is available in Maven Central.\nYou can build it locally and install it in your local repository.\n\n## 📋 Table Of Content\n\n1. [Installation](#1-installation)\n   1. [Prerequisites](#11-prerequisites)\n   2. [Packaging](#12-packaging)\n2. [QuickStart with Astra DB](#2-quickstart-with-astra-db)\n   1. [Sign up for Astra DB](#21-sign-up-for-astra-db)\n   2. [Create a Database](#22-create-a-database)\n   3. [Get your credentials](#23-get-your-credentials)\n   4. [Create a new project and add the dependency](#24-create-a-new-project-and-add-the-dependency)\n3. [QuickStart with Local Instances]()\n    1. [Start Data Api with DSE](#31-start-data-api-with-dse)\n    2. [Start Data Api with HCD](#32-start-data-api-with-hcd)\n    3. [Datq Api Information](#33-datq-api-information) \n    4. [Using Java client with Local Instance](#34-using-java-client-with-local-instance) \n4. [What's Next](#4-whats-next)\n\n   \n## 1. Installation\n\n### 1.1 Prerequisites\n\n#### 📦 Java Development Kit (JDK) 11\n- Use the [reference documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html) to install a **Java Development Kit**\n- Validate your installation with\n\n```bash\njava --version\n```\n\n#### 📦 Apache Maven\n- Use the [reference documentation](https://maven.apache.org/install.html) to install **Apache Maven**\n- Validate your installation with\n\n```bash\nmvn -version\n```\n\n#### 📦 Docker (local Installation)\n\nDocker 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.\n\n### 1.2 Packaging\n\n- Clone the repository\n\n```console\ngit clone git@github.com:datastax/astra-db-java.git\n```\n\n- Build the project (java 11 and Maven is required)\n\n\u003e 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:\n\u003e - An environment variable `ASTRA_DB_APPLICATION_TOKEN` with your an Organization Administrator Astra token (PROD)\n\u003e - An environment variable `ASTRA_DB_APPLICATION_TOKEN_DEV` with your an Organization Administrator Astra token (DEV)\n\u003e - A running Data API locally with docker (see the `docker-compose.yml` in the root of the project)\n\n```console\nmvn clean install -Dtest.skipped=true\n```\n\n## 2. QuickStart with Astra DB\n\n### 2.1. Sign up for Astra DB\n\n- 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.\n\n![](https://awesome-astra.github.io/docs/img/astra/astra-signin-github-0.png)\n\n### 2.2. Create a Database\n\n\u003e If you are creating a new account, you will be brought to the DB-creation form directly.\n\n- 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.\n\n![](https://datastaxdevs.github.io/langchain4j/langchain4j-1.png)\n\n- **ℹ️ Fields Description**\n\n| Field                                      | Description                                                                                                                                                                                                                                   |\n|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Vector Database vs Serverless Database** | Choose `Vector Database` In june 2023, Cassandra introduced the support of vector search to enable Generative AI use cases.                                                                                                                   |\n| **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. |\n| **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.            |\n| **Cloud Region**                           | Pick region close to you available for selected cloud provider and your plan.                                                                                                                                                                 |\n\nIf all fields are filled properly, clicking the \"Create Database\" button will start the process.\n\n![](https://datastaxdevs.github.io/langchain4j/langchain4j-2.png)\n\nIt should take a couple of minutes for your database to become `Active`.\n\n![](https://datastaxdevs.github.io/langchain4j/langchain4j-3.png)\n\n### 2.3. Get your credentials\n\nTo 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://\u003cdb-id\u003e-\u003cdb-region\u003e.apps.astra.datastax.com`).\n\n![](https://datastaxdevs.github.io/langchain4j/langchain4j-4.png)\n\nTo get a token click the `[Generate Token]` button on the right. It will generate a token that you can copy to your clipboard.\n\n### 2.4 Create a new project and add the dependency\n\nAdd the following dependency to your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.datastax.astra\u003c/groupId\u003e\n  \u003cartifactId\u003eastra-db-java\u003c/artifactId\u003e\n  \u003cversion\u003e1.3.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nHere is a sample class that demonstrates how to use the library:\n\n```java\nimport com.datastax.astra.client.DataAPIClient;\nimport com.datastax.astra.client.collections.Collection;\nimport com.datastax.astra.client.databases.Database;\nimport com.datastax.astra.client.collections.documents.Document;\nimport com.datastax.astra.client.core.paging.FindIterable;\n\nimport java.util.List;\n\nimport static com.datastax.astra.client.core.query.Filters.eq;\nimport static com.datastax.astra.client.core.vector.SimilarityMetric.cosine;\n\npublic class GettingStarted {\n   public static void main(String[] args) {\n      // Initializing client with a token\n      DataAPIClient client = new DataAPIClient(\"my_token\");\n\n      // Accessing the Database through the HTTP endpoint\n      Database db = client.getDatabase(\"http://db-region.apps.astra.datastax.com\");\n\n      // Create collection with vector support\n      Collection\u003cDocument\u003e col = db.createCollection(\"demo\", 2, cosine);\n\n      // Insert records\n      col.insertMany(List.of(\n              new Document(\"doc1\").vector(new float[]{.1f, 0.2f}).append(\"key\", \"value1\"),\n              new Document().id(\"doc2\").vector(new float[]{.2f, 0.4f}).append(\"hello\", \"world\"),\n              new Document(\"doc3\").vector(new float[]{.5f, 0.6f}).append(\"key\", \"value1\"))\n      );\n\n      // Search\n      FindIterable\u003cDocument\u003e docs = col.find(\n              eq(\"key\", \"value1\"), // metadata filter\n              new float[]{.5f, .5f},              //vector\n              10);                                 // maxRecord\n\n      // Iterate and print your results\n      for (Document doc : docs) System.out.println(doc);\n   }\n}\n```\n\n## 3. QuickStart with Local Instances\n\n### 3.1. Start Data Api with DSE\n\n- Start the 2 containers with the following command:\n\n```console\ndocker-compose up -d\n```\n\n### 3.2. Start Data Api with HCD\n\n```\ndocker-compose -f docker-compose-hcd.yml up -d\n```\n\n- Check the status of the containers with the following command:\n\n```console\ndocker-compose ps\n```\n\n### 3.3. Datq Api Information\n\n\u003e _Output_\n\u003e ```console\n\u003e NAME                          IMAGE                                           COMMAND                \n\u003e astra-db-java-coordinator-1   stargateio/coordinator-dse-next:v2.1.0-BETA-9   \"./starctl\"             \n\u003e astra-db-java-jsonapi-1       stargateio/jsonapi:v1.0.6         \n\u003e ```\n\n- Here are the information to connect to the local instance:\n\n| Field                                      | Description                                                                             |\n|--------------------------------------------|-----------------------------------------------------------------------------------------|\n| **Data API Spec**                          | http://localhost:8181/swagger-ui/#/                                                     |\n| **Data API Endpoint**                      | http://localhost:8181                                                                   |\n| **Token Header Key**                       | `Token`                                                                                      |\n| **Token Header Value**               | `Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh` (aka `Cassandra:Base64(userName):Base64(password)`) |\n| **Authentication API Spec (before 1.0.6)** | http://localhost:8081/swagger-ui/#/                                                     |\n\n- The API will have 3 resources\n\n| Field                 | Url                            | Description                                       |\n|-----------------------|--------------------------------|---------------------------------------------------|\n| **Namespace**         | `/v1/`                         | Interact with namespaces (not available in Astra) |\n| **Data API Endpoint** | `/v1/{namespace}`              | Interact with collections of a namespace |\n| **Token Header Key**  | `/v1/{namespace}/{collection}` |Interact with documents of a collection  |\n\n- Sample curl to create a namespace:\n\n```console\ncurl -X 'POST' \\\n  'http://localhost:8181/v1' \\\n  -H 'accept: application/json' \\\n  -H 'Token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"createNamespace\": {\n    \"name\": \"default_keyspace\"\n  }\n}'\n```\n\n### 3.4. Using Java client with Local Instance\n\n```java\npublic class QuickStartLocal {\n\n    public static void main(String[] args) {\n\n        // Create a token\n        String token = new UsernamePasswordTokenProvider(\"cassandra\", \"cassandra\").getToken();\n        System.out.println(\"Token: \" + token);\n\n        // Initialize the client\n        DataAPIClient client = new DataAPIClient(token, builder().withDestination(CASSANDRA).build());\n        System.out.println(\"Connected to Data API\");\n\n       // Create a default keyspace\n       ((DataAPIDatabaseAdmin) client\n               .getDatabase(dataApiUrl)\n               .getDatabaseAdmin()).createNamespace(keyspaceName, NamespaceOptions.simpleStrategy(1));\n        System.out.println(\"Keyspace created \");\n       \n        Database db = client.getDatabase(\"http://localhost:8181\", \"default_keyspace\");\n        System.out.println(\"Connected to Database\");\n\n        // Create a collection. The default similarity metric is cosine.\n        Collection\u003cDocument\u003e collection = db.createCollection(\"simple\", 5, COSINE);\n        System.out.println(\"Created a Collection simple\");\n\n       // Create a collection with Vector embeddings OPEN AI\n       Collection\u003cDocument\u003e collectionLyrics =  db.createCollection(\"vector\", CollectionOptions.builder()\n                       .vectorSimilarity(SimilarityMetric.COSINE)\n                       .vectorDimension(1536)\n                       .vectorize(\"openai\", \"text-embedding-3-small\")\n                       .build(),\n               new CommandOptions\u003c\u003e().embeddingAPIKey(\"sk-.....\"));\n    }\n}\n```\n\n## 4. What's Next\n\nThis is an the organization of the different classes of the framework.\n\n![overview](https://datastaxdevs.github.io/astra-db-java/overview.png)\n\n- For more information use the [JAVADOC  documentation](https://datastaxdevs.github.io/astra-db-java/latest/)\n\n- The `examples` directory contains more examples on how to use the library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fastra-db-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastax%2Fastra-db-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fastra-db-java/lists"}