Common Properties

All chart types share these properties:

PropertyTypeDescription
typestringChart type: number, line, bar, pie, or table
namestringUnique identifier for the chart
titlestringDisplay title
descriptionstringOptional description
querystringSQL query that provides chart data

Number Charts

Number charts display a single metric value, often used for KPIs.

- type: number
  name: total_sales
  title: "Total Sales"
  query: "SELECT sum(amount) as total FROM sales"
  metrics:
    - name: total
      label: Total Sales
  metric_format: "$0,0.00"

Line Charts

Line charts visualize trends over time or continuous data.

- type: line
  name: sales_trend
  title: "Sales Trend"
  query: "SELECT date, sum(amount) as total FROM sales GROUP BY date ORDER BY date"
  dimensions:
    - name: date
      label: Date
  metrics:
    - name: total
      label: Daily Sales

Bar Charts

Bar charts compare values across categories.

- type: bar
  name: sales_by_category
  title: "Sales by Category"
  query: "SELECT category, sum(amount) as total FROM sales GROUP BY category ORDER BY total DESC"
  dimensions:
    - name: category
      label: Category
  metrics:
    - name: total
      label: Total Sales
  show_labels: true

Pie Charts

Pie charts show part-to-whole relationships.

- type: pie
  name: sales_distribution
  title: "Sales Distribution"
  query: "SELECT category, sum(amount) as total FROM sales GROUP BY category"
  dimensions:
    - name: category
      label: Category
  metrics:
    - name: total
      label: Total Sales

Table Charts

Table charts display raw data in tabular format.

- type: table
  name: recent_orders
  title: "Recent Orders"
  description: "Last 100 orders placed"
  query: "SELECT * FROM orders ORDER BY date DESC LIMIT 100"

Formatting

Use metric_format to control how numbers are displayed:

FormatExampleResult
"0,0"1234”1,234”
"$0,0.00"1234.5”$1,234.50”
"0.0%"0.123”12.3%“
"0.00a"1234”1.23k”

Advanced Features

Multi-Series Charts

For line and bar charts, you can include multiple metrics:

- type: line
  name: revenue_vs_cost
  title: "Revenue vs Cost"
  query: "SELECT date, sum(revenue) as rev, sum(cost) as cost FROM financials GROUP BY date"
  dimensions:
    - name: date
      label: Date
  metrics:
    - name: rev
      label: Revenue
    - name: cost
      label: Cost