Skip to content

KPI Board Example

A simple board showing multiple key performance indicators (KPIs), built on the Dundersign demo dataset; paste it into the playground and it renders as-is.

Complete Board

title: "Executive KPIs"

source: db

queries:
  totals:
    sql: |
      SELECT
        SUM(revenue) AS total_revenue,
        SUM(new_users) AS new_users,
        SUM(documents_completed) AS documents_completed,
        SUM(tickets_resolved) AS tickets_resolved
      FROM dundersign_serving.monthly_metrics

rows:
  - grid:
      columns: 24
      items:
        - item: revenue_kpi
          width: 6
        - item: users_kpi
          width: 6
        - item: documents_kpi
          width: 6
        - item: tickets_kpi
          width: 6

    charts:
      revenue_kpi:
        label: "Total Revenue"
        query: queries.totals
        type: kpi
        value: total_revenue

      users_kpi:
        label: "New Users"
        query: queries.totals
        type: kpi
        value: new_users

      documents_kpi:
        label: "Documents Completed"
        query: queries.totals
        type: kpi
        value: documents_completed

      tickets_kpi:
        label: "Tickets Resolved"
        query: queries.totals
        type: kpi
        value: tickets_resolved
Executive KPIs 24k Total Revenue 3.2k New Users 28k Documents Completed 86 Tickets Resolved Data as of 14:25 UTC on 6 Oct 2026 made withdbt Charts
▶

The query reads dundersign_serving.monthly_metrics, a pre-aggregated rollup maintained by Dundersign's dbt project, so the SQL is a plain SELECT with no date functions, portable across warehouses.

Key Concepts Demonstrated

KPI Chart Type

The kpi chart type displays a single metric as a large number:

revenue_kpi:
  label: "Total Revenue"
  query: queries.totals
  type: kpi
  value: total_revenue
  • type: kpi: KPI chart type (dbt Charts-specific)
  • value: total_revenue: KPI value; column reference (string column name, required for KPI type)

Grid Layout

Using a grid layout to arrange multiple KPIs:

grid:
  columns: 24
  items:
    - item: revenue_kpi
      width: 6
    - item: users_kpi
      width: 6
    - item: documents_kpi
      width: 6
    - item: tickets_kpi
      width: 6
  • columns: 24: 24-column grid system
  • items: List of items to place
  • width: 6: Each chart takes 6 columns (4 charts × 6 columns = 24 columns total)

Multiple Values in One Query

A single query can return every KPI's value as its own column:

queries:
  totals:
    sql: |
      SELECT
        SUM(revenue) AS total_revenue,
        SUM(new_users) AS new_users,
        SUM(documents_completed) AS documents_completed,
        SUM(tickets_resolved) AS tickets_resolved
      FROM dundersign_serving.monthly_metrics

Each KPI chart references the same query but displays a different column.

Layout Variants

KPI charts ship in three layouts, selected via variant::

  • variant: stacked (default): value, label, and support on three lines. The fixed slot widths keep multi-KPI rows aligned.
  • variant: inline: value, label, and support all on one row, baseline-aligned. Good for tight summary strips.
  • variant: compact: 2-column. Big value on the left; up to two stacked lines on the right, with the bottom right line sharing baseline with the value.
revenue_kpi:
  label: "Total Revenue"
  query: queries.totals
  type: kpi
  variant: inline
  value: total_revenue
  support:
    value: revenue_delta_pct
    label: vs last month
    format: percent_delta
    glyph: ▲
    tone: positive

label: and support: are each independently optional in all three variants. In compact, a support: block authored without a label: splits across both right-column lines automatically (glyph + value on top, support label on the baseline).

variant: compact assumes the card is wide enough to fit the value alongside its label and support. Long labels or narrow grid widths can push text past the card's right edge. The stacked default wraps its label automatically; if you're authoring compact KPIs at narrow widths, prefer stacked.

variant: inline handles this itself: when the assembled value + label + support run does not fit the card at its available width, it falls back to the stacked arrangement for that card automatically; you don't need to switch variants by hand. A WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED warning tells you when this happened, since the card no longer matches the variant: inline you authored.

Variations and Extensions

Add Markdown Content

Add context above the KPIs:

rows:
  - title: "Executive Summary"
    text: |
      # Key Performance Indicators

      Real-time view of business performance.
    grid: ...
    # ... charts

Add Trend Charts

Combine KPIs with trend charts:

This adds a line chart of the raw series next to the KPIs. For a fitted trend line (a straight regression line overlaid on the data), see Trend Lines in the layered charts guide.

queries:
  monthly:
    sql: |
      SELECT month, revenue
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

rows:
  - title: "Overview"
    grid:
      columns: 24
      items:
        - item: revenue_kpi
          width: 6
        # ... other KPIs
        - item: revenue_trend
          width: 24

    charts:
      revenue_kpi:
        # ... KPI definition
      revenue_trend:
        query: queries.monthly
        type: line
        x: month
        y: revenue

Add Filters

Add variables to filter the KPIs:

variables:
  date_range:
    input: daterange
    # No default: starts on the full history

queries:
  totals:
    sql: |
      SELECT
        SUM(revenue) AS total_revenue,
        SUM(new_users) AS new_users
      FROM dundersign_serving.monthly_metrics
      WHERE {{ filter_date_range('month', date_range) }}