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, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY date ORDER BY date
    type: bar
    title: Daily Revenue
    x: date
    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, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date, product ORDER BY date, product
    type: line
    title: Revenue Trend
    x: date
    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
    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 }
format	No	Number format. Defaults to compact narrative notation (1.50mn); override notation: analytic for the dense register
style.glyph.character	No	Glyph character (e.g. ▲, ●) rendered ahead of the value

KPI charts require a query that returns exactly 1 row (e.g. 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