Create and Use a Document Database with Stargate Document API and Astra DB in 15 Minutes

This is the third post in our series on how to use Stargate APIs. With our Katacoda scenario and 15 minutes, you can learn how to use the Stargate Document API to use Astra DB like a document database and perform CRUD operations against it.

Document databases offer a lot of benefits. They offer a very flexible schema with few restrictions in terms of format and data structure. And, because they’re built around JSON-like documents, document model databases are quite flexible and feel very natural for developers to work with.

Document databases have a hierarchical structure, which consists of namespaces, which are analogous to keyspaces in Cassandra. Namespaces contain collections, and these collections contain JSON documents. Unlike a key-value database where the data is only identifiable by its key (the values are opaque), with a document API, you’re able to navigate and understand the contents of JSON documents within a document database.

Figure 1: Hierarchical structure of a document database.

If you use Apache Cassandra, you may already know that it isn’t very easy to use it for document use cases like flexible schema and querying by non-partition keys. However, now we have Stargate and its Document API, which allows you to use DataStax Enterprise (DSE), DataStax Astra DB, or Apache Cassandra® as a document database.

The Stargate Document API offers a JSON document model interface, meaning that it is a document database that associates keys with JSON documents. Documents API allows for data ingestion on the fly regardless of structure. The only requirement is that the data be valid JSON. With the Document API, you can create collections, add documents, and modify them directly within your database. And, we’ll show you how to do that in Astra DB with our Katacoda tutorial.

In as little as 15 minutes and with any browser, you’ll learn how to use the Document API to:

  • Create a new collection and add a document
  • Read the document back from the database
  • Read a subdocument from the database
  • Update a document
  • Replace a subdocument
  • Delete a document from the database

All you need for this scenario is a free Astra DB account.

The advantages of using the Document API

Stargate is an open-source framework that provides an abstraction layer between client applications and a Cassandra database to allow developers to customize access to data in the database to fit their application’s needs.

The Document API is one of three powerful APIs available in Stargate that provides for this customization. Like the Stargate REST API and the Stargate GraphQL API, the Stargate Document API is designed for Cassandra databases and can also be used with DSE and Astra DB.

One of the biggest benefits of using the Document API is that it allows developers to store JSON objects in Astra DB without a bunch of upfront modeling and to easily prototype without having to pre-define schema and queries. There’s a lot of power under the hood of this API even for the beginner developer. For example, you can interact with data stored in collections with familiar HTTP methods (GET/PUT/POST/DELETE) to work directly with your JSON documents, without having to learn a new database query language.

These benefits extend to Cassandra and DSE, too. However, in our scenario, we focus on Astra DB because it comes with the Document API already built-in and enabled, making it easy to take the API for a test drive to see what it can do. If you don’t already have an Astra DB to work with, you can create a new one here for free.

How to use the Stargate Document API

If you want to use the Document API with a self-hosted Cassandra cluster or DSE, you’ll need to install it. You can see how to do this in the Document API QuickStart guide. With the Document API already enabled in Astra DB, you won’t have any installation steps.

The Katacoda scenario will take you through the process of setting up your environment variables so you can begin to use the API.

With the Document API, you create a namespace for your application, which can contain one or more named collections, which can contain multiple documents with any number of structures. You can choose the same structure for all of them or different structure(s) depending on the needs of your application and how you want to represent the data.

In our scenario, you’ll create a games document within the namespace of your Astra DB. You’ll do this with a cURL REST command. It’s worth noting here that Stargate’s Document API builds on the Stargate REST API. The REST API provides a RESTful interface to interact with your data. At this point, though, you’re still constrained by “Cassandra-isms” like schema and data modeling. The Document API takes this one step further by providing a similar RESTful API but without the setup. You can just chuck data at it and move on with writing your app instead of having to mess around with a database.

The scenario will provide a list of the information you’ll need to build the collection, including the cluster ID, the region, and the keyspace name, all of which come from your environment variables which will show you how to set based on values you’ll find in the Astra UI. You’ll also use the token that you generate when setting up your environment and the JSON for creating the table. Once you have created the document, the scenario will show you all the steps necessary to read the document, update it, replace it, and delete it.

After going through the scenario, you’ll not only know how to use the Document API to interact with your Astra DB like a document database, but you’ll also have a better understanding of all the possibilities that this opens up for Astra DB developers as well as those working with Cassandra and DSE.

If you want to see an example of a full stack app built with Stargate’s Document API, Astra DB, and Netlify (and maybe build one yourself), check out our BattleStax demo application on GitHub developed for DataStax Academy.

Follow the DataStax Tech Blog for more developer stories. Check out our YouTube channel for tutorials and here for DataStax Developers on Twitter for the latest news about our developer community.


  1. Katacoda Scenario: Getting Started with Stargate Document API for Cassandra
  2. Stargate
  3. Stargate Concepts
  4. DataStax Enterprise
  5. DataStax Astra DB
  6. Apache Cassandra®
  7. Accessing Cassandra with the Stargate Documents API
  8. Accessing Cassandra with the Stargate REST API
  9. Accessing Cassandra with the Stargate GraphQL API
  10. Stargate Document API reference (2.0.0)
  11. Stargate Document API QuickStart guide
  12. Blog Roundup: Astra + Stargate Open Source API Stack for Modern Data Apps Is Here
  13. The Stargate Cassandra Documents API (Because, sometimes, we just want JSON)
  14. BattleStax demo application on GitHub
  15. DataStax Academy




We’re huge believers in modern, cloud native technologies like Kubernetes; we are making Cassandra ready for millions of developers through simple APIs; and we are committed to delivering the industry’s first and only open, multi-cloud serverless database: DataStax Astra DB.

Recommended from Medium




C/C++: How to print colourful chars in the terminal

CRUD operation with Spring JPQL

Help us Power the World with Tech

Design of Real-time Hardware for Edge Detection

Scala write InputStream to a file

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


DataStax is the company behind the massively scalable, highly available, cloud-native NoSQL data platform built on Apache Cassandra®.

More from Medium

Creating AWS Lambda Functions with Kotlin

Create a Distributed Database with High Availability with Apache ShardingSphere

WellAware Avoided Big Database Headaches by Migrating to Astra DB