How the Apache Superset and Apache Druid integration works
Your team wants event and time-series dashboards from Apache Druid in Superset, and the first decision is how Superset reaches Druid. In this setup Superset sends queries to Druid's SQL interface through the pydruid driver, which is a Python package that must be installed in the Superset image before any Druid connection can be created. Superset does not ship with it enabled by default, so the image build is the first place to plan for it. Treat the connection itself as a deployment artifact: it belongs in your image, your configuration and your change process, not in a one-off setup on a running instance.
The exact connection string, the TLS certificate options and the list of supported SQL features depend on the Superset release and the Druid release you run, so confirm them before design starts rather than copying an example from a forum. Check the database connection section of the Superset configuration documentation and the Druid documentation for the version in your environment. Pay particular attention to which time grains Superset offers for Druid datasets, how joins across datasets behave and whether any SQL functions are blocked by default, because these shape which dashboards are practical.
This page helps you decide four things: whether pydruid in your image meets your security and dependency rules, how the Druid endpoint is exposed to Superset and secured with TLS, which time grains and join patterns your event dashboards need, and how you will test those dashboards against a staging Druid cluster before users depend on them. Each of these choices affects the sections that follow, so record the answers as you read.
What you need before connecting Superset to Druid
Connecting Superset to Druid depends on five things being in place before any connection string is entered: a tested Superset version, a Druid SQL endpoint that Superset can reach, a read-only Druid account, a supported metadata database, and a TLS certificate chain that both sides trust. Each card below is a decision or check your team should close first, because gaps usually surface as failed connections or stalled dashboards rather than clear errors.
A tested Superset version
Pick the Superset release your team will run, then test the Druid connection on that exact version in staging before production. Superset 6.1.0 and 7.0.0rc2 are listed in the supplied release history, but 7.0.0rc2 is a pre-release, so it is a poor base for a production Druid connection. Before each upgrade, check UPDATING.md for breaking changes that affect database drivers or connection handling. Confirm which pydruid version your chosen release expects, because the driver is installed into the image and is not something you can assume from the connection string alone.
A reachable Druid SQL endpoint
Superset does not talk to Druid's ingestion or segment services directly. It connects to the Druid SQL endpoint, usually served through the Router or Broker, and that endpoint must be reachable from the Superset web and worker containers, not only from your workstation. Confirm the host, port and path with your Druid administrator, and test from inside the same network segment and container runtime that Superset uses. If Superset runs in Kubernetes, confirm egress policies and DNS resolution from the pods, since alerts, reports and async queries run from the worker containers.
A read-only Druid user
Create a dedicated Druid account for Superset that has only the read permissions needed to query the datasources your dashboards use. Do not reuse an administrative or ingestion account, because Superset users can write arbitrary SQL through SQL Lab unless you restrict it. Confirm with the Druid security documentation how authentication and datasource-level permissions are enabled in your Druid version, and decide which datasources the account can see. Record who owns the credential and how it is rotated, since it will be stored in Superset's database connection configuration.
A supported metadata database
Superset stores its own state, including users, dashboards, charts and database connection records, in a metadata database. The supplied documentation says PostgreSQL and MySQL are the tested options, with PostgreSQL 10 to 17 and MySQL 5.7 and 8.x listed as supported versions. The SQLite default and the Docker Compose PostgreSQL container are not recommended for production. Keep this database separate from Druid, which is the analytics source, and plan backups of it before connecting any analytics source, because the Druid connection record lives there.
A certificate chain both sides trust
If Superset connects to Druid over TLS, the full certificate chain issued for the Druid endpoint must be available to the Superset containers, including any internal certificate authority that signed it. Confirm with your security team whether the certificate is publicly trusted or issued by a private CA, and whether hostname verification will match the name Superset uses in the connection string. Decide where the CA bundle lives in the image or mounted volume, and who renews it. Expired or incomplete chains are a common cause of connection failures that look like network faults.
Confirmed Druid and Superset documentation
Before you finalize the design, confirm the Druid SQL features, time grain support and join limitations against the Druid documentation for the version your cluster runs, and confirm the pydruid and Superset database connection options against the Superset documentation for your release. Druid versions and Superset releases change independently, so a design that works on one pair may not hold on another. Record the versions you tested, the driver version installed, and the reviewer who approved them, so the connection can be reproduced after an upgrade.
How to configure the Druid database connection in Superset
This sequence takes a self-hosted Superset from a Druid SQL endpoint that is reachable from its container to a tested connection, a dataset with a defined time column, and a chart that returns the expected rows. Each step closes with a check, so a failure is caught before dashboards depend on the connection.
Install pydruid into the Superset image
The platform engineer who owns the Superset image adds the pydruid driver to the build, using the method your Superset deployment documentation specifies for extra database drivers. Rebuild the image, roll it to a staging environment, and confirm the package is present by running a Python import of pydruid inside a running Superset container. The step is done when the import completes without an error and the image tag used in staging is recorded for the change record.
Confirm the Druid SQL endpoint responds
From the same Superset container, the engineer sends a minimal SQL query to the Druid SQL endpoint that the cluster exposes through its router or broker, such as a SELECT against a known datasource with a row limit. Confirm the endpoint path and port in the Druid documentation for your version, and check that the network policy allows traffic from the Superset pods or hosts. The step is done when the query returns a valid response and the container can reach the endpoint without going through a workstation.
Create the Druid database connection in Superset
A Superset administrator opens the database connections settings and adds a new database that uses the Druid dialect. Enter the SQLAlchemy connection string exactly as the Superset database connection documentation describes for Druid, substituting your router or broker host, port, and path. Use a service account with read access only to the datasources that dashboards need. The step is done when the connection form saves without validation errors and the database appears in the list.
Set TLS and certificate options
The security owner decides how Superset verifies the Druid endpoint. Options typically include enabling TLS in the connection, supplying a CA certificate bundle that the Superset image trusts, or disabling verification only in a test environment that is documented as such. Confirm which certificate options the pydruid version in your image accepts, and store any certificate material through your secrets process rather than in plain connection settings. The step is done when a request over the TLS path succeeds and no verification warning is logged for the production endpoint.
Test the connection from Superset
In the database connection form, the administrator runs the connection test and then opens the SQL Lab with the new database selected. A simple query against a known datasource confirms that Superset can authenticate, reach the endpoint, and return rows. If the test fails, compare the error with the Superset server logs and the Druid router or broker logs before changing settings. The step is done when both the connection test and a SQL Lab query return results, and the query text and result size are noted for later comparison.
Add datasets and define the time column
The analyst or data owner adds each Druid datasource as a Superset dataset and sets its main datetime column so that time grains and time range filters work on event data. Confirm the column type that Druid reports and check which time grains the dialect exposes for your version, since support can differ by function. The step is done when each dataset previews rows with timestamps in the expected time zone and the time column appears in the dataset settings.
Build a chart to confirm results
The analyst builds one simple time-series chart on a dataset, such as a count of events grouped by a time grain over a short, known window. Compare the chart values with the same aggregation run directly against Druid for that window. Joins across datasets are limited on this path, so keep this test to a single datasource. The step is done when the chart values match the direct query and the chart is saved to a test dashboard for the team to review.
Which TLS and certificate settings to confirm for your Druid endpoint
The TLS settings you can use depend on how your Druid endpoint is exposed and on the pydruid driver version Superset loads, so confirm both before writing the connection. Druid SQL is usually reached through a Router or Broker behind a load balancer or ingress, and the certificate that terminates TLS there determines what Superset must trust. Check the current Superset database connection documentation for how the Druid driver accepts certificate paths, CA bundles and verification settings, and test the exact option names against the pydruid release in your image. Do not copy a settings example from an older blog post or from a different driver such as the ones used for SQL Server or PostgreSQL.
The main decision is whether Superset verifies the Druid certificate against an internal certificate authority that you distribute to the Superset image, or against the public CA certificates already in the system trust store. An internal CA suits Druid clusters on private addresses or certificates issued by your own PKI, and it means the CA bundle must be mounted into every web and worker container that runs queries, with a process for rotating it. The system store fits endpoints with publicly trusted certificates, but it still requires confirming that the hostname in the connection string matches the certificate's subject names. Ask your platform team which certificate chain the Druid endpoint presents and who owns its renewal.
Disabling certificate verification may look like a quick fix when a connection fails, but it removes the check that the Druid endpoint is the server you intended to reach, and the query credentials and results travel over that channel. Treat any setting that turns verification off as a finding to fix in staging, not a production option, and confirm that the connection fails closed when a certificate is expired or untrusted. Record the chosen certificate source, the mounted CA path and the renewal owner in your deployment documentation so that a rotated certificate does not silently break dashboards.
How Druid datasources and columns map to Superset datasets
This table shows how each Druid element becomes a Superset dataset element, who decides each mapping, and the check that confirms it. Read it before you build the first dataset, because the time column and metric definitions drive every chart that follows. The main takeaway is that most dashboard errors trace back to a timestamp or metric that was mapped without being tested against a known query result.
| Druid element | Superset element | Owner of the decision | Check that confirms the mapping |
|---|---|---|---|
| Datasource | Dataset on the Druid database connection | Analytics lead with the data owner | Dataset row count for a known time window matches a Druid SQL query run directly |
Timestamp column (__time or equivalent) | Temporal column used for time grains and time filters | Data engineer who owns ingestion | Time grain charts bucket records into the expected hours or days for a sample event |
| Dimension column | Group-by column and filter column | Data owner, with analysts reviewing names | Each dimension returns the expected distinct values in a Superset chart and in Druid SQL |
| Metric or aggregation | Saved metric with an explicit aggregation expression | Finance or metrics owner who signs off definitions | Saved metric total equals the reference total from an independent Druid SQL query |
| Multi-value or nested field | Column that needs explicit unnesting or is left out | Data engineer, after reviewing the ingestion spec | A test chart groups by the field and the result matches the raw data |
| Druid join or lookup use | Dataset built from a single datasource, or a virtual dataset with a documented join | Solution architect, with the Druid SQL limits confirmed for the version in use | Virtual dataset returns the same rows as the Druid query it replaces |
| Column type and format | Column type, number format and time zone setting | Analytics lead | Dates and totals displayed in Superset match the values in the source query |
| Dataset ownership and access | Dataset owner and role permissions | Security or platform owner | Role test user sees only the datasets granted to that role |
What Druid SQL can and cannot do in Superset charts
Joins are the constraint that shapes Druid dashboard design most. Druid is built to scan datasources efficiently, and joins across Druid datasources are a known limit, so a chart that expects to join an events datasource to a customer or product table should not be assumed to work. Confirm the join types and size limits your Druid version supports in the Druid SQL documentation before you commit to a design. For most event dashboards, the better path is to denormalize at ingestion, so each event row carries the dimensions people filter by, or to pre-aggregate with rollup into a summary datasource sized for the questions the dashboard answers. Plan this with the data owners early, because changing a datasource's shape later usually means re-ingesting data.
Time grain support is the second item to verify, and it depends on two versions at once: the Superset release and the Druid SQL functions its Druid engine generates. Superset offers common grains such as hour, day, week and month in chart controls, but which grains work for a given Superset version should be confirmed in that version, not assumed from the names alone. Run each grain against a real datasource and compare bucket boundaries with a known count. Confirm time zone handling as well, since a day bucket that starts at a different hour than your reporting day will shift totals on the dashboard. If a grain is missing, avoid hiding the gap with a custom expression that Druid may evaluate slowly or reject. Build the bucket in the datasource granularity instead.
These gaps change chart design for time-series dashboards in three ways. Charts that need a grain Druid does not provide should use the nearest supported grain together with a rollup granularity that matches the question, so queries stay fast and results stay consistent. Dashboards that compare periods should use the same grain across all charts, because mixed grains on one page make totals look inconsistent. Finally, record the tested grain list for your Superset and Druid versions in your upgrade checklist, since a Superset upgrade can change which grains appear in chart controls and the results should be retested before go-live.
Security settings for a Druid connection in Superset
A Superset connection to Druid is only as safe as the account, network path and permissions behind it. The controls below decide what Superset can read, how credentials and traffic are protected, and who can change the connection. Settle them before dashboards open to users, not after.
Read-only Druid service account
Create a dedicated Druid user for Superset with read permissions only, limited to the datasources your dashboards need. Superset runs whatever SQL its users generate, so the account's privileges set the blast radius of any mistake or abuse. Ask your Druid administrator to confirm which permission model your cluster uses for SQL queries and whether datasource-level grants are available in your version. Review the grants after every new datasource is added.
Credentials in database configuration
Store the Druid username and password in Superset's database connection settings, not in dashboard code, environment files committed to source control or chart definitions. Restrict who can read the stored connection, since database connections hold the secret. Confirm how your deployment supplies the secret key and encryption for stored credentials, and rotate the Druid password on a schedule you can document.
TLS verification to the Druid endpoint
Connect to the Druid router or broker over HTTPS and verify the server certificate against your internal certificate authority. Disabling verification to get a connection working hides the problem and leaves credentials exposed to interception. Ask your team to confirm which certificate option the pydruid connection path in your Superset version accepts, and test with an expired or untrusted certificate to prove that the connection is refused.
SQL execution limits and row-level security
Decide before rollout how long a query may run, how many rows a chart may return and whether row-level security filters apply to every datasource. Druid SQL can scan large time ranges, so a dashboard with no time filter can load a cluster heavily. Set Superset's query limits and time-range defaults, then map each audience to the filters it must see. Document these choices so they can be reviewed later.
Network segmentation of Druid traffic
Allow traffic from Superset to the Druid router or broker only on the required port, and keep Druid's internal services such as historicals, middle managers and the coordinator off the Superset network. Place Superset's workers and metadata database in the same segment rules so that a compromised dashboard host cannot reach the cluster's internal components. Ask your network team to confirm the ports your Druid deployment exposes.
Control over database connection changes
Anyone who can create or edit a database connection in Superset can point it at a different host, change the account or pick up credentials. Limit the Admin and database creation permissions to a small group, review that group's membership on a set schedule and log changes to connections. Confirm which Superset roles grant database management in your version before assigning them.
Common Druid connection failures in Superset
This table lists the failures teams most often hit when connecting Superset to Druid over Druid SQL with pydruid. Each row gives the likely cause, what to check first and the fix, so you can work through symptoms in the order they appear during setup.
| Failure | Likely cause | What to check | Fix |
|---|---|---|---|
| Druid database option missing or import error | The pydruid driver is not installed in the Superset image or virtual environment | Run the image's Python package list and confirm pydruid is present in the same environment that runs the web and worker processes | Add pydruid to the image build and redeploy every Superset process, not only the web container |
| Druid SQL endpoint unreachable from containers | The Router or Broker address resolves on the host but not inside the Superset container, or a network policy blocks the port | Test the Druid SQL port from inside the running Superset container, and check DNS names and namespace rules | Use an address the container can reach, correct the DNS entry, or open the egress rule to the Druid Router or Broker |
| Certificate verification errors on TLS | Druid presents a certificate signed by an internal CA that Superset does not trust, or the hostname does not match | Read the verification error in the Superset logs and compare the certificate chain and subject name with the connection host | Mount the CA bundle into Superset and reference it in the connection settings, or issue a certificate that matches the host name used |
| Authentication rejected | Wrong username or password, an expired credential, or a Druid authentication extension that does not accept the client's method | Confirm the account exists and has read access to the datasources, then test the same credential with a Druid SQL client outside Superset | Correct the credential in the connection, rotate it through your secrets process, and grant the required datasource permissions |
| Dataset has no temporal column | The Druid datasource has no time column that Superset can detect, so time filters and time grains cannot apply | Open the dataset in Superset and check the main datetime column setting, then inspect the datasource schema in Druid | Set the main datetime column on the dataset, or add a time-typed column in ingestion if the source data lacks one |
| Join not supported | Druid SQL joins are limited, so a join that works in a relational database fails or is rejected | Review the Druid version and the join type in the virtual dataset SQL against Druid's documented join limits | Redesign the dataset to query one datasource, pre-join during ingestion, or move the joined view to a database built for joins |
| Time grains do not appear | The time grain options depend on the Druid dialect support in the installed Superset version, or the time column is not a valid timestamp | Check the time column type, then confirm the grain list in the installed Superset release for the Druid engine | Fix the column type, upgrade to a Superset release with the needed support, or use custom time expressions in the chart |
| Slow queries over long time ranges | Wide intervals scan many segments, and dashboards issue several queries on each load | Compare the query time range in the Superset query history with the Druid query logs and check how many charts run per dashboard | Narrow default time ranges, enable result caching, and set Druid query limits and timeouts agreed with the Druid operators |
Questions buyers ask about the Superset and Druid integration
How much effort is the Druid connection compared with dashboard design work?
For most teams the connection is the smaller part of the work. Connecting Superset to Druid through Druid SQL involves installing the pydruid driver into the Superset image, building a connection string, and settling TLS certificate handling. Those steps are bounded and testable. Dashboard design takes more effort because it depends on the data model, the time columns, the metric definitions and the questions business owners need answered. Ask any partner to split the quote into connection and validation work on one side and dataset modeling and dashboard build on the other, so you can see where the hours really go.
How long does a first Superset and Druid integration usually take?
Duration depends on how many datasources, how many dashboards and how clean the Druid data model already is. The main drivers are the number of Druid datasources to expose, whether Druid is served behind a load balancer or gateway that needs TLS configuration, how many environments (development, staging, production) must be kept in step, and whether the team needs time-grain or join behavior explained to analysts. A narrow first scope with one or two datasources usually moves faster than a broad rollout. Ask for the timeline in the written scope, with milestones tied to the datasources and environments you name.
What must our team provide before the integration starts?
The team needs to provide four things before work begins:
- Network access from the Superset hosts to the Druid broker (Druid SQL endpoint) on the agreed port
- A read-only Druid user or credential set, with the datasources it may query listed
- The CA certificate chain or certificate details needed for TLS verification, if your Druid endpoint uses a private CA
- Named owners for each datasource, who can confirm column meanings, time columns and metric definitions
Confirm the Druid version and access model with your Druid administrators at the start, since they decide which connection settings are available.
Can our in-house team build and run this integration without a partner?
Yes, if the team already runs Superset and Druid and has someone who can build container images, manage secrets and read Druid query logs. The connection itself is standard configuration. The harder parts are verifying TLS properly, writing queries that respect Druid's join limits, choosing time grains that match how Druid stores timestamps, and keeping the driver version aligned across upgrades. A partner is most useful when the team lacks Druid experience or needs the work documented and handed over with tests. Compare the internal effort against the written scope a partner would deliver, including documentation and the hand-over.
How do Superset upgrades affect the Druid driver and connection?
Each Superset upgrade can change the Python dependencies, the supported driver versions and the connection handling, so the pydruid driver must be checked on every upgrade. The Superset upgrade documentation says to back up the metadata database, run the database upgrade and init commands, test in staging first, and check UPDATING.md for breaking changes between versions. For Druid, that means re-running a test query against each datasource in staging, confirming the TLS settings still validate, and confirming time-grain behavior in charts still matches expectations. Keep the driver pinned in your image build so a rebuild cannot change it silently.
What are the main limitations to plan around when querying Druid from Superset?
Druid SQL is powerful for event and time-series queries but has limits that affect dashboard design. Joins are restricted compared with a general-purpose warehouse, so datasets that need to combine several sources usually require denormalized Druid datasources or a different engine. Time-grain support depends on the Druid timestamp column and the SQL functions available, so confirm each grain your dashboards need against a test query. Plan these checks as part of the dataset design, not after dashboards are built. Confirm the current join and function behavior in the Druid documentation for your version.
When should a team choose a different query engine instead of Druid?
Consider a different engine when dashboards need frequent multi-table joins, when most questions are ad hoc across many sources, or when the data is mostly transactional rather than event or time-series. In those cases a warehouse or SQL engine with richer join support may fit better, and Superset can connect to several of them from the same deployment. Also consider the trade-off on the other side: if your main need is sub-second slices over large event streams, Druid may remain the right choice even with join limits. Compare candidate engines on your own queries and your data model before committing to a design.
How DeployOpen scopes and delivers the Druid integration
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes the Superset to Apache Druid connection. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- Inventory which Druid datasources, Superset datasets and dashboards the integration must serve, and who needs access to each.
- Confirm the Druid SQL endpoint, network path, and TLS certificate chain that Superset's pydruid connection will use.
- Record which time grains, joins and query patterns the dashboards require, and flag those that need a different engine.
How we build
- Create the pydruid connection string in the Superset image and configuration, with credentials stored in secrets rather than in the database UI.
- Configure TLS verification against your internal certificate authority and test the handshake from every Superset node.
- Build and validate sample charts for each time grain and join pattern, recording the limits found and the workarounds agreed.
How we hand over
- Deliver the connection configuration, certificate handling steps and image build notes as versioned documentation for your team.
- Walk your engineers through the verification checklist, covering query results, time grain behavior and failure modes.
- Document the driver and Superset version pairing so upgrades can be tested against the same Druid SQL behavior.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the initial build.
- Retainer work can re-run the Druid query tests after each Superset release and each Druid cluster change.
- Confirm with DeployOpen during scoping which support hours, response expectations and upgrade testing your retainer includes.
