Repository navigation
Home
The SDK makes it easy to call Astra services using idiomatic Java APIs. On top of the SDK the repository provide tool like a Spring Boot starter and another samples helping you starting code with ASTRA and JAVA.

How do you want to connect?
| Options | Description |
|---|---|
| I don't want to create a schema. Just let me get started. | Use schemaless JSON Documents with the Document API |
| I want to start using my database now with APIs. | Use the REST API or GraphQL API to begin interacting with your database. |
| I have an application and want to use the DataStax drivers. | Use the CQL API leveraging DataStax drivers to manage database connections for your application. |
| I want to operate Astra, work with my instances. | Use the Devops API |
For any choice you will see that you only need to setup the class AstraClient with a builder and you are good to go.
The SDK has been build with the HttpClient provided in JDK. A You need JDK 11.0.9+ and a dependency management too as Maven or Gradle
It is a single library providing support for the 5 API(s) listed above.
Maven dependency in pom.xml
<dependency>
<groupId>com.datastax.astra</groupId>
<artifactId>astra-sdk-java</artifactId>
<version>${2021.1}</version>
</dependency>Gradle dependency in build.gradle
dependencies {
astra_sdk 'com.datastax.astra:astra-sdk-java:2021.1'
}You can use the class AstraClient to access any API (document, rest, cql, graphql, devops) . Not all parameters are needed, it depends on which API you want to use and if connection is created agains Astra or Stargate. With an important number of parameters a builder is provided.
Values are initialised with environment variables (if exist) full list here but you can define parameters programmatically as we do in the code snippet. Constants provided comply with expected format but are faked values. To locate values in the Astra user interface you can refer to this explanation.
Final word, we use object Person as our entity
AstraClient astraClient = AstraClient
.builder()
.astraDatabaseId("1111111-1111-1111-1111-111111111111") // Use in Rest,Doc,Devops,Cql APIs
.astraDatabaseRegion("europe-west1") // Use in Rest,Doc,Devops,Cql APIs
.username("astraUser") // Use in Rest,Doc,Cql APIs
.password("astraPassword") // Use in Rest,Doc,Cql APIs
.clientId("2222222-2222-2222-2222-22222222222") // Use in Devops only API
.clientName("cedric.lunven@datastax.com") // Use in Devops only API
.clientSecret("3333333-3333-3333-3333-333333333333") // Use in Devops only API
.build();
// DOCUMENT API
ApiDocumentClient apiDocClient = astraClient.apiDocument();
// DOC1. Create Namespace
if (!apiDocClient.namespace("five_min_namespace").exist()) {
// apiDocClient.namespace("five_min_namespace").create();
// We use the devops API with higher privileges
astraClient.apiDevops()
.createNamespace("1111111-1111-1111-1111-111111111111", "five_min_namespace");
}
// DOC2. Create a collection
if (!apiDocClient.namespace("five_min_namespace").collection("person").exist()) {
apiDocClient.namespace("five_min_namespace")
.collection("person")
.create();
}
// DOC3. Create a document Insert a Person and system generates id
String johnId = apiDocClient.namespace("five_min_namespace")
.collection("person")
.save(new Person("John", "Doe", 20, new Address("Paris", 75000)));
// DOC4. Upsert a document by providing id
apiDocClient.namespace("five_min_namespace")
.collection("person")
.document("saradoe")
.save(new Person("Sara", "Doe", 20, new Address("Paris", 75000)));
// DOC5. Find all (notice that everything is paged)
ResultListPage<Person> results = apiDocClient
.namespace("five_min_namespace")
.collection("person")
.findAll(Person.class);
// DOC6. Search: Find with a where Clause
ResultListPage<Person> results = collectionPerson.search(QueryDocument.builder()
.where("lastname").isEqualsTo("Doe").build(), Person.class);
// Devops API
ApiDevopsClient apiDevops = astraClient.apiDevops();
apiDevops.databases();
Optional<AstraDatabaseInfos > dbInfos = apiDevops.findDatabaseById("1111111-1111-1111-1111-111111111111");
// Rest API
ApiRestClient apiRest = astraClient.apiRest();
// Cql API (Drivers)
ApiCqlClient apiCql = astraClient.apiCql();Astra use the open source data gateway Stargate to expose REST, Document and GraphQL APIs, design is done to work with both. Depending on which API we want to use and if we use Astra or Stargate required parameters are not the same.
Parameters required in Astra for each API

Parameters required in Stargate for each API

Philosophy of the SDK is either to use AstraClientand fill the parameters you need to work with the API you need or instanciate the sub client you need.

