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.

Initialisation

AstraClient and Stargate initializations have been detailed on the Home page. Moving forward the sample code will reuse those classes but do not initialized them.

📘 Accessing ApiDocumentClient

// Option1. Given an astraClient
ApiDocumentClient client1 = astraClient.apiStargateDocument();
ApiDocumentClient client2 = client.getStargateClient().apiDocument()

// Option 2. Given a StargateClient
ApiDocumentClient client3 = stargateClient.apiDocument();

// Option 3. Constructors
ApiDocumentClient client4_Astra    = new ApiDocumentClient("http://api_endpoint", "apiToken");
ApiDocumentClient client5_Stargate = new ApiDocumentClient("http://api_endpoint", 
  new TokenProviderDefault("username", "password", "http://auth_endpoint");

From now, in another samples, we will use the variable name apiDocClient to define ApiDocumentClient

Working with namespaces

This class is the main unit test for this API and could be use as reference code

✅ Lists available Namespaces Names

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

✅ Lists available Namespaces

Related endpoint documentation can be found here

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

✅ Find namespace by its id

Related endpoint documentation can be found here

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

✅ Test if namespace exists

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

✅ Create a new namespace

🚨 As of Today, the Namespace and Keyspace creations in ASTRA are available only at the DevOps API level.

// Create a namespace with a single DC dc-1
DataCenter dc1 = new DataCenter("dc-1", 1);
apiDocClient.namespace("ns1").create(dc1);

// Create a namespace providing only the replication factor
apiDocClient.namespace("ns1").createSimple(3);

✅ Delete a namespace

🚨 As of today the namespace / keyspace creations are not available in ASTRA

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

ℹ️ Tips

You can simplify 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

The related Api Documentation is available here

✅ Lists available Collection in namespace

// We can create a local variable to shorten the code.
NamespaceClient ns1 = apiDocClient.namespace("ns1");
Stream<String> colNames = ns1.collectionNames();

✅ Check if collection exists

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

✅ Create an empty collection

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

✅ Delete a collection

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

ℹ️ 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

To work with documents you need a CollectionClient that you can retrieve with :

CollectionClient collectionPerson = apiDocClient.namespace("ns1").collection("col1")

✅ Get a document by id

boolean docExist = collectionPerson.document("doc1").exist();
Optional<Person> p = collectionPerson.document("doc1").find(Person.class);

✅ Create a new document with no id

Person john = new Person("John", "Doe", 20, new Address("Paris", 75000));
String docId =  collectionPerson.createNewDocument(john);

✅ Upsert a document enforcing the id

Person john2 = new Person("John", "Doe", 20, new Address("Paris", 75000));
String docId = collectionPerson.document("myId").upsert(john2, Person.class);

✅ Delete a Document

collectionPerson.document("myId").delete();

✅ Find all Documents

All requests are paged.

collectionPerson.findAll()

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