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
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: 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 systemitems: List of items to placewidth: 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 style.variant::
stacked(default): value, label, and support on three lines. The fixed slot widths keep multi-KPI rows aligned.inline: value, label, and support all on one row, baseline-aligned. Good for tight summary strips.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.
customers_kpi: label: "Net New Customers" query: queries.totals type: kpi value: net_new_customers good: up support: value: revenue_delta_pct label: vs last month good: up style: variant: inline support: format: percent_delta
good: names which direction of the support value is good, so the glyph and color follow its sign when a filter or refresh flips it. good: down suits a cost, where a rise reads as bad. Zero and null draw no glyph. Set style.support.glyph.up, down, or neutral to change the symbols.
The chart-root good: does the same for the headline number, for a KPI whose headline is itself a change, like net new customers; its symbols are style.value.glyph.up, down, and neutral. Leave it off a plain total.
A style.conditional rule keyed on the support column restyles the card wherever it matches. The body names the row it styles (value, label or support); the column only supplies the value the condition tests. This one marks a flat band with a warning tone on the support row and leaves the sign behavior everywhere else:
revenue_kpi: label: "Total Revenue" query: queries.totals type: kpi value: total_revenue support: value: revenue_delta_pct label: vs last month good: up style: conditional: revenue_delta_pct: - between: [-0.01, 0.01] support: tone: warning
A rule can set background, value.font, label.font and support.font (color and weight), and support.tone. Every matching rule applies and the later one wins per key; a default: true rule applies only when no other rule in its column matched. Glyphs are content, not a rule output: good picks them from the sign.
Content sits at the chart root: the value, label, an optional headline glyph, and the support line's value, label, and glyph. How it looks sits under style:: variant, the support row's format and tone, and a font for each slot (style.value.font, style.value.affix.font, style.value.glyph.font, style.label.font, style.support.font, style.support.glyph.font). style.label.overflow sets how a long label fits (clip, truncate, wrap-two, wrap).
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).
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.
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 style.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) }}
Related¶
- Charts Guide - Learn about KPI charts
- Boards Guide - Learn about grid layouts
- Interactive Board Example - Add variables and filters