datus-ai/datus-agent/superset-dashboard

Superset Dashboard Skill

Use this skill to create, update, or inspect dashboards in Apache Superset.

The data you need is already in a table inside a Superset-connected database — gen_dashboard does not move data. Your job: register the dataset, build charts, assemble the dashboard, validate.

Dashboard Creation Workflow

Follow these steps in order. Each step depends on the output of the previous one.

Step 1: Locate the BI database

list_bi_databases()

Match the orchestrator-provided bi_database_name against the returned name, and pick the corresponding id — that's your database_id for every create_dataset call below. If no match, bail with a structured error naming the missing DB.

Step 2: Register Dataset (create_dataset)

Register a table or SQL query as a Superset dataset.

Physical dataset (table already exists in the BI database):

create_dataset(name="target_table", database_id="<from step 1>")

Virtual dataset (aggregated/transformed view over the physical table):

create_dataset(name="view_name", database_id="<from step 1>", sql="SELECT ... FROM target_table")

• Returns dataset_id — save it for Step 3.
• IMPORTANT: database_id must be a Superset BI database connection ID from

list_bi_databases(). Source connector IDs and Superset BI database IDs are separate identifiers.

Step 3: Plan Dashboard Layout Before Creating Charts

Before calling create_dashboard, create_chart, or add_chart_to_dashboard, make an internal layout plan. Do not expose a long plan to the user unless asked, but use it to decide the chart count, chart order, and expected row grouping before any dashboard or chart write calls.

The layout plan must include:

• Reading flow: KPI overview first, then trend, breakdown / ranking,

composition, and optional detail.

• Row grouping: which charts should share a row and which chart should span a

full row.

• Chart sizing intent: KPI cards are compact and share rows; trend and

breakdown charts usually share rows; detail tables usually span the full row.

• Creation order: create and add charts in the same order users should read

the dashboard.

If the user provides a row-by-row layout, normalize it against these rules before creating resources. Avoid blindly creating one row per chart when charts can share a row.

Step 4: Create Dashboard (create_dashboard)

create_dashboard(title="Dashboard Title", description="Optional description")

Returns dashboard_id — save it for chart creation and assembly.

Step 5: Create Charts (create_chart)

Create visualization charts referencing the dataset.

create_chart(
    chart_type="bar",        # bar, line, pie, table, big_number, scatter
    title="Chart Title",
    dataset_id="<from step 2>",
    dashboard_id="<from step 4>",
    metrics="revenue,COUNT(order_id)",
    x_axis="date_column",
    dimensions="category"
)

Metrics format:

• Plain column name defaults to SUM(column): "revenue" -> SUM(revenue)
• Explicit aggregation: "AVG(price)", "MAX(amount)", "MIN(cost)", "COUNT(id)"
• Multiple metrics comma-separated: "revenue,COUNT(order_id),AVG(price)"

For `big_number` charts:

• Use a single metric: metrics="AVG(activity_count)"
• No x_axis or dimensions needed.

Dashboard design defaults:

• Create charts in this visual order: KPI overview, time trends, category

breakdowns / rankings, composition, then optional detail table.

• Use 3-5 big_number charts for headline metrics when the request includes

totals, counts, rates, averages, or sums.

• Use line only when there is a real temporal column; otherwise use bar

for comparisons and rankings.

• For high-cardinality categories, prefer a virtual dataset SQL that pre-filters

or ranks the top 10-15 values before creating the chart.

• Use pie only for fewer than 7 categories and exactly one metric.
• Avoid one chart per column. Do not use a fixed chart count; include the

charts needed to answer distinct business questions, then stop.

• Keep chart titles short and business-facing, for example

"Open Requisitions by Team" instead of "count by team chart".

Step 6: Add Charts to Dashboard (add_chart_to_dashboard)

add_chart_to_dashboard(chart_id="<from step 5>", dashboard_id="<from step 4>")

Repeat for each chart.

Step 7: Finish and Let Validation Run

After assembling the dashboard, finish the run and return the created IDs. bi-validation is a validator skill invoked automatically by ValidationHook.on_end; do not call load_skill("bi-validation") or try to run validator checks manually.

Publish is complete when the creation calls succeed and the dashboard / chart / dataset identifiers are known. The framework validates reachability and wiring after the agent run ends. Return the dashboard_id, dataset_id, and chart_ids. Treat follow-up layout or chart rewiring as a separate update request.

Viewing & Querying

Updating

• Update dashboard: update_dashboard(dashboard_id, title="New Title", description="New desc")
• Update chart: update_chart(chart_id, title="...", chart_type="...", metrics="...", x_axis="...", description="...")
• Use updating for an explicit change request or a concrete validation

mismatch. Keep existing published resources when the publish checks pass.

Deleting

MUST confirm with user before any deletion.

• delete_dashboard(dashboard_id="...")
• delete_chart(chart_id="...")
• delete_dataset(dataset_id="...")

Important Rules

1. Data movement is outside scope. If the target table doesn't exist in

the BI database, stop and return a structured error naming the missing table. The caller must prepare or refresh data separately with gen_job or scheduler before retrying dashboard creation.

1. Use a Superset BI database ID for create_dataset — obtain it from

list_bi_databases, not from a source connector.

1. Language: Match the user's language (Chinese input -> Chinese output).
2. Multiple charts: Create separate datasets for charts needing different data shapes.