Chart Types

dbt Charts renders most charts through Vega-Lite, but authored chart YAML uses a typed dbt Charts surface. Choose one of the supported built-in chart types, use top-level dbt Charts fields such as x, y, color, theta, value, and href. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition blocks are rejected on the authored surface.

---

Bar Chart

Best for: Comparing values across categories

source: examples_db
charts:
  bar_example:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY week ORDER BY week
    type: bar
    title: Weekly Revenue
    x: week
    y: revenue
rows:
  - bar_example

▶

Field	Required	Description
x	Yes	Category field
y	Yes	Value field
color	No	Group by color

Horizontal Bar Chart

Use style.orientation: horizontal for horizontal bars - great for long category labels or ranked lists. When sort: is omitted, horizontal bars rank by the value field descending so the largest bar appears at the top.

source: examples_db
charts:
  horizontal_bar_example:
    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
    style:
      orientation: horizontal
rows:
  - horizontal_bar_example

▶

Style field	Value	Description
style.orientation	horizontal	Swaps x/y axes for horizontal bars

Add sort: when a horizontal bar needs a different category order.

---

Line Graph

Best for: Trends over time

source: examples_db
charts:
  line_example:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week, product ORDER BY week, product
    type: line
    title: Revenue Trend
    x: week
    y: revenue
    color: product
rows:
  - line_example

▶

Field	Required	Description
x	Yes	Time/category field
y	Yes	Value field
color	No	Series grouping

---

Area Chart

Best for: Stacked trends, showing composition over time

source: examples_db
charts:
  area_example:
    query:
      sql: |
        SELECT date, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date, category ORDER BY date, category
    type: area
    title: Revenue by Category
    x: date
    y: revenue
    color: category
rows:
  - area_example

▶

Field	Required	Description
x	Yes	Time/category field
y	Yes	Value field
color	No	Stack grouping

---

Scatter Plot

Best for: Relationships between two metrics

source: examples_db
charts:
  scatter_example:
    query:
      sql: |
        SELECT * FROM ecommerce_orders WHERE date >= DATE '2024-06-01'
    type: scatter
    title: Revenue vs Units
    x: units_sold
    y: revenue
    color: category
rows:
  - scatter_example

▶

Field	Required	Description
x	Yes	First metric
y	Yes	Second metric
color	No	Category grouping
size	No	Bubble size

---

Pie Charts

Best for: Part-to-whole relationships, proportions

source: examples_db
queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
charts:
  pie_example:
    query: sales_by_category
    type: pie
    title: Revenue by Category
    theta: revenue
    color: category
  donut_example:
    query: sales_by_category
    type: donut
    title: Units by Category
    theta: units_sold
    color: category
cols:
  - pie_example
  - donut_example

▶

Field	Required	Description
theta	Yes	Numeric value field (angle encoding)
color	No	Category field
style.inner_radius	No	Inner radius ratio (hole/outer disk, 0–1). Use type: donut as a shorthand (sets 0.6 by default).

---

KPI Display

Best for: Single metric highlights, key numbers

source: examples_db
queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
charts:
  revenue_kpi:
    query: sales_summary
    type: kpi
    label: Total Revenue
    value: revenue
  units_kpi:
    query: sales_summary
    type: kpi
    label: Units Sold
    value: units_sold
cols:
  - revenue_kpi
  - units_kpi

▶

Field	Required	Description
value	Yes	Column reference (string column name) for the headline number or text
label	No	Text rendered above the headline value (KPI uses label: instead of title:)
support	No	Trailing line with the same shape: { value, label, format, glyph, tone }
style.value.format	No	Format for the headline value. Numbers default to compact narrative notation (1.50mn); override notation: analytic for the dense register. Dates default to date_short. Since this can be a board-wide default shared across every KPI, a non-date format that doesn't fit a date-valued headline falls back to date_short there rather than erroring (a mismatched support.format errors instead, since it's always authored for that one chart)
style.glyph.character	No	Glyph character (for example, ▲, ●) rendered ahead of the value
style.value.font.color	No	Ink for the headline value and its glyph
style.label.font.color	No	Ink for the label
style.align	No	Horizontal alignment of the value, label, and support text: left (default), center, or right

KPI charts require a query that returns exactly 1 row (for example, SELECT SUM(revenue) as revenue). For status-style KPIs displaying a fixed string, use an inline values query with rows::

query:
  rows:
    - status: "On track"
value: status

---

Table

Best for: Detailed data view, exact values

source: examples_db
charts:
  table_example:
    query:
      sql: |
        SELECT * FROM ecommerce_orders
    type: table
    title: Sales Data
rows:
  - table_example

▶

Tables automatically format numbers, convert snake_case headers to Title Case, and show a "more rows" indicator when data is truncated.

---

Related

• Line Graphs - Detailed line-graph surface and Vega-Lite mapping
• Sector Charts - Detailed pie and donut surface and Vega-Lite mapping
• Maps - Choropleth, point, and bubble maps for geographic data
• More Chart Types - Heatmaps, histograms, and all Vega-Lite marks
• Charts Overview - Field reference and styling
• Interactions - Hover tooltips and link: click-through links