At Imply, we are always looking for innovative ways to help you learn Apache Druid. To get you started with the Druid APIs, we’ve developed a set of interactive tutorials focused on Druid API fundamentals. These tutorials are available as Jupyter Notebooks and can be downloaded individually or as a Docker container.
For those of you not familiar with the Jupyter Notebook, it is an open source interactive web application developed by Project Jupyter.
Notebooks are great for creating interactive tutorials because they combine computer code with Markdown text making it possible to call APIs and run commands from the same page. No more context switching!
The following notebook tutorials work with the Druid 25.0 release and later.
This notebook introduces you to the basics of the Druid REST API. You’ll learn how to retrieve basic cluster information, ingest data, and query data.
Visit Learn the basics of the Druid API to view the notebook on GitHub.
This notebook provides a quick introduction to the Druid Python API, a Python wrapper around the Druid REST API. Although the Druid Python API is primarily intended to help with the Jupyter-based Druid tutorials, you can use it in your own notebooks, or in a regular Python program.
Visit Learn the Druid Python API to view the notebook on GitHub.
This notebook introduces you to the unique aspects of Druid SQL with the primary focus on the SELECT statement.
Visit Learn the basics of Druid SQL to view the notebook on GitHub.
You can run the notebooks locally on your system or in Docker using the Docker Compose file. The Docker Compose file provides a custom Jupyter container that includes all of the Jupyter-based Druid tutorials and prerequisites. In addition to the Jupyter container, you can run the containers for Druid and Apache Kafka.
Jupyter in Docker requires that you have Docker and Docker Compose. We recommend installing these through Docker Desktop.
Ready to hit the ground running? This method gets you started with the tutorials in no time!
You can run the containers for Jupyter and Druid using the Docker Compose file provided in the Druid GitHub repo.
To get started, download docker-compose.yaml and environment from tutorial-jupyter-docker.zip.
Alternatively, you can clone the apache/druid repo and access the files in druid/examples/quickstart/jupyter-notebooks/docker-jupyter.
In the same directory as docker-compose.yaml, start the application with the following command:
Katya Macedo DRUID_VERSION=26.0.0 docker-compose --profile druid-jupyter up -dThe first time you run the compose environment, it can take several minutes to load.
Tip: You pass in the version of Druid as an environment variable that gets read into the docker-compose file. When new versions of Druid come out, update the variable when you launch the tutorials. For example, DRUID_VERSION=27.0.0
Another benefit of using Docker Compose is that you can run different combinations of services, based on what you have specified in the profile flag. For example, if you already have Druid running locally, you can just run the Jupyter container as follows:
docker-compose --profile jupyter up -dFor detailed instructions on how to run the notebooks in Docker, see Docker for Jupyter Notebook tutorials.
——
We’re continuously adding more tutorials to our library. If you have an idea for your own notebook tutorial, please make a contribution! We’ll work with you to merge it to the repo.
In the meantime, don’t be a stranger, check out our Jupyter Notebook-based Druid tutorials in the apache/druid repo and share your feedback.
The Breaking Point for Observability Leaders
Observability is at a crossroads For years, observability has promised to give teams the visibility they need to keep digital services resilient. But as data volumes explode, many leaders are realizing the...
Learn MoreThe State of Log Management 2025
Logs are exploding. Costs are climbing. Performance is stalling. If you manage logs, you’re in the hot seat Every app, every integration, every security risk—it all generates more data. And when something...
Learn MoreThe next evolution in observability: How architecture is following in BI’s footsteps
Modern observability systems are hitting the same wall business intelligence did a decade ago. As data volumes explode, the traditional model — where a single product handles ingestion, storage, compute,...
Learn More