Superset embedding
Connect Superset, build dashboards on your Beetl datasets and make them appear under Dashboards.
Dashboards in Beetl are Apache Superset dashboards. You build them in Superset on your Beetl datasets, and Beetl shows them under Dashboards in the sidebar. Superset reads only your tenant's data, and it cannot change it.
Connect Superset
A TenantAdmin connects Superset once per tenant. Until then, Dashboards in the sidebar is greyed out and its hint says it is not configured.
Open the settings
Open Settings from the account menu, switch to Tenant and choose Dashboards.
Enter the URL and API key
Dashboards work with the Superset instance Beetl prepares for your tenant. Ask Beetl for its URL and API key.
URL must use HTTPS and cannot contain a username, password, query string or fragment. API key is write-only, so Beetl never shows it again.
Register
Choose Register. Beetl connects to Superset and sets up your tenant's database there. When the badge next to the buttons reads Active, Dashboards in the sidebar becomes available.
A Pending badge means setup has not finished, usually because Superset could not be reached or rejected the key. The error appears above the buttons; fix the cause and choose Retry provisioning.
Replace saves a new key or URL; leave API key empty to keep the current key, and Beetl checks a new key before saving it. Remove turns Dashboards off without deleting anything in Superset.
What you see in Superset
After setup, Superset has a database named Beetl <tenant>, where <tenant> is your tenant's
short name. It holds one schema with the same name, and each table in it is one of your datasets.
Materialized, registered and external datasets all appear, and a Pending dataset shows up once data
has been written to it.
The database is hidden from SQL Lab, so you create datasets from the Datasets page instead. Any SQL you write in Superset runs on Beetl's engine as DataFusion SQL.
Build a dashboard
Building charts and dashboards works as in any Superset. Follow Superset's own guides, and pick the
Beetl <tenant> database and its schema whenever they ask for a database:
- Creating your first dashboard covers datasets, charts and dashboard layout.
- Exploring data covers the chart builder and its options.
- The Superset user docs cover everything else.
When the data needs joins, filters or a ranking, build that in a Beetl pipeline and chart its destination table. You can preview every step there, and every chart on the table shows the same numbers.
Make it appear in Beetl
A dashboard appears under Dashboards only when all three of these hold:
| Requirement | How to meet it in Superset |
|---|---|
| Published | Click the Draft label next to the dashboard title so it reads Published. |
| Embedding enabled | In the dashboard's ⋯ menu, choose Embed dashboard. Under allowed domains, enter the address you open Beetl at, such as https://app.beetl.io, then enable embedding. See Embedding Superset. |
| Only Beetl data | Every chart must use a dataset from Beetl <tenant>. A single chart on another database hides the whole dashboard, and a dashboard with no charts does not appear. |
Beetl checks these every time the Dashboards page loads, so a change shows up on the next reload.
Open a dashboard in Beetl
Every user in the tenant can open Dashboards from the sidebar, where each dashboard is a card with its Superset title. Opening one shows it at full height, with the filter bar collapsed at the side. To change a dashboard, edit it in Superset.
Data freshness
Each chart query reads the latest version of the dataset. A pipeline run or sync commits its write at once, so a chart never shows half a run.
Authoring tips
| Situation | What to do |
|---|---|
| Sorted tables | Use the chart type called Table; other table types may not be enabled and fail on the dashboard. In aggregate mode, a Table sorts by its first metric, descending, so list the metric you rank by first. |
| Top N | A chart's row limit can cut rows before they are sorted, and an ORDER BY in a dataset's SQL does not carry through to the chart. Put the ranking and LIMIT in the pipeline that produces the dataset, so it holds exactly the N rows, then set the display order on the chart. |
| Bar order | Bars sort by category name unless you set the axis sort. On horizontal bars, the sort control sits under the Y axis. |
| Currency formats | Number formats do not accept a currency symbol: €,.0f shows "Invalid format". Use ,.0f and put the currency in the title or axis label. See Number formatting. |
| Large results | One chart query can return at most 50,000 rows, and a larger result fails instead of being cut. Aggregate in the dataset or the chart instead of pulling raw rows. |
| New columns | After a Beetl dataset gains columns, open the Superset dataset's edit dialog and sync the columns from the source. |
Troubleshooting
| Symptom | What to check |
|---|---|
| Dashboards is greyed out ("not configured") | Superset is not Active. A TenantAdmin checks Settings → Tenant → Dashboards, fixes the error and chooses Retry provisioning. |
| "No embedded dashboards", or one dashboard is missing | Check the three requirements: published, embedding enabled and only Beetl data. Then reload Dashboards. |
| "Dashboard not found" | The dashboard was unpublished, lost embedding or gained a chart on another database. |
| The dashboard opens blank | Check that the embed settings' allowed domains include your Beetl address. |
| A chart shows an error | Open the chart in Superset to read the message. Common causes are a table type that is not enabled, an invalid number format, SQL that is not valid DataFusion SQL, more than 50,000 rows, or a dataset deleted in Beetl. |
Last updated on