The KPI widget surfaces a single headline metric — a number, percentage, trend, or comparison — pulled directly from a query result. It is designed to be read at a glance.

Reading the data

The KPI widget takes the first value from the first row of your query result. Write your query to return exactly one meaningful value:

-- Good — returns a single scalar
SELECT COUNT(*) AS total_signups FROM users WHERE created_at >= NOW() - INTERVAL '30 days'

-- Good — returns one row, KPI reads the first column
SELECT SUM(revenue) AS mrr FROM subscriptions WHERE status = 'active'

If your query returns multiple rows, only the first row is used. If it returns multiple columns, only the first column is used as the primary metric — subsequent columns may be used by certain KPI types for comparison values. Null results display as —. An empty result set (zero rows) also displays as —, not 0.

KPI types

The KPI type controls how the query result is interpreted and displayed.

Type	Description
Number	Displays a single numeric value
Percentage	Displays the value as a percentage — typically used when your query already returns a 0–100 (or 0–1) value
Trend	Shows the current value alongside a change indicator (up/down) against a previous period
Comparison	Shows two values side-by-side — the current value against a baseline

Display options

Open the KPI widget settings to configure what is shown alongside the metric.

Option	Description
Title	The label displayed above or below the metric value. Defaults to the widget name
Prefix	Text displayed immediately before the value (e.g. `$`, `€`, `£`)
Suffix	Text displayed immediately after the value (e.g. `%`, `ms`, `users`)
Icon	An emoji or image shown alongside the title for visual context

Prefix and suffix are visual only — they do not affect the underlying number or any calculations.

Number formatting

Control how the raw numeric value is displayed.

Setting	Description
Style	`Number` (default), `Percent`, `Scientific`, or `Currency`
Separator style	`100,000,000` (Western thousands separator) or `1,00,00,000` (Indian lakh separator)
Decimal places	Number of decimal digits to show (0–5)
Multiply by	Scale factor applied before display. Enter `0.001` to convert milliseconds to seconds, `100` to convert a 0–1 fraction to a percentage, etc.

Multiply by and decimal places together — a common pattern is to set Multiply by to 0.001 and Decimal places to 1 to display a value stored in milliseconds as 1.2 s.

Compact notation

Compact notation abbreviates large numbers so they fit cleanly in the widget.

Setting	Displays as
None	Full number — `1,234,567`
K	Thousands — `1.2K`
M	Millions — `1.2M`
B	Billions — `1.2B`
Auto	Automatically selects K, M, or B based on the magnitude of the value

Auto is recommended for metrics whose value can vary across orders of magnitude (e.g. revenue that might be in the thousands one month and millions the next).

Trend graph

Enable Show mini graph to display a small sparkline chart beneath the metric value. The sparkline is driven by the same query — it uses all rows returned, plotting each row as a point on the trend line. For the sparkline to be meaningful, write a query that returns multiple rows (one per time period):

SELECT
  DATE_TRUNC('day', created_at) AS day,
  COUNT(*) AS signups
FROM users
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY 1
ORDER BY 1

The KPI displays the last row’s value as the headline number, and all rows as the sparkline.

If you enable the trend graph but your query returns only one row, the sparkline will appear as a flat line.

Directional signals

KPI signals show an up or down arrow next to the value to indicate direction. Useful for metrics where the viewer needs to know immediately whether the number is good or bad.

Setting	Behaviour
None	No arrow shown
Positive	Green up arrow when value is positive, red down arrow when negative
Negative	Red up arrow when value is positive, green down arrow when negative (for cost or churn metrics where up is bad)
Both	Shows an arrow in the neutral accent color regardless of sign

Choose Negative for metrics like error rate, churn, or cost — where a higher number is worse.

Icon

The Icon field accepts an emoji character. It appears alongside the KPI title and acts as a quick visual identifier when multiple KPI widgets appear on the same dashboard. Examples: 💰 for revenue, 👥 for users, ⚡ for performance, 🛒 for orders. The icon is decorative — it does not affect the value or any calculations.

Data Sources

Visualisation

How To

KPI Widget

Reading the data

KPI types

Display options

Number formatting

Compact notation

Trend graph

Directional signals

Icon

​Reading the data

​KPI types

​Display options

​Number formatting

​Compact notation

​Trend graph

​Directional signals

​Icon

Reading the data

KPI types

Display options

Number formatting

Compact notation

Trend graph

Directional signals

Icon