• Document

1. Overview¶

The Document API is an HTTP REST API and part of the open source Stargate.io. The idea is to provide an abstraction on top of Apache Cassandra™ to allow document-oriented access patterns.

A namespace (replacement for keyspace) will hold multiple collections (not tables) to store Documents
You interact with the database through JSON documents and no validation (sometimes called _schemaless_ but a better term would be validationless).
Each documents has a unique identifier within the collection. Each insert is an upsert.
You can query on any field (thanks to out of the box support for the secondary index SAI)

  graph LR
    DB(Database) -->|1...n|NS(Namespaces)
    NS -->|1..n|COL(Collections)
    COL -->|1..n|DOC(Documents)
    DOC -->|1..49 Nested docs|DOC

How is the data stored in Cassandra?

The JSON documents are stored using an internal data model. The table schema is generic as is each collection. The algorithm used to transform the document is called document shredding. The schema is optimized for searches but also to limit tombstones on edits and deletes.

create table <collection_name> (
  key       text,
  p0        text,
  ...
  p[N]       text,
  bool_value boolean,
  txt_value  text,
  dbl_value  double,
  leaf       text
)

A JSON like {"a": { "b": 1 }, "c": 2} will be stored like

key	p0	p1	dbl*value
{docid}	`a`	`b`	`1`
{docid}	`c`	_null*	`2`

This also works with arrays {"a": { "b": 1 }, "c": [{"d": 2}]}

key	p0	p1	p2	dbl_value
{docid}	`a`	`b`	null	`1`
{docid}	`c`	`[0]`	`d`	`2`

Known Limitations

As of today there is no aggregation or sorting available in the Document Api.
Queries are paged with a pagesize of 3 records by default and you can increase up to a maximum of 20 records. Otherwise, the payload would be too large.

2. Prerequesites¶

You should have an Astra account
You should Create an Astra Database
You should Have an Astra Token

3. Browse Api with Swagger¶

3.1 Provide Database Details¶

Astra DB Setup Authentication token ^*

Database identifier ^* (Where find it ?)

Database Region ^* (Where find it ?)

3.2 Use Swagger¶

The swagger client below will have fields pre-populated with your database details.

4. Browse Api with Postman¶

4.1 Installation¶

Install Postman to import the sample collections that we have provided.
You can also import the collection in Hoppscotch.io not to install anything.

Postman Collection

4.2 Postman Setup¶

Import the configuration File Astra_Document_Api_Configuration.json in postman. In the menu locate File > Import and drag the file in the box.

Postman Configuration

Edit the values for your db:

Parameter Name	parameter value	Description
token	`AstraCS:....`	When you generate a new token it is the third field. Make sure you add enough privileges to use the APis, Database Administrator is a good choice to develop
db	`00000000-0000-0000-0000-00000000000`	Unique identifier of your DB, you find on the main dashboard
region	`us-east1`	region name, you find on the datanase dashboard
namespace	`demo`	Namespaces are the same as keyspaces. They are created with the database or added from the database dashboard: How to create a keyspace]
collection	`person`	Collection name (like table) to store one type of documents.

this is what it is looks like

Import the Document Api Collection Astra_Document_Api.json in postman. Same as before File > Menu

That's it! You have now access to a few dozens operations for namespace, collections and documents

4.3 Working with the Postman Workspace¶

Alternatively, you can access the collections for Document API in the Postman workspace below.

5. Api Sandbox with Curl¶

Provide the parameters asked at the beginning and see a first set of commands in action.

6. Extra Resources¶

Reference Documentation

Last update: 2022-10-28