Skip to content

Charts

Charts visualize your query data. Each chart references a query and defines how to display it.

Vega-Lite foundation: Charts render through Vega-Lite, but authored chart YAML is a typed dbt Charts surface. Use top-level dbt Charts fields (x, y, color, lookup, value, etc.) and the typed style object exclusively. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition (hconcat/vconcat/concat/repeat/resolve) blocks are rejected on the authored surface.

A chart's control surface is the full set of authored properties available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus the typed style object.


Basic Chart Structure

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: queries.sales          # References a query name
    type: bar                     # Chart type
    x: month                      # X-axis dimension
    y: total_revenue              # Y-axis metric

Here's a working example:

source: examples_db
charts:
  revenue_chart:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - revenue_chart
Revenue by Product00.5m1m1.5mWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Naming no channels

A chart that names none of its channels binds the query's columns by position, the way the query was written: dimensions first, the measure last.

charts:
  revenue_chart:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: bar
    title: Revenue by Category
rows:
  - revenue_chart
Type 1 column 2 columns 3 columns
bar, line, area x, y x, color, y
scatter x, y color, x, y
heatmap x, y, color
pie, donut theta color, theta
kpi value
histogram x

The binding reads column order only, never a column's name or type: a text column in the measure slot fails the same way an explicit y: naming it would. Any other column count is an error naming the columns, and so is naming some channels but not the rest (a y with no x). A field that names a column outside the set (layers, y_start, connect, multiples, tooltip) counts as naming one: a chart that sets it names its channels, and so does a chart whose sort, support_table or own mark labels.field (not one a board or theme cascades onto it) names a column other than the measure once a third column fills color. A chart with no query has no columns to bind, so it names its channels or gets a query:; a pie, donut or kpi needs only its theta: or value:.

Keep a shorthand chart's query inline, as above: its select list is then the chart's mapping, read in one place. A chart over a query that other charts share names its channels, since a column added for one chart re-binds every shorthand chart on that query.


Common Chart Types

Type Best For
line Time series trends
bar Comparisons across categories
area Stacked trends over time
scatter Relationships between metrics
pie / donut Part-to-whole comparisons
heatmap Two-dimensional patterns
histogram Distributions
funnel Stages of one process, first to last (Funnels)
table Detailed data view
kpi Single metric display
callout Status or warning message card
map Geographic region maps
point_map Location markers
bubble_map Sized location markers

Every built-in type, the shapes that compose from them, and what to do when a shape is missing: Chart types and extensibility.

See also: Bar Charts • Line Graphs • Sector Charts • Point Charts • Area Charts • Layered Charts • Maps • Tables and Text


Field Reference

charts:
  <chart_id>:              # Unique identifier (must be unique within a file and across all imported files)
    title: string          # Optional
    query: string          # Required
    type: string           # Required (bar, line, area, etc.)

    # Channel fields
    x: string              # Dimension for x-axis
    y: string | [string]   # Metric(s) for y-axis
    color: string          # Field to encode as color
    size: string           # Field to encode as size
    shape: string          # Field to encode as shape

    # KPI-specific
    value: string          # KPI value binding or map fill field (column reference)
    label: string         # KPI label above the value

    # Map-specific
    geo_source: string     # Built-in geographic data source
    lookup: string         # Query field to join to geography
    latitude: string       # Point/bubble map latitude field
    longitude: string      # Point/bubble map longitude field

    # Data and links
    sort:
      by: string
      order: asc | desc
    link: string           # URL template for drill-down links ({{ x }}, {{ y }}, etc.)

    # Chart-specific presentation
    style:
      color:
        categorical:
          palette: string                # Named categorical palette
      background: string                 # Chart SVG background fill
      legend:
        visible: boolean                 # false to hide legend
      axis:
        grid:
          visible: boolean               # false to hide gridlines
      orientation: horizontal | vertical  # Bar chart orientation
      stack: none | zero | normalize | center  # Stack mode
      columns:
        column_name: {}                   # Table column config (mapping key = column name)
      # Axis, scale, legend, mark, and other style sections...

    notes: string    # AI search/context metadata; never rendered

Row limiting belongs on the query (queries.<id>.limit), not on the chart.


Chart Sizing

