Azure Cosmos DB Playground: Learn and experiment with queries in your browser

#docker #python #javascript #webdev

Interactive Browser-Based Environment to Learn, Test, and Share Queries

The Azure Cosmos DB Playground is an interactive, browser-based playground for learning and experimenting with Azure Cosmos DB SQL queries without any setup, installation, or cloud costs. The playground runs on the Azure Cosmos DB vNext emulator and leverages the open-source codapi project behind the scenes.

The playground is a great tool for learning, prototyping, testing, and sharing Azure Cosmos DB queries. You can:

📦 Explore with pre-loaded datasets and ready-to-run query examples
📤 Paste or upload your own JSON data to experiment with custom scenarios
⚡ Instantly see query results and modify both data and queries on the fly
🔗 Generate shareable links that capture your current dataset and query for easy sharing
♻️ Restore your last session automatically after a refresh or reopening the page
🧩 Embed interactive, runnable examples directly into HTML files for documentation, blogs, or tutorials

Note: This is an experimental project and not an official Microsoft or Azure offering. It’s designed for learning and sharing, not for production use.

▶️ Quick Demo (click to play)

Try the Playground (or Deploy Your Own) 🚀

You can head over to https://aka.ms/cosmosdb-playground and start experimenting right away!

While the hosted playground is ready to use, you can also deploy your own instance on Azure. The playground uses a fully containerized architecture with Docker Compose. Follow the detailed deployment instructions available on GitHub to set up your own playground instance.

To configure HTTP(s) access for your deployed playground, refer to the instructions available on GitHub.

Playground Features 🛠️

These might evolve over time - You can check out the GitHub repository for up to date list of features.

Behind the Scenes 🏗️

Here is a simplified architecture of the Azure Cosmos DB Playground:

+-------------------+        +-------------------+        +-------------------+
|   User Browser    |  <---> |      nginx        |  <---> |     Codapi        |
| (playground.html) |        | (Reverse Proxy)   |        | (Sandbox Server)  |
+-------------------+        +-------------------+        +-------------------+
                                                           |
                                                           v
                                                +--------------------------+
                                                |  Ephemeral Query Container|
                                                |  (Python + Cosmos SDK)    |
                                                +--------------------------+
                                                           |
                                                           v
                                                +--------------------------+
                                                | Cosmos DB Emulator       |
                                                | (Docker Container)       |
                                                +--------------------------+

At its core, the playground uses the Azure Cosmos DB vNext Emulator as a custom Codapi sandbox.

Azure Cosmos DB vNext Emulator: This is a local version of Azure Cosmos DB (SQL API) available as a Docker container. It emulates the real Azure Cosmos DB service, so you can experiment with queries and data models without any cloud setup or cost.

Codapi: It is a lightweight sandbox server designed for interactive documentation, code examples, and learning environments. In the playground, Codapi manages the creation of isolated Docker containers for each query execution. This ensures that each user’s code and data are executed in an ephemeral environment. Codapi JavaScript widget (codapi-js) is used for the playground frontend integration, which invokes the Codapi API for code execution in the sandbox.

Query Execution Flow

nginx serves the frontend and routes API requests to Codapi, enabling interactive query execution from the browser.

For each run, Codapi spawns an ephemeral query Docker container where a Python component connects to the long-running Cosmos DB emulator. It creates a temporary Cosmos DB container, seeds the data, executes the query, and returns results. After execution, both the temporary Cosmos DB container and the ephemeral query Docker container are cleaned up.

Limitations ⚠️

The playground is a sandbox for learning and experimentation, not production use. It is designed for small(ish) datasets and may have performance constraints, among other limitations. Some of these limitations may change over time. For the most current list, refer to the GitHub repo.