Illustration to use either AstraClient facade or sub clients.
// Use AstraClient
AstraClient astraClient = AstraClient.builder()
.astraDatabaseId(dbId)
.astraDatabaseRegion(dbRegion)
.username(dbUser)
.password(dbPasswd)
.build();
ApiDocumentClient apiDocClient1 = astraClient.apiDocument();
// Create subclient direct
ApiDocumentClient apiDocClient2 =
new ApiDocumentClient(dbId, dbRegion, dbUser, dbPasswd);🖥️ Expected Output:
- Initializing Client: BaseUrl=https://e92195f2-159f-492e-9777-3dadda3ff1a3-europe-west1.apps.astra.datastax.com/api/rest, username=todouser,passwordLenght=13
- Successfully Authenticated, token will live for 300 second(s).
📘 astraDatabaseId: It is the default identifier of a database hosted in Astra.
- Used only when working with Astra
- Mandatory to work with Doc, Rest or GraphQL APIS.
- Environment Variable lookup for initial value
ASTRA_DB_ID - Sample Use
AstraClient.builder().astraDatabaseId("1111111-1111-1111-1111-111111111111");- Property found on the summary page
📘 astraDatabaseRegion: It is the default identifier of a database hosted in Astra
- Used only when working with Astra
- Mandatory to work with Doc, Rest or GraphQL APIS.
- Environment Variable lookup for initial value
ASTRA_DB_REGION - Sample Use
AstraClient.builder().astraDatabaseRegion("europe-west-1");- Property found on the summary page
📘 baseUrl: It is the endpoint for Apis when working with Stargate
- Used only when working with Stargate
- Mandatory to work with Doc, Rest or GraphQL APIS.
- Environment Variable lookup for initial value
STARGATE_BASE_URL - Sample Use
AstraClient.builder().baseUrl("http://localhost:8082/api");!If you provide `baseUrl` but also `astraDatabaseId` and `astraDatabaseId` the client will use `baseUrl`.📘 username: It is the... username
- Used both for Stargate and Astra
- Mandatory to work with Doc, Rest or GraphQL APIS.
- Environment Variable lookup for initial value
STARGATE_USERNAME, then if not found,ASTRA_DB_USERNAME - Sample Use
AstraClient.builder().username("astraUser");📘 password: It is the... password
- Used both for Stargate and Astra
- Mandatory to work with Doc, Rest or GraphQL APIS.
- Environment Variable lookup for initial value
STARGATE_PASSWORDthen, if not found,ASTRA_DB_PASSWORD - Sample Use
AstraClient.builder().username("astraUser");📘 clientId: is part of a service Account and stands as an unique identifier for the client.
- Used only when working with Astra
- Mandatory to work with Devops API.
- Environment Variable lookup for initial value
ASTRA_CLIENT_ID - Sample Use
AstraClient.builder().clientId("1111111-1111-1111-11111111111");- Property found on the Security Account page, use the ellipsis to copy the JSON.
📘 clientName: is part of a service Account and stands as client email.
- Used only when working with Astra
- Mandatory to work with Devops API.
- Environment Variable lookup for initial value
ASTRA_CLIENT_NAME - Sample Use
AstraClient.builder().clientName("cedrick@datastax.com");📘 clientSecret: is part of a service Account and is used as a key to authenticate.
- Used only when working with Astra
- Mandatory to work with Devops API.
- Environment Variable lookup for initial value
ASTRA_CLIENT_SECRET - Sample Use
AstraClient.builder().clientSecret("1111111-1111-1111-11111111111");📘 contactPoints: is used to work with Drivers (cql API)
- Used only when working with Stargate
- Mandatory to work with Driver API.
- Environment Variable lookup for initial value
CONTACT_POINTS - Sample Use
AstraClient.builder().addContactPoint("127.0.0.1", 9042);📘 driverConfigFile: is used to work with Drivers (cql API)
- Used both for Stargate and Astra
- Mandatory to work with Driver API.
- Environment Variable lookup for initial value
DRIVER_CONFIG_FILE - Sample Use
AstraClient.builder().driverConfigFile("/tmp/application.conf");📘 secureConnectBundle: is used to work with Drivers (cql API). NOt that this file can be downloaded with the DevopsAPI.
- Used only when working with Astra
- Mandatory to work with Driver API.
- Environment Variable lookup for initial value
ASTRA_SECURE_BUNDLE - Sample Use
AstraClient.builder().secureConnectBundle("/tmp/mybundle.zip");🏠 Home | Document | Rest | Native Drivers | GraphQL | gRPC | Astra Devops |