Three fields control a chart's preferred geometry. height and width live at chart root, directly under charts.<name>:; aspect_ratio is a style field, under the chart's style:.

charts:
  revenue_trend:
    query: revenue
    type: bar
    x: month
    y: total
    height: 400          # exact pixel height; wins over aspect_ratio and theme

  wide_chart:
    query: revenue
    type: line
    x: month
    y: total
    width: 800           # preferred dashboard width; the layout may allocate less
    style:
      aspect_ratio: 3.0  # wider than default; height = width / 3.0
  • height: fixes the pixel height exactly. Bypasses min_height/max_height clamps. Not supported on kpi, table, callout, or spark_bar.
  • width: pins the chart's slot in a rows: layout (a fixed footprint, capped at the row). In cols: and grid: layouts it requests an intrinsic width for dashboard measurement on boards with no width of their own; the layout still owns the final slot allocation.
  • style.aspect_ratio: controls shape without pinning a size. The theme default is 1.5 (3:2 landscape). Not supported on the same chart types as height. The theme-level form style.charts.kpi.aspect_ratio is also rejected; the per-type theme override is unsupported on kpi, table, callout, and spark_bar.

The dashboard combines preferred widths recursively: rows and tabs use the widest child, while columns add child widths and gaps. A root width: is the board's exact width wherever it is authored; without one, style.frame.max_width is the maximum the content hug can grow to. Layout rules still own the final chart allocation.

See Board Sizing for the full three-layer model (layout tile → chart root → theme default) and guidance on when to use each layer.


Chart Styling

Customize chart appearance:

charts:
  styled_chart:
    query: sales
    type: bar
    x: month
    y: total_revenue
    style:
      color:
        categorical:
          palette: editorial-10   # Color palette
      legend:
        visible: true             # Show legend (default)
      axis:
        grid:
          visible: true            # Show gridlines
      background: "#f8fafc"       # Chart background fill

Style options: - color.categorical.palette: Color palette name (for example, editorial-10, vivid-10, dbt-seq-blue; see the Palettes guide) - legend.visible: false to hide the legend - axis.grid.visible: false to hide gridlines - background: SVG/CSS-compatible background fill applied behind the chart

See Themes for the built-in themes, and Styling for color palettes.

Value Labels

Bar, line, and scatter charts can show the numeric value on each mark. Enable per-chart via the family marks path:

style:
  bar:           # or line: / scatter:
    marks:
      bar:       # or line: / point:
        labels:
          visible: true     # show value above each bar
          position: top     # above | top | middle | middle_aligned | bottom (bar); top | bottom | left | right | middle (line/point)

format defaults to null (inherits from axis_y format). Set a d3-format string to override. See per-chart docs for the full field list: Bar Charts · Line Graphs · Point Charts.


Best Practices

Choosing Chart Types

  • Time series: Use line or area
  • Comparisons: Use bar
  • Relationships: Use scatter
  • Single numbers: Use kpi
  • Detailed data: Use table

Effective Color Encoding

  • Use color to distinguish categories
  • Choose accessible palettes (colorblind-friendly)
  • Limit distinct colors (5-7 max)

Filtering

  • Use variables with dropdowns for cross-chart filtering
  • Tooltips appear automatically on hover

See Interactions for hover tooltips and link: drill-down links.


Previewing Charts

Preview your charts interactively:

dct serve

dct serve auto-discovers the project and prints the URL on startup. See CLI Reference.

Validate First

dct validate charts/sales.yml

  • Bar Charts - Comparison-first charts and columns
  • Line Graphs - Line-graph style, examples, Vega-Lite mapping, and gaps
  • Sector Charts - Pie, donut, and related arc-based charts
  • Point Charts - Dot plots, scatterplots, and other point-based charts
  • Area Charts - Filled trend and composition charts
  • Layered Charts - Combo charts and dual-axis charts
  • Annotations - Rules, bands, notes, and trends drawn on a chart
  • Maps - Geographic charts and projection-aware mapping
  • Tables and Text - Exact-value tables, KPIs, and other data-powered text outputs
  • Interactions - Hover tooltips and link: drill-down links
  • Queries - Data sources for charts
  • Boards - Organizing charts in dashboards
  • Variables - Variables in query filters and inputs
  • Themes - The built-in themes and how to write your own
  • Styling - Color palettes and the rest of the style surface