Insights: matrix, heatmap, and multi-metric cards¶

Present numbers three new ways on a dashboard — a matrix pivot, a colour-scaled heatmap, and a multi-metric card that packs several KPIs into one query — on top of the Metric, Chart, and Table cards you already have.

These are new ways to show numbers, not new plumbing: all three ride the same SQL query or published metric data sources every Insights card already uses (see Backing a card with a metric).

New presentations3 — matrix · heatmap · multi-metric

AggregationsSum · Avg · Min · Max · Count

Row cap1,000 · client-side pivot

Data sourcesSQL · Metric

When to reach for each¶

Matrix — read exact cell values

A pivot table: pick a row field, a column field, a value, and an aggregation. Every unique combination becomes a cell you can read — region × month × revenue, vendor × category × spend.
Heatmap — spot the pattern

The same pivot, but every cell is colour-scaled against the min/max of all values, so hot weeks and cold regions jump out before you read a single number.
Multi-metric — many KPIs, one query

One query, several KPI tiles in a single card frame. Cuts the warehouse cost versus four separate Metric cards, with one shared loading state.

When another card fits better

A time series (a value over dates) → a Chart card with a date X axis, not a matrix.
A single KPI → a Metric card; a matrix or multi-metric card is overkill for one number.
Two different aggregates in one grid (revenue and orders per region × month) → two matrix cards; a matrix holds one value column.
Different filters or time grains per number → separate Metric cards, or a metric-backed card per tile, not multi-metric.

Card	Best for	Wrong for
Matrix	Cross-tabs you'd build in Excel — region × month × revenue, vendor × category × spend, status × team × open tickets. You want to read individual cell values.	Time series (use a Chart card with a date X axis). Single-value KPIs (use a Metric card).
Heatmap	Same data shape as Matrix, but you care more about pattern than exact number — spotting hot weeks, cold regions, anomalous cells in dense grids.	Sparse grids (large empty regions ruin the colour scale). Reports that will be printed in greyscale.
Multi-metric	A single query that already returns several aggregates you want side by side — "Revenue, Orders, AOV, Refund rate" pulled from one `SELECT` against a `metrics` view. Cuts warehouse cost vs four separate Metric cards.	Aggregates that require different filters or time grains (use separate Metric cards or a metric-backed card per tile).

Prefer one multi-metric card over four Metric cards

If the data fits in a single query and the user wants several numbers, reach for Multi-metric. It's one round-trip to Databricks and one shared loading state instead of four.

Which card fits your data¶

The choice comes down to the shape of your result — one number, a series over time, several numbers from one query, or a grid you read cell-by-cell versus at a glance.

flowchart TD
    START{"What shape is<br/>your data?"}
    START -->|"one number"| METRIC["Metric card"]
    START -->|"a value over time"| CHART["Chart card"]
    START -->|"several numbers<br/>from one query"| MM["Multi-metric card"]
    START -->|"a rows × columns grid"| GRID{"Read exact<br/>cells or the<br/>pattern?"}
    GRID -->|"exact cells"| MATRIX["Matrix card<br/>numeric mode"]
    GRID -->|"the pattern"| HEAT["Matrix card<br/>heatmap mode"]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class START accent

Figure 1 — Pick by the shape of your data. Matrix and heatmap are the same card type in two display modes, so flipping between exact numbers and colour is one toggle, not a rebuild.

Why teams reach for these

A multi-metric card turns four Metric cards into one query and one loading state; a heatmap turns a dense pivot into a picture you read at a glance. Both ride the same SQL-or-metric data sources you already use — no new plumbing on the dashboard.

Matrix and Heatmap — set one up¶

Add a card on a dashboard you can edit.
In the type picker, choose Matrix (defaults to numeric values) or Heatmap (defaults to colour-scaled cells). You can flip between numeric and heatmap at any time on the Format tab — the underlying card type is the same.
Write the query (or pick a metric). The query must return at least three columns: the values you want as rows, the values you want as columns, and the numeric value to aggregate. Example:
```
SELECT region, month, SUM(amount) AS revenue
FROM sales.orders
GROUP BY region, month
```
The renderer caps results at 1,000 rows — same limit as every other Insights card. If your matrix needs more, pre-aggregate in the query.
Open the Build tab and configure the Pivot section:
Row Field — which column becomes the row labels (e.g. region).
Column Field — which column becomes the column headers (e.g. month).
Value Field — the numeric column to put in each cell (e.g. revenue).
Aggregation — Sum, Average, Min, Max, or Count. If your query already aggregated to one row per (row, col) combination, Sum is the right default.
On the Format tab, in the Appearance section, choose Display Mode: Numeric values (plain pivot table) or Heatmap (coloured cells).
If you chose Heatmap, pick a Color Scale — see the table below.
Set the cell Format (Number / Currency / Percent) and currency in the Format section. The same number formatter the other cards use applies here.

Heatmap colour scale — what the colours mean¶

