Apache Superset and SAP HANA integration: what connects and how
A team that wants dashboards over SAP HANA data usually wants to avoid two costs at once: expanding SAP licensing and widening the scope of SAP reporting. Apache Superset can meet that need when the connection is treated as a plain SQL connection from Superset to HANA. The supported route in the Superset database catalog is the hdbcli driver with the sqlalchemy-hana dialect, which is installed into the Superset image, and a connection string in the form hana://{username}:{password}@{host}:{port}. The default port listed in the catalog is 30015, but the port of your HANA tenant database should be confirmed with your SAP Basis team. The connection is then created in Superset's database settings, where the driver, host, port and credentials are entered.
This integration is not an SAP-certified or SAP-supplied connector. Neither hdbcli nor sqlalchemy-hana comes from SAP's reporting stack, and Superset does not reproduce SAP semantic layers, calculation views or authorizations. Every query Superset sends runs as the technical user in the connection, so the SAP authorization model applies only to the extent that the database user is granted privileges on the schemas and views you expose. Before the connection goes to production, confirm the driver and dialect versions that match your HANA release and your Superset version with the packages' documentation, and confirm with SAP which licensing terms apply to the database access you plan to give a BI tool.
Plan the technical user before the first dashboard is built. Create a dedicated read-only user, grant SELECT only on the reporting schemas or curated views, and keep it separate from application and administrative accounts. Store the password in Superset's secret handling rather than in shared notes, and document who can edit the database connection, because anyone with that permission can point the connection at other objects. Ask your security team to confirm how the connection is encrypted between Superset and HANA, since the catalog entry does not settle TLS settings for your landscape.
What you need before the connection is configured
Four things have to be in place before Superset can query SAP HANA: a Superset image that includes the HANA driver packages, a production-grade metadata database with a SECRET_KEY, a network path to the HANA SQL port, and a read-only technical user. Each one can block the connection in a different way, so confirm them in order.
Driver packages in the Superset image
Superset does not ship with the SAP HANA driver, so the hdbcli and sqlalchemy-hana packages must be installed into the image that runs the web server and workers. Add them to your image build rather than installing them into a running container, so every web and worker replica has the same driver. Confirm the driver versions against the HANA version and the Superset release you run in your own environment, because compatibility is not something to assume from one release to the next.
Production metadata database and SECRET_KEY
Superset stores its own users, dashboards and connection definitions in a metadata database. Use PostgreSQL or MySQL in production, since the SQLite default is not recommended for production use. Superset also requires a user-specified SECRET_KEY to start, and the HANA connection credentials are encrypted with it, so set it before the first start and keep it in a secrets store. Check the supported metadata database versions in the configuration documentation before you choose a version.
Network path to the HANA SQL port
Superset must reach the HANA SQL endpoint over TCP from every host that runs a web or worker process, because the connection is made from Superset, not from the browser. The default port in the catalog is 30015, but your instance may use a different SQL port depending on its instance number and tenant layout, so confirm the exact port with your HANA administrators. Ask the network team to open that path through firewalls, and test it from the Superset container itself.
Read-only HANA technical user
Create a dedicated technical user in HANA for Superset and grant it only the schemas, tables and views that dashboards need, with SELECT and no write or DDL rights. Keep it separate from named analyst accounts and from application users so its activity can be audited and its password rotated without side effects. Coordinate with your HANA security team on the grants, since views that reference restricted data inherit those restrictions and may need explicit privileges.
Version compatibility checks
Confirm that your HANA version, the hdbcli version and the sqlalchemy-hana version work together, and that the Superset release you run supports the dialect. Check the vendor's client notes and the package release notes rather than relying on a general statement that HANA is supported. Record the tested combination in your change record, because an upgrade of HANA or Superset can break a driver pairing that worked before.
How to configure the SAP HANA connection in Superset
This sequence takes a self-hosted Superset from an image without SAP HANA support to a tested connection that exposes the schemas a read-only technical user can see and renders a working sample chart. Each step ends with a check so the team knows it can move forward.
Add the HANA drivers to the Superset image
The Superset platform team adds the hdbcli and sqlalchemy-hana Python packages to the image that runs the web server and Celery workers, then rebuilds and redeploys it in staging first. The HANA database catalog in the Superset documentation lists both packages for SAP HANA, so these are the packages to confirm against your Superset release before you pin versions. Done means the Superset container imports both modules without error and the Database connection dialog offers SAP HANA as an option.
Create a read-only technical user in HANA
A HANA administrator creates a dedicated technical user for Superset and grants it SELECT privileges only on the schemas, views or calculation views that dashboards need, not on whole database schemas or the SYSTEM account. Confirm with your SAP Basis team how password policy, certificate requirements and the user's privilege assignments should be set for your landscape. Done means the user can query the approved views in a SQL client and receives an insufficient privilege error when it tries to write to or read an unapproved object.
Build the connection string with host and port
The platform team builds the connection string in the form hana://{username}:{password}@{host}:{port}, substituting the technical user, the HANA host name and the SQL port. The documented default port is 30015, which applies to the instance number in your landscape, so confirm the actual SQL port with your HANA administrator if the instance uses another value. Store the password in a secret manager or Superset's encrypted credential handling, not in a file or a shared document. Done means the string is recorded in the secret store and the host resolves from the Superset containers.
Register the database and test the connection
A Superset administrator opens Settings, selects Database Connections, chooses SAP HANA, pastes the connection string and runs Test connection before saving. If the test fails, check that the drivers loaded in the image, that the host and port are reachable from the Superset network, and that the technical user is not locked or expired. Done means the test reports a successful connection and the database appears in the list with the expected name.
Confirm schema visibility for the technical user
In SQL Lab, the Superset administrator selects the new HANA database and lists the schemas and views visible to the technical user. The result should match the approved list from step two, with no system schemas or unexpected objects appearing. If extra objects are visible, correct the grants in HANA and retest rather than relying on Superset settings to hide them. Done means the visible schemas and views match the approved list and a simple SELECT on an approved view returns rows.
Build and verify a sample chart
A Superset builder creates a dataset from one approved HANA view, builds a simple chart such as a bar or table with a known total, and saves it to a test dashboard. The team compares the chart total with the same query run directly in a HANA client to confirm that Superset returns the expected figures. Done means the chart renders and its numbers match the direct query, which shows the driver, the dataset and the permissions work end to end.
How HANA users, schemas and views map into Superset
This table shows which HANA object or Superset object carries each part of the access model, and where the decision is made. Read it as a checklist for the SAP security review: each row names a layer, what it controls, and what to confirm before the first dashboard is built.
| Layer | What it maps to | Where access is decided | Confirm with the SAP security team |
|---|---|---|---|
| Technical user | One HANA database user in the Superset connection string hana://{username}:{password}@{host}:{port} | HANA: roles and privileges granted to the user | A read-only user with no write or admin privileges, and the password rotation process |
| Port | Default port 30015 in the connection string, unless the instance uses another SQL port | HANA network and firewall rules | The SQL port for the tenant and that the Superset host is allowed to reach it |
| HANA schema | Schemas the technical user can read, exposed as database and schema choices in Superset | HANA: schema privileges and object grants | Which schemas hold reporting data and which hold sensitive or operational tables that must stay out of reach |
| Calculation or analytic view | Views selected as Superset datasets, with metrics and columns defined on top | HANA: grants on the view and on the underlying tables, including analytic privileges | Whether analytic privileges on the views already restrict rows, since Superset will read through the technical user |
| Superset dataset | A dataset per approved view or table, with defined metrics and filters | Superset: dataset permissions and roles | Owners who approve each dataset and who may change its definition |
| Superset role | Groups of users granted access to specific datasets and dashboards | Superset: roles and permissions, optionally mapped from identity provider groups | Which business groups need which datasets, and who approves role membership |
| Row-level filtering | Filters applied per role or user on a dataset | Superset row level security, applied on top of HANA grants | Whether HANA analytic privileges or Superset rules are the authoritative row filter, and how they are tested |
Where Superset fits next to SAP reporting tools
Some teams use Superset to answer questions that currently take a request to the SAP reporting team or a licensed SAP analytics product. Superset reads from SAP HANA through a database connection, so the decision is less about the engine and more about which datasets, dashboards and users move to it. Start with a short list of recurring business questions and check whether the underlying tables and views in HANA are stable enough to chart directly.
- Dataset ownership: Decide who maintains the HANA views Superset queries, and whether the SAP functional team or your data team owns the semantic layer.
- Scope of users: Limit the first group to analysts and managers who need read access to a defined set of reports, not to every SAP user.
- Licensing position: Confirm with SAP whether your agreement permits third-party tools to query the HANA database directly and whether any usage terms apply.
- Support boundaries: Agree who fixes a broken dashboard when a HANA view changes after an SAP upgrade.
- Parallel running: Keep the existing reports running until the Superset outputs match them for an agreed period.
Before committing, ask SAP to confirm the licensing and support terms in writing and confirm the HANA views you plan to chart are documented and versioned.
Some outputs must come from the SAP system itself: statutory filings, financial statements produced by the ERP close, and documents that feed back into SAP processes. In these cases Superset is useful for exploration, monitoring and operational views around the official output, but it should not become the source of record for numbers that auditors or regulators receive. Making that boundary explicit early avoids two versions of the same figure circulating.
- Source of record: Document which reports are authoritative and which Superset dashboards are informational only.
- Reconciliation controls: Define how Superset figures are checked against the SAP output at each close.
- Change control: Route changes to HANA views that feed financial figures through your existing SAP change process.
- Access separation: Keep the technical user for Superset read-only and limited to the schemas it needs.
- Label and disclosure: Mark dashboards that show unaudited or intra-period data so readers do not mistake them for filed results.
Confirm with your finance and audit stakeholders which outputs they accept from SAP and which they accept from an analytics layer, and get that agreement recorded before dashboards go live.
Many organizations run SAP alongside other systems, such as a data warehouse, a CRM or operational databases. In a mixed landscape Superset may query SAP HANA together with those sources, or it may be one of several reporting tools that different departments already use. The main risk is duplicated logic: the same metric defined three ways in three tools. Choosing which layer owns each metric reduces that risk.
- Metric ownership: Decide whether shared definitions live in the warehouse, in HANA views or in Superset datasets, and record the choice.
- Tool overlap: Map which teams currently use which SAP reporting product and where Superset would duplicate them.
- Cross-source joins: Confirm whether data from HANA and other systems will be joined in the database layer or in Superset, since this affects performance and correctness.
- Identity alignment: Plan how SAP user identities map to Superset roles, so access follows the same rules in each tool.
- Retirement criteria: Set conditions under which an existing report is retired, rather than keeping it indefinitely.
Ask your SAP account team and your internal licensing owner to confirm which products and user types your agreement covers before you size the rollout.
Securing the HANA connection
Superset will run every dashboard query against SAP HANA under one database identity, so that identity and the settings around it decide what users can see and how much load they can put on the instance. The cards below cover the account, its grants, credential storage, transport encryption, query limits and export paths, and each one names the setting or check that proves it is in place.
Dedicated read-only technical user
Create a separate HANA user for Superset instead of reusing a administrator or application account. Superset connects with this single identity for most dashboard queries, so every query is attributed to it in HANA audit and monitoring views. Confirm with your HANA administrator that the user has no password expiry exemption you did not intend and that it cannot be used to log in to HANA Studio or other tools. Record the user's purpose and owner in your access register.
Least-privilege grants on named schemas
Grant SELECT only on the specific schemas, views and calculation views that dashboards need, and nothing from SYSTEM or other administrative schemas. Avoid broad system privileges and package-level grants that enable writes or DDL. Review the granted object list with HANA catalog views and compare it against the datasets registered in Superset. Any dataset that needs a new object should go through the same review before it is added.
Credentials kept out of plain configuration
The connection string takes the form hana://{username}:{password}@{host}:{port}, and a password written there will appear in the database connection record and in exports. Store the password in an environment variable or secrets manager and inject it at container start rather than writing it into superset_config.py. Check that the database connection screen and any exported metadata show a masked value, and rotate the password on a schedule your security policy sets.
TLS on the HANA connection
Where your HANA instance offers TLS, enable it on the client side and confirm that the driver validates the server certificate against your internal certificate authority. Unencrypted traffic between Superset workers and HANA exposes query text and result data on the network. Ask your HANA team which listener port carries TLS and whether it differs from the default port 30015, then test the connection with certificate validation switched on before you accept it as configured.
SQL execution limits in Superset
Set a row limit and query timeout for the HANA database in Superset so that an unbounded chart or an ad hoc SQL Lab query cannot hold large memory or threads on the instance. Restrict SQL Lab access to the roles that need it, and decide whether ad hoc SQL is permitted on this connection at all. Verify by running a deliberately large query as the test role and confirming that it stops at the configured limit.
Export and download controls
Dashboards and SQL Lab results can be exported as CSV or Excel, which moves HANA data out of the governed environment. Decide which roles may export, and confirm in your Superset role configuration that the export permissions are granted only to those roles. Test by logging in as a viewer account and checking that export options are absent, then review the export events in your audit logs.
Why the HANA connection fails and how to fix it
This table lists the failures teams most often hit when connecting Superset to SAP HANA, with the likely cause and fix for each. Read it in order when a connection test fails, since the first two rows are the most frequent. The main takeaway is that most failures sit in the image, the connection string or the database account rather than in Superset itself.
| Failure | Likely cause | Fix |
|---|---|---|
| Driver not found | The hdbcli and sqlalchemy-hana packages were installed in a local environment or a build layer that the running Superset image does not use | Add both packages to the image Superset actually runs, rebuild, redeploy, then retest the connection from the running web container |
| Connection refused or timeout | Wrong host or port. The catalog default is 30015, but your HANA instance may expose SQL on a different instance-specific port | Confirm the SQL port with your HANA administrator, then allow network access from the Superset web and worker nodes to that port |
| Dialect not recognized | The URI scheme is not hana://, or the sqlalchemy-hana package is missing so the dialect never registers | Use hana://{username}:{password}@{host}:{port} exactly, check URL encoding of special characters in the password, and confirm the package is installed |
| Certificate or TLS handshake errors | HANA requires encrypted connections and Superset cannot verify the server certificate chain it was given | Ask for the CA certificate your HANA team uses, add it to the trust store the Superset image reads, and set the encryption options your driver version documents |
| Authorization errors on schemas or views | The technical user lacks SELECT on the schema, column view or calculation view, or the view depends on objects the user cannot read | Grant read privileges on the specific analytic views and schemas through a role, then test each dataset in Superset, not only the connection |
| Timeouts on large queries | Dashboards send wide, unfiltered queries to HANA, or the Superset query timeout is shorter than the HANA response time | Add filters and aggregations in the dataset, enable caching, and review the timeout values with the HANA team before raising them |
Questions teams ask before connecting Superset to SAP HANA
Does connecting Superset to SAP HANA affect our SAP licensing?
Superset is an Apache Software Foundation project released under the Apache License 2.0, and the project has no paid edition, so the software itself carries no license fee. The SAP side is what needs review. Connecting a reporting tool to HANA is a question of how your SAP license agreement defines access, named users and indirect or external use of the database, and that wording varies by contract. Ask your SAP account team or licensing advisor to confirm in writing whether dashboards read through a technical user count toward any metric you license, before the first query is run.
What drives the effort and cost of a Superset and SAP HANA build?
The main drivers are the number of HANA schemas and views in scope, the number of dashboards and their refresh patterns, how many identity sources and roles must map to Superset, and whether the metadata database, caching layer and Celery workers are built for production. Each of these changes the work. Cost has one-time components (design, driver installation, role and security configuration, testing and handover) and recurring components (upgrades, patching, driver maintenance and support). Ask any provider for a quote that lists these items separately, with who performs each one and what each assumes about your environment.
Can our in-house team connect Superset to SAP HANA without a partner?
Yes, if your team already runs Superset and has someone comfortable with Python packaging, database drivers and SAP administration. The connection itself is a driver installation and a connection string, but production readiness depends on work outside that step: installing hdbcli and sqlalchemy-hana into the image, creating a read-only technical user with agreed privileges, applying Superset role and data access controls, and testing against the real HANA landscape. Teams without HANA administration experience usually need an SAP basis or database specialist on the project. A partner is a fit when you want the work scoped, documented and handed over on a fixed plan.
How long does the work take, and in what sequence?
Duration depends on your scope and approvals, so no fixed figure applies here. The sequence is consistent: confirm licensing and access rules with SAP, define the schemas and views to expose, create the read-only technical user, build a test image with the drivers, connect a non-production HANA system, configure roles and dashboards, run performance and access tests, then promote to production with monitoring in place. Security review and change control often take longer than the technical connection. Ask for a written plan with milestones and dependencies, and check which steps depend on your SAP team's availability.
What must our team provide before the build starts?
Plan to provide the HANA host and port details for non-production and production, the default port being 30015 for tenant databases unless your landscape uses another, and confirmation of the instance type. You will also need an SAP contact who can create or approve the read-only technical user, a list of schemas and views the reporting team needs, the identity provider or group structure that maps to Superset roles, network routes from the Superset hosts to HANA, and a named owner for dashboards and data definitions. Early access to test data and sign-off authority for production are often the items that delay projects.
Does SAP support cover a Superset connection to HANA?
SAP support covers SAP software under your support agreement. Superset is not an SAP product, and the hdbcli driver and sqlalchemy-hana dialect are third-party components, so SAP support will not generally troubleshoot Superset itself. Ask SAP what it will and will not support when a connection uses a non-SAP reporting tool, and whether any query load from that tool needs to be reviewed under your agreement. Keep a record of driver versions and the HANA version so that a support case can be reproduced. Support scope for the Superset application and its hosting comes from your own team or the partner you engage.
How does Superset fit next to SAP's own reporting tools?
Superset is a data exploration and dashboard layer that queries HANA through SQL, so it complements rather than replaces SAP reporting products that your finance or operations teams already use. Teams often keep SAP-native reports for certified, formatted outputs and use Superset for exploratory analysis and shared dashboards over approved views. Decide early which reports belong in which tool, who owns each definition, and how access is governed, so that two tools do not present different numbers for the same measure.
How to test the integration before users rely on it
Test the connection with known queries before any dashboard depends on it. Create a short list of SQL statements whose answers you already know from HANA itself, such as a count of rows in a named table, a sum over a fixed date range and a query against a view your finance team has reconciled. Run each one through the Superset SQL Lab using the hana:// connection and compare the results with the same statements run directly in SAP HANA's own SQL tools by a user with equivalent rights. Confirm that the driver packages, hdbcli and sqlalchemy-hana, load in the Superset image you actually deploy, not only on a developer workstation, and that the connection uses the host and port your HANA administrator confirmed, including the default port 30015 only if that is the instance's configured SQL port.
Check row counts and permissions against the source, then test as the restricted user. For each dataset you will publish, compare row counts and a control total, such as the sum of a numeric column grouped by period, between HANA and the Superset chart. Differences often come from time zone handling, decimal precision or filters left in a saved chart, so record every mismatch and its cause. Then log in to Superset as a test account mapped to the dashboard audience and attempt to read tables outside the agreed scope, to write or create objects, and to call functions your technical user should not reach. The technical user should fail each of these attempts. Repeat this after any change to HANA roles, because grants made for one report often widen what another consumer can see.
Measure timing under expected concurrency and keep the evidence. Time the slowest dashboards with the number of simultaneous viewers your business expects at peak, not only a single browser session, and record the query durations Superset reports alongside the statements HANA executes. Confirm with your HANA administrator that the monitoring you rely on, such as expensive statement traces or workload class views, captures queries from the Superset technical user so that a runaway dashboard is visible on the database side. Keep a dated test record listing the Superset and driver versions, the HANA release, each test, its expected and actual results and who approved the outcome. Revisit that record before every Superset upgrade, following the Upgrading Superset guide.
How DeployOpen scopes and delivers the SAP HANA integration
DeployOpen plans, builds, documents and supports self-hosted Apache Superset inside your own infrastructure, including the SAP HANA connection, drivers, technical user and network path. Engagements start from a written scope, so the connection design, access model and handover are agreed before any work begins.
How we scope
- Confirm which HANA tenant, schemas and views Superset needs, and which SAP reporting tools already serve the same users.
- Agree the driver packages, image build approach and Superset version the written scope will target.
- Define the read-only technical user, network path, port and TLS requirements with your SAP Basis and security teams.
How we build
- Install hdbcli and sqlalchemy-hana into the Superset image and verify the hana:// connection string against your HANA host and port.
- Test the technical user's privileges on the views Superset will query, then confirm that query limits and caching behave as agreed.
- Configure the metadata database, caching and worker components so that dashboards and scheduled reports run against HANA reliably.
How we hand over
- Document the connection configuration, driver versions, privilege model, network rules and secret locations in a handover pack.
- Walk your platform and SAP teams through dashboard ownership, access roles and the steps for rotating the HANA credential.
- Provide a runbook for upgrades that covers backing up the metadata database and checking UPDATING.md before each Superset version change.
How we support
- Available as a retainer for ongoing patching, Superset upgrades, driver updates and troubleshooting of HANA connectivity.
- Re-test the HANA connection and privilege set after each Superset upgrade or SAP-side change to the views in scope.
- Scope any new HANA schemas, dashboards or integrations through a written change request before the work starts.
