> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first dashboard with Superset

> Connect a BI tool to the Data Connector and build a working chart, start to finish.

This guide goes end to end with Apache Superset, an open-source BI tool you can install yourself. The Data Connector works the same way with Power BI, Tableau, Looker, and Sigma, so the steps translate: only the field names and the chart editor differ.

## Before you start

You need a Data Connector account and a warehouse that's already been set up for your organization. For both, see [Get started with the Data Connector](/automate-with-ion/analytics-and-dashboards/get-started-data-connector).

You also need Superset running, with the Snowflake driver installed. For installation, see the [Apache Superset documentation](https://superset.apache.org/docs/installation/docker-compose).

## Connect Superset to the Data Connector

This guide signs in with your own username and password, which is the quickest way to get a first chart on screen.

> [!TIP]
>
> For a dashboard other people rely on, use a BI service user instead. It authenticates with a key pair, so the connection doesn't depend on one person's account or break when they change their password. For the steps, see [Connect a BI tool](/automate-with-ion/analytics-and-dashboards/get-started-data-connector#connect-a-bi-tool).

1. In ION, go to **Data Connector > BI service users** and find the **Connection details** card. Keep it open: you copy four values from it.

2. In Superset, go to **Settings > Database Connections** and select **Database** to start a new connection.

3. Select **Snowflake** from the **Supported databases** list.

4. Fill in the form:

   | Field | Value |
   | - | - |
   | **Database name** | **Database** from the Connection details card |
   | **Username** | your Data Connector username, which is your email address |
   | **Password** | your Data Connector password |
   | **Display Name** | any name you choose, such as `ION Data Connector` |
   | **Account** | **Server** from the Connection details card, with the `.snowflakecomputing.com` suffix removed |
   | **Warehouse** | **Warehouse** from the Connection details card |
   | **Role** | **Role** from the Connection details card |

5. Select **Connect**.

> [!NOTE]
>
> The form has no schema field, so the **Schema** value from the Connection details card has nowhere to go here. You set it on each dataset instead.

## Create a dataset

A dataset is the query behind a chart. Creating one from the **Datasets** page only points at whole tables, so anything with a join, a filter, or a `GROUP BY` starts in SQL Lab.

1. In Superset, go to **SQL > SQL Lab**.

2. Select your database, then select the schema, using the **Schema** value from the Connection details card in ION.

3. Enter a query. This one ranks suppliers by how many open purchase order lines are past due:

   ```sql theme={null}
   select supplier_name,
          count(*)                                     as po_lines,
          sum(case when is_past_due then 1 else 0 end) as late_lines,
          round(avg(days_past_due), 1)                 as avg_days_late
   from purchase_order_tracker
   where is_open
   group by 1
   having count(*) >= 3
   ```

4. Select **Run**.

5. In the query toolbar, select **Save dataset**, name the dataset, and save it.

> [!TIP]
>
> `purchase_order_tracker` is a [Data Product](/automate-with-ion/analytics-and-dashboards/data-products): a view First Resonance maintains that has the joins and the common measures already calculated, including `is_past_due`, `days_past_due`, and `outstanding_value`. Starting from a Data Product saves you rebuilding those joins, and keeps one row per purchase order line so your counts don't inflate.

## Label the columns

Unquoted names come back in uppercase, so a column you wrote as `avg_days_late` reads as `AVG_DAYS_LATE` on every axis and in every menu.

Rather than quoting the names in your query, which forces you to quote every later reference, set a label on each column:

1. On the dataset, select **Edit**.
2. On the **Columns** tab, expand a column and enter a **Label**, such as `Avg days late`.
3. Repeat for each column you plan to chart, then save.

## Build a chart

1. In Superset, go to **Charts** and select **Chart** to open the chart builder.
2. Select your dataset, choose **Bar Chart**, and select **Create new chart**.
3. In **X-axis**, add your supplier column.
4. In **Metrics**, add your average-days-late column.
5. Select **Update chart**, then **Save**.

> [!NOTE]
>
> A metric has to be an aggregate. Your query already returns one row per supplier, so an aggregate such as `MAX` returns that row's value rather than combining rows.

Leave **Dimensions** empty. That control splits each bar into a series, which isn't what you want here.

## Add the chart to a dashboard

1. In Superset, go to **Dashboards** and select **Dashboard** to create one.
2. Name the dashboard.
3. Drag your chart from the chart list onto the canvas.
4. Select **Save**.

## Troubleshooting

> **Snowflake isn't offered as a database type**
>
> The database picker shows a few types as tiles and keeps the rest in the **Supported databases** list below them. Select Snowflake from that list.
>
> If Snowflake isn't in the list either, the Snowflake driver isn't installed in your Superset environment.

> **Could not connect to Snowflake backend**
>
> The error names your firewall and allowlist, but the usual cause is the **Account** value. Remove the `.snowflakecomputing.com` suffix from the **Server** value and try again.

> **Object does not exist on a table you can see**
>
> The query ran without a schema. Select the schema in SQL Lab, or write the table name in full as `database.schema.table`.
>
> This error reads like a permissions problem, so check the schema before you ask for access.

> **A chart waits a long time on its first load**
>
> The warehouse suspends when it's idle and resumes on the next query. The first query after a quiet period waits for that, and later queries are faster.


## Related topics

- [Get started with the Data Connector](/automate-with-ion/analytics-and-dashboards/get-started-data-connector.md)
- [Custom analytics with the Data Connector](/automate-with-ion/analytics-and-dashboards.md)
- [Data Products](/automate-with-ion/analytics-and-dashboards/data-products.md)
- [Build readiness plans reference](/automate-with-ion/analytics-and-dashboards/build-readiness-plans.md)
- [Build readiness mBOM reference](/automate-with-ion/analytics-and-dashboards/build-readiness-mbom.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.