Pick the scale that matches the meaning of "more":

Color Scale	Gradient	Reach for it when
Brand	neutral → brand colour	"More is more" data — revenue, traffic.
Success / Danger	green → red	"More is bad" or "less is bad", depending on context — errors, latency, churn.
Info	neutral → blue	You want a calm signal that doesn't read as judgemental.

The renderer computes the min and max value across all visible cells and interpolates each cell's background between them. The cell with the lowest value gets the lightest colour; the cell with the highest gets the darkest. Text colour inside each cell automatically switches between dark and light to stay readable against the background.

Anchor the scale in your query, not the renderer

The gradient is relative to whatever values are on screen — the renderer doesn't know your business meaning. If you have a baseline you want to anchor against (e.g. zero), normalise in the query first.

Multi-metric — set one up¶

Add a card and pick Multi-metric in the type picker.

Write a single query that returns one row with the numbers you want as tiles. Example:

SELECT
  SUM(amount) AS revenue,
  COUNT(*) AS orders,
  AVG(amount) AS aov,
  SUM(refund_amount) / SUM(amount) AS refund_rate
FROM sales.orders
WHERE order_date >= current_date - INTERVAL 30 DAYS

Run the query. The Build tab will auto-seed one tile per numeric column it sees — you can drag to reorder, rename, or remove tiles.
For each tile, configure:
Column — which result column drives this tile's value.
Label — the label shown on the tile (defaults to the column name).
Format — Number, Currency, or Percent.
Trend Column (optional) — pick a second column to compare this tile's value against. The tile then shows both the percentage change and the absolute change in parentheses (for example +27.9% ($41,310.75)), because a percentage on its own hides the size of the move. A Percent tile shows its change in percentage points instead (+0.6 pp).
Good direction — Higher is better (the default), Lower is better (a refund rate or a cost: a rise shows red), or Neutral (the change shows grey). A tick or a cross next to the arrow says whether the change is favourable. Available once the tile has a trend column.
Icon (optional) — a small icon before the tile's label.
(Optional) Under the tiles, Comparison label replaces the caption under the changes, for example "vs last quarter".
Save. The tiles render as one fused strip — hairline dividers between them rather than a grid of separate boxes — inside a single card frame. The strip folds to the width the card actually has, not the width of the browser: a four-tile strip in a quarter-width card stacks one per row instead of squeezing four labels into it.

flowchart LR
    Q["One query<br/>SQL or metric"] --> ROW[("First result row<br/>revenue · orders · aov · refund_rate")]
    ROW --> T1["Tile · Revenue"]
    ROW --> T2["Tile · Orders"]
    ROW --> T3["Tile · AOV"]
    ROW --> T4["Tile · Refund rate"]
    T1 --> CARD(["One card frame<br/>one loading state"])
    T2 --> CARD
    T3 --> CARD
    T4 --> CARD
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class CARD accent

Figure 2 — A multi-metric card runs a single query, reads the first result row, and maps each numeric column to its own KPI tile — all inside one card frame with one shared loading state.

Why one card, many tiles¶

One query, not N. The warehouse runs your aggregation once.
One loading state. Either every tile loads or none — no half-broken card.
One frame on the dashboard. Visually grouped numbers stay grouped; you can't accidentally separate them when a colleague rearranges the layout.

Limitations¶

Limit	Why	Workaround
Pivot is client-side.	All matrix aggregation runs in the browser over the SQL result.	The 1,000-row LIMIT every Insights query enforces is the natural cap; pre-aggregate large grids in SQL.
One value column per matrix.	A cell holds a single value.	Two aggregates side by side (e.g. revenue and orders per region × month) → use two matrix cards.
Heatmap colour scale is per-card.	It's anchored to that card's own min/max.	Comparing colours across two heatmap cards isn't meaningful unless they share the same value range.
Multi-metric reads the first row only.	Tiles are driven by one result row.	If the query returns multiple rows by mistake, only the first drives the tiles — add `LIMIT 1` to be explicit.
No per-tile filters on multi-metric.	Every tile sees the same single-row result.	If you want different filters per number, use separate Metric cards.

Troubleshooting¶

Symptom	What it means	Fix
"Pick row, column and value fields to build the matrix." in the card body	The matrix has no `display_config` yet	Open the card, go to Build → Pivot, fill in the three field selectors.
Heatmap cells all the same colour	All cells have the same value, or the value column is constant	Verify the query returns varied numbers. If `min == max` the gradient collapses to a single shade.
"Add at least one tile to display values."	Multi-metric card has no tiles yet	Open Build → Tiles, click Add Tile, pick a column.
Tile shows `—` instead of a number	The result column is missing or null in the first row	Verify the query returns the expected column name (case-sensitive in Databricks).
Numeric matrix renders but heatmap doesn't	`display_config.matrix_mode` is set to `numeric`	Switch the picker to Heatmap, or change Display Mode on the Format tab.