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

charts:
  bar_example:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    color: category
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:

charts:
  horizontal_bar_example:
    query: _doc_examples.yaml#sales_by_product
    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

Line Graph¶

Best for: Trends over time

charts:
  line_example:
    query: _doc_examples.yaml#sales_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

charts:
  area_example:
    query: _doc_examples.yaml#sales_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

charts:
  scatter_example:
    query: _doc_examples.yaml#sales
    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

charts:
  pie_example:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    title: Revenue by Category
    theta: revenue
    color: category
  donut_example:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    inner_radius: 0.5
    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`	Yes	Category field
`inner_radius`	No	Inner radius ratio (0–1). Use `inner_radius: 0.5` for a donut appearance.

KPI Display¶

Best for: Single metric highlights, key numbers

charts:
  revenue_kpi:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    label: Total Revenue
    value: revenue
  units_kpi:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    label: Units Sold
    value: units_sold
cols:
  - revenue_kpi
  - units_kpi

▶

Field	Required	Description
`value`	Yes	Column reference (string matching a column in the bound row) OR literal scalar (number/string) for the headline
`glyph`	No	Optional prefix glyph (e.g. `▲`, `●`) rendered ahead of the value
`tone`	No	Semantic styling — `positive` / `negative` / `neutral` / `warning`
`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 editorial notation (`1.50mn`); override `notation: bi` for the dense register

KPI charts require a query that returns exactly 1 row when value: is a column reference (e.g. SELECT SUM(revenue) as revenue). Status-style KPIs use a literal: value: "At risk".

Table¶

Best for: Detailed data view, exact values

charts:
  table_example:
    query: _doc_examples.yaml#sales
    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
Pie Charts - Detailed pie 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 href: click-through links