Skip to content

More Chart Types

Beyond the common charts, dbt Charts supports a fixed set of authored built-in chart types. Arbitrary Vega-Lite mark, encoding, spec, config, transform, params, and composition blocks are not part of the authored dbt Charts schema.


Heatmap

Best for: Two-dimensional patterns, matrix data

source: examples_db
charts:
  heatmap_example:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue
        FROM ecommerce_orders
        GROUP BY region, category
        ORDER BY region, category
    type: heatmap
    title: Revenue by Region and Category
    x: region
    y: category
    color: revenue
rows:
  - heatmap_example
Revenue by Region and CategoryEastNorthSouthWestAccessoriesElectronicsToolsRevenue200,000400,000600,000800,0001,000,0001,200,000 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶
Field Required Description
x Yes Column categories
y Yes Row categories
color Yes Value to color by

Both axes default to the query's own row order. An authored sort: reorders both the columns and the rows together: a heatmap has no way to sort one axis without the other.


Conditional styling

style.conditional restyles a cell by the value in its own row. It maps a column name to a list of rules. Each rule is one condition (eq, ne, lt, lte, gt, gte, between, in, is_null, or default) plus the part of the chart style it applies:

type: heatmap
x: day
y: hour
color: visits
style:
  conditional:
    visits:
      - gte: 90
        marks:
          rect:
            stroke:
              color: "#c62828"
              width: 3

A rule can set only what varies per cell:

Field Sets
marks.rect.color The cell's fill
marks.rect.opacity The fill opacity
marks.rect.stroke.color, marks.rect.stroke.width The cell's outline
axis_x.labels.font.color The category x-axis labels the rule matches (Conditional label colors)

A stroke width needs a stroke color, from the rule or from marks.rect.stroke. A heatmap draws no cell text, so marks.text in a rule is refused, as is anything else that does not vary per cell.

  • Every matching rule applies, and where two set the same field the later one wins, so list the more specific rule last.
  • A default: true rule must be last and applies only when no other rule matched.
  • The column must be in the query result. Rules on two columns cannot set the same field.
  • A rule's color replaces the color: channel's color for the matched cell only; the legend is unchanged.
  • conditional is authored on the chart's own style; at style.charts.heatmap it is refused.

Histogram

Best for: Distribution of continuous values

source: examples_db
charts:
  histogram_example:
    query:
      sql: |
        SELECT * FROM ecommerce_orders
    type: histogram
    title: Revenue Distribution
    x: revenue
rows:
  - histogram_example
Revenue Distribution05001,0001,5002,0002,5003,0003,50002004006008001,0001,2001,4001,6001,8002,000# Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶
Field Required Description
x Yes Continuous field to bin
color No Category grouping

Histograms automatically bin the x-axis values.


Supported Built-In Types

Use type with one of the built-in names below. Unknown chart type names fail validation.

Type Description Use Case
bar Bar chart Category comparisons
histogram Auto-binned bar chart Distributions
line Line chart Time series
area Area chart Stacked trends
scatter Scatter plot Scatter plots
heatmap Color-coded matrix Density, calendars
pie Pie chart Part-to-whole
donut Pie with inner radius Part-to-whole
kpi Single-value indicator Big numbers
table Tabular display Detailed values
geoshape Geographic shapes Maps
map Filled region map State/country metrics
point_map Location markers Plotting locations
bubble_map Sized markers Location + magnitude
callout Annotated value Highlighted measure
spark_bar Inline mini bar chart Compact trends

Vega-Lite mark names such as boxplot, errorbar, errorband, tick, rect, rule, text, trail, circle, square, image, and arc are not accepted as authored chart type values.


Input Requirements

Quick reference for what each chart type needs:

Type Required Optional
bar x, y color, size
line x, y color
area x, y color
scatter x, y color, size, shape
heatmap x, y color (the measure; without it every cell is one color), pattern
pie / donut theta color, style.inner_radius
histogram x color
kpi value label, glyph, support, style.variant, style.value.format
table none none
geoshape / map Usually geo or geo_source lookup, value, color, projection
point_map / bubble_map Usually latitude, longitude size, color, projection
callout message title, style.tone
spark_bar x, y style.max_bars

The required channels are named together, or not at all: a chart naming none of them binds its query's columns by position (see Naming no channels).


Overlays and Mixed-Mark Charts

The cartesian chart families (bar, line, area, scatter) accept a layers: field for mixed-mark or dual-axis compositions. layers: is not a chart type; it is a field on a base chart.

charts:
  revenue_vs_target:
    type: bar
    x: month
    y: revenue
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
        axis_y:
          position: right
        style:
          marks:
            line:
              stroke:
                width: 2

A layer on its own axis gets an independent scale; see Dual y-axis for why dbt Charts warns about it and what to use instead.

The base chart owns the x-axis, frame, title, legend, and sort order. Each layer contributes its mark, its own y-axis side, and its own legend entry. See Bar Charts, Line Graphs, and Area Charts for full layers: examples.