Document API

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. It is available in both AstraClient and StargateClient. To remember how to initialize those check the Configuration chapter.

📘 Initialize with AstraClient

// Given an astraClient
ApiDocumentClient apiDocClientAstra1 = astraClient.apiStargateDocument();

📘 Initialize with StargateClient

// Given an stargateClient
ApiDocumentClient apiDocClientStargate1 = stargateClient.apiDocument();

📘 Initialize with constructor

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

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

From now in another sample, we will use the variable apiDocClient.

You can use this class as a reference for the code.

Working with namespaces

**✅ Lists available Namespaces Names **

Stream<String> namespaces = apiDocClient.namespaceNames();

✅ 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

🚨 As of Today the Namespace/keyspace creations in ASTRA are available only at the DevOps API level.

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

✅ Delete a namespace Api Documentation Api

🚨 As of Today the Namespace/keyspace creations in ASTRA are available only at the DevOps API level.

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

ℹ️ Tip

You can simply the code by assigning apiDocClient.namespace("ns1") to a NamespaceClient variable as shown below:

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");