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
200,000400,000600,000800,0001,000,0001,200,000RevenueRevenue by Region and CategoryEastNorthSouthWestAccessoriesElectronicsTools Data as of 14:25 UTC on 6 Oct 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.

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
05001k1.5k2k2.5k3k3.5k02004006008001k1.2k1.4k1.6k1.8k2kCountRevenue Distribution Data as of 14:25 UTC on 6 Oct 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 none
pie / donut theta, color style.inner_radius
histogram x color
kpi value label, support, format, href
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

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.