Superset can be confusing on day one, and it is usually for the same reason: people go straight to “create chart”, hit a wall, and conclude the tool is awkward.
The wall is almost always the same. Superset separates your data from your charts more strictly than Excel or Power BI does, and until that structure clicks, nothing works smoothly. Once it clicks, the whole thing gets fast.
This guide walks through a complete first dashboard, and spends a little time up front on the structure so the rest makes sense.
The mental model: four layers
Everything in Superset sits in one of four layers, and each one depends on the one before it.
1. Database connection. The credentials that let Superset talk to MySQL, PostgreSQL, ClickHouse and so on. Usually set up once by whoever administers the instance.
2. Dataset. The specific table or query that a chart reads from. This is the layer people skip, and it is the most important one. A dataset is where you define your metrics, your calculated columns and your time column.
3. Chart. One visual answering one question, built on exactly one dataset. A chart cannot pull from two datasets, which surprises people coming from other tools.
4. Dashboard. A layout that arranges charts and adds filters across them.
The rule that follows from this: if a chart cannot show what you want, the fix is usually at the dataset layer, not the chart layer.
Step 1: Connect your database
Go to Settings, then Data, then Database Connections, and add a new one.
Superset needs a connection string, which looks like this for MySQL:
mysql://reporting_user:password@hostname:3306/database_nameAnd like this for PostgreSQL:
postgresql://reporting_user:password@hostname:5432/database_nameTwo things worth doing properly at this point, because fixing them later is annoying.
Use a read only user. Create a dedicated database user with SELECT permission only. Superset lets people write SQL, and eventually somebody will paste something they do not understand.
Decide about SQL Lab access. In the Advanced tab you can allow this connection to be queried in SQL Lab, and separately allow DML. Leave DML off. Allowing SQL Lab is usually worth it for analysts.
Click Test Connection before saving. If it fails, the cause is nearly always the database not allowing connections from the Superset server’s IP, not a Superset problem.
Step 2: Create your first dataset
This is the step that decides how pleasant the rest will be.
You have two options.
Physical dataset
Point Superset at an existing table. Go to Datasets, click plus, choose the database, schema and table.
Good when the table is already shaped the way you want to analyse it.
Virtual dataset
Write a SQL query and save the result as a dataset. Go to SQL Lab, write your query, run it, then use Save as Dataset.
This is what you will use most of the time, because raw tables are rarely shaped for reporting.
Here is a typical virtual dataset for a visits dashboard:
sql
SELECT
v.visit_id,
v.visit_date,
v.patient_id,
v.district_name,
v.visit_status,
p.gender,
CASE
WHEN p.age_years < 18 THEN '01 Under 18'
WHEN p.age_years < 30 THEN '02 18 to 29'
WHEN p.age_years < 45 THEN '03 30 to 44'
WHEN p.age_years < 60 THEN '04 45 to 59'
ELSE '05 60 plus'
END AS age_band
FROM visits AS v
JOIN patients AS p ON p.patient_id = v.patient_id
WHERE v.is_voided = 0;Three habits visible in that query that will save you time later.
Keep it at one row per thing. This dataset is one row per visit. Every chart built on it counts visits. Mixing grains, for example visits and patients, in one dataset is how you end up with numbers that do not add up.
Zero pad your band labels. 01 Under 18 instead of Under 18. Superset sorts text categories alphabetically by default, and this forces the right order without a fight.
No hardcoded dates. Let the dashboard time filter do the filtering. If you bake a date range into the dataset, every chart on it is frozen.
After saving, open the dataset settings and do two things:
- Set the main temporal column to
visit_date, which is what the dashboard time filter will use. - Add your metrics under the Metrics tab, for example
COUNT(*)saved as “Total Visits” andCOUNT(DISTINCT patient_id)saved as “Unique Patients”.
Defining metrics once at the dataset level means every chart uses the same definition. This is the difference between a dashboard that agrees with itself and one that does not.
Step 3: Build the first chart
Start with something simple so you learn the interface. Click Charts, then plus, choose your dataset and pick Big Number with Trendline.
In the chart editor:
- Metric: Total Visits
- Time column: visit_date
- Time grain: Day
Click Create Chart. You get a large headline number with a small trend under it, which is the single most useful tile type for the top of a dashboard.
Save it with a clear name like “Total Visits, last 30 days”. Do not accept the default name. Six months from now, “Untitled chart 14” is a small tragedy.
Now a bar chart
Create another chart, same dataset, type Bar Chart.
- Metric: Total Visits
- Dimension: district_name
- Row limit: 15
- Sort by: the metric, descending
The row limit matters. A bar chart with 80 districts is unreadable, and the top 15 answers the real question.
If your bars refuse to sort by value and insist on alphabetical order, you have hit the most common Superset annoyance. The fix is usually to make sure the column is a proper string type in the dataset. Adding a calculated column that explicitly casts the value to STRING exposes the sort control and makes it behave.
And a time series
Third chart, type Time series Line Chart.
- Metric: Unique Patients
- Time grain: Week
- Dimension: leave empty for one line, or add gender for one line per group
Weekly grain is often better than daily for anything human scale. Daily data on a small tile looks like static.
Step 4: Assemble the dashboard
Click Dashboards, then plus. You get a blank canvas with a chart panel on the right.
Drag your charts in. Superset uses a 12 column grid, so a chart at width 4 takes a third of the screen.
A layout that works almost everywhere:
Top row: three or four big number tiles. Total visits, unique patients, completion rate, average per day. These answer “is everything normal” in one glance.
Second row: the time series, at full or two thirds width. This answers “is it changing”.
Third row onwards: breakdowns. District, age band, gender. These answer “where is it coming from”.
Bottom: a detailed table, if people need to check individual records.
Add a Markdown component at the very top with two sentences saying what the dashboard covers and when the data refreshes. It takes one minute and prevents a surprising number of support messages.
Step 5: Add filters
In edit mode, open the filter panel on the left and add filters. Superset’s native filters apply across every chart on the dashboard that uses a compatible dataset.
Useful ones for this example:
- Time range filter on
visit_date - Value filter on
district_name, set to allow multiple selections - Value filter on
visit_status
Set sensible defaults. A dashboard that opens showing all time on a five year table will be slow and will make a bad first impression. Default the time range to something like “Last month”.
One detail worth knowing: filters only apply to charts whose dataset actually contains that column. If you build charts on three different datasets, make sure the filter columns exist and are named identically in all three, or your filter will silently skip some charts.
Step 6: Control who sees it
Superset’s permission model is role based and catches people out, so handle it deliberately.
At minimum you want a viewer role that can see dashboards but not edit them, and not use SQL Lab. Create a custom role, give it the dashboard access permissions it needs plus access to the specific database or datasets, and assign users to it.
Avoid giving everyone the built in Alpha role because it is convenient. Alpha users can create and modify datasets, which means someone can change a metric definition for everybody.
If different teams should see only their own district or region, look at Row Level Security under Settings. You add a clause like district_name = 'Pune' that gets appended to every query for users in a given role. It is the cleanest way to serve many teams from one dashboard.
Step 7: Make it fast
A slow dashboard is an unused dashboard. Three things fix most of the problem.
Turn on caching. Set a cache timeout on the dataset, for example 3600 seconds if the underlying data updates hourly. The first person pays the load time, everyone else gets it instantly.
Do not make Superset do heavy lifting. If your virtual dataset is a 200 line query with six joins, every chart re-runs that query on every load. Materialise it into a summary table refreshed on a schedule, and point the dataset at that.
Limit the rows. Charts pulling 50,000 rows to draw 12 bars waste time on both the database and the browser.
Common beginner mistakes
- Building everything on one giant dataset. Different questions need different grains. A visit level dataset cannot cleanly count households.
- Defining metrics inside individual charts. Do it at the dataset level so definitions stay consistent.
- Ignoring the time column. Without a main temporal column set, the dashboard time filter does nothing.
- Fifteen charts on one page. Nobody reads them. Pick the six that drive decisions and put the rest on a second tab.
- No refresh note. Users assume data is live. Tell them it is not.
Final thought
The first Superset dashboard takes an afternoon. The second takes an hour, because by then the four layer structure is second nature and you stop fighting the tool.
Spend most of that afternoon on the dataset, not the charts. A well shaped dataset with clean metric definitions makes every chart on top of it trivial. A messy one makes every chart a negotiation.