Widgets

Widgets are the visual building blocks of a dashboard. Each widget occupies a number of columns in a 12-column grid.

Common Fields

Field	Type	Required	Description
name	string	Yes	Display name
type	string	Yes	metric, chart, table, text, image, or divider
col	integer	No	Column span from 1 to 12
description	string	No	Optional tooltip or subtitle

Data-backed widgets (metric, chart, table) also need a query source: query (named query reference), sql (inline), file (external .sql path), or a semantic reference (metric: for metric widgets, dimension: + metrics: for charts). See Queries & Templating for the full reference, including the connection override.

Metric

Metric widgets display a single value.

- name: Total Revenue
  type: metric
  sql: SELECT SUM(amount) AS value FROM sales
  column: value
  prefix: "$"
  format: number
  col: 3

Metric widgets can also use semantic models:

- name: Total Revenue
  type: metric
  model: sales
  metric: revenue
  filters:
    - dimension: created_at
      operator: between
      value:
        start: "{{ filters.date_range.start }}"
        end: "{{ filters.date_range.end }}"
  prefix: "$"
  format: number
  col: 3

Semantic metric widgets inherit the dashboard-level model when model is omitted. See Semantic Layer for model files, filters, segments, and aliases.

Metric-specific fields:

Field	Type	Description
column	string	Result column to display for SQL-backed metrics
metric	string	Semantic metric name
prefix	string	Text before the value
suffix	string	Text after the value
format	string	number, currency, or percent

Chart

Charts visualize one or more series. The chart field selects the chart type and determines which fields are required.

Chart types

Chart	Required	Optional	Description
line	x, y		Line chart
bar	x, y	stacked	Bar chart
area	x, y	stacked	Area chart
pie	label, value		Pie/donut chart
scatter	x, y		Scatter plot
bubble	x, y, size		Bubble chart
combo	x, y	lines	Mixed bar + line chart (y series in lines render as lines, the rest as bars)
histogram	x	bins	Histogram (client-side binning)
boxplot	x, y		Box-and-whisker plot (client-side quartiles)
funnel	label, value		Funnel chart
sankey	source, target, value		Sankey/flow diagram
heatmap	x, y, value		Grid heatmap
calendar	x, value		GitHub-style calendar heatmap
sparkline	x, y		Compact inline line (60px), no axes
waterfall	x, y		Waterfall chart
xmr	x, y	yMin, yMax	Control chart with limits
dumbbell	x, y (2 columns)		Horizontal range comparison
gauge	value	target	Semi-circular KPI-vs-target gauge (uses first row)
treemap	label, value		Rectangular part-to-whole hierarchy
radar	x, y		Multi-axis polar comparison
candlestick	x, open, high, low, close		OHLC chart

SQL-backed example:

- name: Revenue Trend
  type: chart
  chart: area
  sql: |
    SELECT month, revenue
    FROM monthly_revenue
    ORDER BY month
  x: month
  y: [revenue]
  col: 8

Semantic example:

- name: Revenue Trend
  type: chart
  chart: area
  model: sales
  dimension: created_at
  granularity: month
  metrics: [revenue]
  sort:
    - name: created_at
      direction: asc
  col: 8

Common chart fields:

Field	Type	Description
chart	string	Chart type
x	string	X-axis column for SQL-backed charts
y	string[]	Y-axis columns for SQL-backed charts
label	string	Label column for pie, funnel, and treemap charts
value	string	Value column for pie, funnel, heatmap, calendar, treemap, and gauge charts
source	string	Source node column for sankey charts
target	string	Target/max column for gauge charts (also sankey target node)
open	string	Open column for candlestick charts
high	string	High column for candlestick charts
low	string	Low column for candlestick charts
close	string	Close column for candlestick charts
stacked	boolean	Stack series for bar and area charts
size	string	Bubble size column for bubble charts
lines	string[]	Which y series render as lines (rest as bars) for combo charts
bins	integer	Number of bins for histogram charts (default 10)
yMin	string	Lower control limit column for xmr charts
yMax	string	Upper control limit column for xmr charts
dimension	string	Semantic dimension name
granularity	string	Semantic time grain for dimension
metrics	string[]	Semantic metric names
filters	array	Semantic filters
segments	string[]	Semantic segments
sort	array	Sort instructions
limit	integer	Row limit

Charts using dimension, metrics, segments, or semantic filters are compiled through the backend semantic layer instead of requiring hand-written SQL.

Table

Tables display query results in a scrollable grid.

SQL-backed example:

- name: Recent Orders
  type: table
  sql: |
    SELECT id, customer_name, amount, status, created_at
    FROM orders
    ORDER BY created_at DESC
    LIMIT 20
  columns:
    - name: id
      label: Order ID
    - name: amount
      label: Amount
      format: currency

Semantic example:

- name: Sales Breakdown
  type: table
  model: sales
  dimensions:
    - name: region
    - name: channel
  metrics: [revenue, sales_count]
  sort:
    - name: revenue
      direction: desc
  columns:
    - name: region
      label: Region
    - name: revenue
      label: Revenue
      format: currency

Tables can mix semantic dimensions and metrics with explicit columns metadata for display labels and formatting.

Table column fields:

Field	Type	Description
name	string	Result column name (must match the SQL output)
label	string	Display header (defaults to name)
format	string	number or currency

Text

Text widgets render Markdown content.

- name: Notes
  type: text
  col: 6
  content: |
    **Important:** Data refreshes daily at 06:00 UTC.

Supported markdown:

• Headers (# through ######)
• Bold (**text**), italic (*text*), bold italic (***text***), strikethrough (~~text~~)
• Inline code (`code`)
• Links ([text](url)) and images (![alt](src))
• Unordered lists (- or *) and ordered lists (1.)
• Blockquotes (> text)
• Horizontal rules (---, ***, or ___)

Image

Image widgets render an image from a URL.

- name: Logo
  type: image
  col: 3
  src: https://example.com/logo.png
  alt: Company Logo

Image-specific fields:

Field	Type	Required	Description
src	string	Yes	Image URL
alt	string	No	Alt text for accessibility

Divider

Divider widgets add visual separation between sections.

- name: Section Break
  type: divider
  col: 12