Chart Types¶

Dataface renders charts using Vega-Lite. All Vega-Lite chart types are supported and passed through directly.

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 settings.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
    settings:
      orientation: horizontal
rows:
  - horizontal_bar_example

▶

Setting	Value	Description
`settings.orientation`	`horizontal`	Swaps x/y axes for horizontal bars

Line Chart¶

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

Rendering Error
Failed to render dataface: Query execution failed: DuckDB SQL execution failed: Catalog Error: Table with name sales does not exist! Did you mean "sqlite_master"? LINE 1: SELECT * FROM sales ^ (query: _doc_examples.yaml#sales)

▶

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

Pie & Donut 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: 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`	Yes	Category field

Use donut for a hollow center (good for placing a label or KPI).

KPI Display¶

Best for: Single metric highlights, key numbers

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

▶

Field	Required	Description
`metric`	Yes	Field to display as a big number

KPI charts require a query that returns exactly 1 row (e.g. SELECT SUM(revenue) as revenue).

Table¶

Best for: Detailed data view, exact values

charts:
  table_example:
    query: _doc_examples.yaml#sales
    type: table
    title: Sales Data
rows:
  - table_example