Document API

Before Starting

Astra and Stargate bring great innovation by allowing Apache Cassandra to store Documents like a document-oriented noSQL database. To cope with Cassandra data model constraints the document shredding function has been used.

As a Java developer you want to work with objects (entities) and let the SDK interact with the API performing operations you need Create, Read, Update, Delete and search.

Client Initialisation

The class to work with document API is ApiDocumentClient. You can create it in the following ways:

📘 With AstraClient

ApiDocumentClient apiDocClientAstra1 = AstraClient.builder()
 .astraDatabaseId("dbId").astraDatabaseRegion("dbRegion")
 .username("dbUser")
 .password("dbPasswd")
 .build().apiDocument();

ApiDocumentClient apiDocClientStargate1 = AstraClient.builder()
 .baseUrl("url")
 .username("dbUser")
 .password("dbPasswd")
 .build().apiDocument();

📘 With constructor

ApiDocumentClient apiDocClientAstra2 = 
    new ApiDocumentClient(dbId, dbRegion, username, password);

ApiDocumentClient apiDocClientStargate2 = 
    new ApiDocumentClient(baseUrl, username, password);

From now in other sample we will use variable apiDocClient.

You can use this class as reference for the code.

Working with namespaces

✅ Lists available Namespaces Api documentation

Stream<Namespace> namespaces = apiDocClient.namespaces();

✅ Find namespace by its id API documentation

Optional<Namespace> ns1 = apiDocClient..namespace("ns1").find();

✅ Check namespace exists

apiDocClient.namespace("ns1").exist();

✅ Create a new namespace Api documentation

DataCenter dc1 = new DataCenter("dc-1", 1);
apiDocClient.namespace("ns1").create(dc1);

This operation required elevated privilege in Astra but works in Stargate. To create a namespace in Astra you can also use the DevopsAPI.

✅ Delete a namespace Api Documentation Api

apiDocClient.namespace("ns1").delete();

This operation required elevated privilege in Astra but works in Stargate. To delete a namespace in Astra you can also use the DevopsAPI.

ℹ️ Tips

You can simply the code by assigning apiDocClient.namespace("ns1") to a variable;

NamespaceClient nsClient = apiDocClient.namespace("ns1");
nsClient.exist();
nsClient.delete();
nsClient.find();
//...

Working with Collections

✅ Lists available Collection in namespace Api documentation

Stream<String> colNames = apiDocClient.namespace("ns1").collectionNames();

✅ Check if collection exists Api documentation

boolean colExist = apiDocClient.namespace("ns1").collection("col1").exist();

✅ Create an empty collection Api documentation

apiDocClient.namespace("ns1").collection("col1").create();

✅ Delete a collection Api documentation

apiDocClient.namespace("ns1").collection("col1").delete();

✅ Upgrade a collection

apiDocClient.namespace("ns1").collection("col1").upgrade();

ℹ️ Tips

You can simply the code by assigning apiDocClient.namespace("ns1").collection("col1") to a variable;

NamespaceClient nsClient   = apiDocClient.namespace("ns1");
CollectionClient colClient = nsClient.collection("col1");
colClient.exist();
//...

Working with Documents

✅ Get a document by id Api documentation

Optional<Person> p = apiDocClient
 .namespace("ns1")
 .collection("col1")
 .document("doc1")
 .find(Person.class);

boolean docExist = apiDocClient
   .namespace("ns1")
   .collection("col1")
   .document("doc1")
   .exist();

✅ Create a new document with no id Api documentation

Person john = new Person("John", "Doe", 20, new Address("Paris", 75000));
String docId =  apiDocClient
 .namespace("ns1")
 .collection("col1")
.save(john, Person.class);

✅ Upsert a document enforcing no id Api documentation

Person john = new Person("John", "Doe", 20, new Address("Paris", 75000));
String docId = apiDocClient
 .namespace("ns1")
 .collection("col1")
 .document("myId")
 .save(john, Person.class);

✅ Delete a Document

✅ Find all Documents

✅ Find document with where clause

✅ Find part of a documents

// Retrieve a Scalar field
Optional<String> firstName = apiDocClient.namespace("ns1")
  .collection("col1")
  .document("myId")
  .findSubDocument("firstname", String.class);

// Retrieve a list        
System.out.println("Countries= "+ apiDocClient.namespace("ns1")
  .collection("col1")
  .document("myId")
  .findSubDocument("countries", List.class)
  .get());

// Retrieve an Object
System.out.println("Address/City = "+ apiDocClient.namespace("ns1")
  .collection("col1")
  .document("myId")
  .findSubDocument("address", Address.class)
  .get());
        
// Retrieve a scalar with depth=2
System.out.println("Address/City = "+ apiDocClient.namespace("ns1")
  .collection("col1")
  .document("myId")
  .findSubDocument("address/zipcode", Integer.class)
  .get());

✅ Update part of a documents

 apiDocClient.namespace("ns1")
        .collection("col1")
        .document("myId")
        .updateSubDocument("address", new Address("city2", 8000));

✅ Delete part of a documents

 apiDocClient.namespace("ns1")
        .collection("col1")
        .document("myId")
        .deleteSubDocument("address");