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.
astra-db-tsis the equivalent for typescriptastrapyis the equivalent in python
This library is under development and is available in Maven Central. You can build it locally and install it in your local repository.
- Use the reference documentation to install a Java Development Kit
- Validate your installation with
java --version- Use the reference documentation to install Apache Maven
- Validate your installation with
mvn -versionDocker 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.
- Clone the repository
git clone git@github.com:datastax/astra-db-java.git- 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:
- An environment variable
ASTRA_DB_APPLICATION_TOKENwith your an Organization Administrator Astra token (PROD)- An environment variable
ASTRA_DB_APPLICATION_TOKEN_DEVwith your an Organization Administrator Astra token (DEV)- A running Data API locally with docker (see the
docker-compose.ymlin the root of the project)
mvn clean install -Dtest.skipped=true- Access https://astra.datastax.com and register with
GoogleorGithubaccount. It is free to use. There is free forever tiers of up to 25$ of consumption every month.
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.
- ℹ️ 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.
It should take a couple of minutes for your database to become Active.
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://<db-id>-<db-region>.apps.astra.datastax.com).
To get a token click the [Generate Token] button on the right. It will generate a token that you can copy to your clipboard.
Add the following dependency to your pom.xml file:
<dependency>
<groupId>com.datastax.astra</groupId>
<artifactId>astra-db-java</artifactId>
<version>1.3.0</version>
</dependency>Here is a sample class that demonstrates how to use the library:
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<Document> 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<Document> 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);
}
}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.
- Clone the repository
git clone git@github.com:stargate/data-api.git
- Access the folder and start the data API. Note that we position cassandra endpoint to
localhostand datacenter todc1.
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
- To check the Data API is running
| Field | Description |
|---|---|
| Data API Spec | http://localhost:8181/swagger-ui/#/ |
| Data API Endpoint | http://localhost:8181 |
| Token Header Key | Token |
| 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
| Field | Url | Description |
|---|---|---|
| Namespace | /v1/ |
Interact with namespaces (not available in Astra) |
| 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
curl --location 'http://localhost:8181//v1' \
--header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \
--header 'Content-Type: application/json' \
--data '{"createKeyspace":{"name":"default_keyspace"}}'- Create a collection
personwith CURL (indexing)
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
curl --location 'http://localhost:8181//v1/default_keyspace' \
--header 'token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \
--header 'Content-Type: application/json' \
--data '{
"findCollections": {}
}'- Inserts a few documents
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
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)
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}
}
}'public class QuickStartLocal {
public static void main(String[] args) {
// Create a token
String token = new UsernamePasswordTokenProvider("cassandra", "cassandra").getToken();
System.out.println("Token: " + token);
// Initialize the client
DataAPIClient client = new DataAPIClient(token, builder().withDestination(CASSANDRA).build());
System.out.println("Connected to Data API");
// Create a default keyspace
((DataAPIDatabaseAdmin) client
.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");
// Create a collection. The default similarity metric is cosine.
Collection<Document> collection = db.createCollection("simple", 5, COSINE);
System.out.println("Created a Collection simple");
// Create a collection with Vector embeddings OPEN AI
Collection<Document> collectionLyrics = db.createCollection("vector", CollectionOptions.builder()
.vectorSimilarity(SimilarityMetric.COSINE)
.vectorDimension(1536)
.vectorize("openai", "text-embedding-3-small")
.build(),
new CommandOptions<>().embeddingAPIKey("sk-....."));
}
}This is an the organization of the different classes of the framework.
-
For more information use the JAVADOC documentation
-
The
examplesdirectory contains more examples on how to use the library.