Chart Types¶

Dataface renders most charts through Vega-Lite, but authored chart YAML uses a typed Dataface surface. Choose one of the supported built-in chart types, use top-level Dataface 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
`style.tone`	No	Semantic color — `positive` / `negative` / `warning`

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.

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