Skip to content

• Document

1. Overview

The Document API is an HTTP REST API and part of the open source 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

3. Browse Api with Swagger

3.1 Provide Database Details

Astra DB Setup

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

Last update: 2022-10-28