Heatmap

Use a heatmap to show a metric across two categorical dimensions.

Every preview on this page is generated from the YAML shown below it using a fixed documentation dataset.

Basic matrix

Provide row and column dimensions plus one metric for compact categorical intensity.

Key fields

visuals:
  state_status_heatmap:
    title: State by order status
    description: Shows order status concentration by customer state.
    type: heatmap
    query:
      type: aggregate
      dimensions:
      - state
      - status
      metrics:
      - order_count
      sort:
      - field: state
        direction: asc
      limit: 120
    presentation:
      type: cartesian
      displayUnits: none
      dataZoom: true
      labels:
        density: dense
        priority: [selected, anomaly, threshold]
        maxCharacters: 12
        minimumSpacing: 2
        tooltipFallback: true

Alternate dimensions

Replace the row dimension with product category to reuse the same matrix contract for a different categorical relationship.

Key fields

visuals:
  category_status_heatmap:
    title: Category by order status
    type: heatmap
    query:
      type: aggregate
      dimensions:
      - category
      - status
      metrics:
      - order_count
      sort:
      - field: order_count
        direction: desc
      limit: 120
    presentation:
      type: cartesian
      displayUnits: none
      dataZoom: true
      labels:
        density: dense
        priority: [selected, anomaly, threshold]
        maxCharacters: 12
        minimumSpacing: 2
        tooltipFallback: true

Cell labels

Use the renderer-neutral presentation.labels policy when exact cell values matter. automatic preserves priority labels and suppresses collisions responsively; full values remain available in tooltips.

Key fields

visuals:
  category_status_heatmap_labels:
    title: Labeled category status heatmap
    type: heatmap
    presentation:
      type: cartesian
      displayUnits: none
      dataZoom: true
      labels:
        density: dense
        priority: [selected, anomaly, threshold]
        maxCharacters: 12
        minimumSpacing: 2
        tooltipFallback: true
    query:
      type: aggregate
      dimensions:
      - category
      - status
      metrics:
      - order_count
      sort:
      - field: order_count
        direction: desc
      limit: 80

API reference

Kind: chart. Renderer: echarts. Supported result shapes: matrix_cells.

Field	Type	Default	Allowed values	Description
`query.dimensions`	`field mapping`	—	—	Groups query results and supplies category or hierarchy labels.
`query.limit`	`integer`	`no limit`	`positive integer`	Caps the number of rows returned to the renderer.
`query.metrics`	`metric mapping`	—	—	Selects governed semantic metrics consumed by the visual shape.
`query.sort`	`sort list`	—	—	Orders query results by a returned field or metric alias.
`presentation.dataZoom`	`boolean`	`false`	`true` `false`	Adds bounded zoom controls to supported Cartesian charts.
`presentation.displayUnits`	`string`	`auto`	`auto` `none` `thousands` `millions` `billions` `trillions`	Chooses one governed magnitude for the complete visual scope.
`presentation.labels`	`label policy`	`hidden`	`hidden` `automatic` `dense` `always`	Controls deterministic label density, priority, truncation, and tooltip fallback.

Accessibility. Use a descriptive title and unit, and do not rely on color alone to distinguish series or values.