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.

Initialization

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.

📘 (a) 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

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

✅ Lists available Namespaces Names

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

✅ Lists available Namespaces

You can find the original API endpoint documentation at this URL

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

To work with document you need a CollectionClient that you can easily retrieve with

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

✅ Get a document by id Api documentation

boolean docExist = collectionPerson.document("doc1").exist();

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

✅ Create a new document with no id Api documentation

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

✅ Upsert a document enforcing the id Api documentation

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