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
0500k1,000k1,500kWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget ZRevenue by Product Data as of 14:24 UTC on 6 Oct 2026 made withdbt Charts
▶

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
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 grid lines
      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 style.frame.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 grid lines
      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 grid lines - 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
  • 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