Skip to content

AI tools

Insights: matrix, heatmap, and multi-metric cards

The Insights module ships three new ways to present numbers on a dashboard, on top of the existing Metric, Chart, and Table cards:

  • Matrix — a pivot table: pick a row field, a column field, a value field, and an aggregation; every unique combination becomes a cell.
  • Heatmap — the same matrix, but every cell is colour-scaled against the min/max of all values, so patterns jump out visually.
  • Multi-metric — one query, several KPI tiles in a single card; pick which numeric columns from your result become tiles.

All three work with both data sources you already know: a SQL query you write, or a published metric from the Metrics module (see Insights: backing a card with a metric).

When to choose each

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).

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

Matrix and Heatmap — how to set one up

  1. Add a card on a dashboard you can edit.
  2. 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 inside the Display tab — the underlying card type is the same.
  3. 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.
  4. Open the Display tab and configure the Pivot section:
  5. Row Field — which column becomes the row labels (e.g. region).
  6. Column Field — which column becomes the column headers (e.g. month).
  7. Value Field — the numeric column to put in each cell (e.g. revenue).
  8. Aggregation — Sum, Average, Min, Max, or Count. If your query already aggregated to one row per (row, col) combination, Sum is the right default.
  9. In the Appearance section, choose Display Mode: Numeric values (plain pivot table) or Heatmap (coloured cells).
  10. If you chose Heatmap, pick a Color Scale:
  11. Brand — neutral → brand colour. Good for "more is more" data (revenue, traffic).
  12. Success / Danger — green → red gradient. Good for "more is bad" or "less is bad" depending on context (errors, latency, churn).
  13. Info — neutral → blue. Good when you want a calm signal that doesn't read as judgemental.
  14. 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

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. If your data has a clear baseline you want to anchor against (e.g. zero), normalise in your query — the renderer doesn't know your business meaning.

Text colour inside each cell automatically switches between dark and light to stay readable against the background.

Multi-metric — how to set one up

  1. Add a card and pick Multi-metric in the type picker.
  2. 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
  3. Run the query. The Display tab will auto-seed one tile per numeric column it sees — you can drag to reorder, rename, or remove tiles.
  4. For each tile, configure:
  5. Column — which result column drives this tile's value.
  6. Label — the label shown on the tile (defaults to the column name).
  7. Format — Number, Currency, or Percent.
  8. Trend Column (optional) — pick a second column whose value renders as a delta indicator under the main value. Useful when your query computes both revenue and revenue_vs_previous_period_pct.
  9. Save. The card renders all tiles as a single row (or a 2-/3-/4-column grid depending on tile count), inside one card frame.

Why one card with many tiles instead of many cards

  • 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

  • Pivot is client-side. All matrix aggregation runs in the browser over the SQL result. The 1,000-row LIMIT enforced by every Insights query is the natural cap; large grids should pre-aggregate in SQL.
  • One value column per matrix. If you want two different aggregates side by side (e.g. revenue and orders per region/month), use two matrix cards.
  • Heatmap colour scale is per-card, anchored to that card's min/max. Comparing colours across two heatmap cards on the same dashboard isn't meaningful unless they share the same value range.
  • Multi-metric pulls values from the first row only. If your query returns multiple rows by mistake, only the first row drives the tiles. Add LIMIT 1 if you want to be explicit.
  • No per-tile filters. Every tile in a multi-metric card 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 Display → 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 Display → 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 in the Display tab.