Spark Charts (Sparklines)¶

Spark charts are compact, inline visualizations that appear within table cells. They enable showing trends, distributions, or comparisons at a glance without requiring separate charts.

Overview¶

Spark charts are specified using the spark: key in table column configurations. They support both a shorthand syntax (just the type) and a full syntax (with options).

Quick Example¶

charts:
  sales_table:
    type: table
    query: regional_data
    settings:
      columns:
        - field: region
        - field: monthly_trend
          spark: line              # Shorthand syntax
        - field: quota_pct
          spark:                   # Full syntax with options
            type: progress
            color: green
            max: 100

Spark Types¶

Line Sparkline (`line`)¶

Classic sparkline showing trend over time. Best for time series data.

spark:
  type: line
  color: "#3b82f6"    # Optional: line color
  show_last: true     # Optional: show dot on last value
  show_min_max: true  # Optional: show dots on min/max values

Data Format: Array of numeric values

-- DuckDB/PostgreSQL
SELECT
  region,
  ARRAY_AGG(monthly_sales ORDER BY month) as trend
FROM sales
GROUP BY region

Area Sparkline (`area`)¶

Filled sparkline that emphasizes magnitude. Good for volume metrics.

spark:
  type: area
  color: "#06b6d4"
  fill_opacity: 0.3   # Optional: fill transparency (0-1)
  show_last: true     # Optional: show dot on last value

Data Format: Array of numeric values (same as line)

Bar Sparkline (`bars`)¶

Vertical bars for discrete value comparison.

spark:
  type: bars
  color: "#8b5cf6"

Data Format: Array of numeric values

Progress Bar (`progress`)¶

Horizontal progress bar showing completion towards a goal.

spark:
  type: progress
  max: 100            # Maximum value (default: 100)
  color: "#22c55e"    # Optional: bar color
  thresholds:         # Optional: color by value
    0: "#ef4444"      # Red for 0-70%
    70: "#f59e0b"     # Yellow for 70-85%
    85: "#22c55e"     # Green for 85%+

Data Format: Single numeric value (0 to max)

Histogram (`histogram`)¶

Distribution visualization showing value frequency.

spark:
  type: histogram
  color: "#3b82f6"
  bins: 5             # Optional: number of bins

Data Format: Array of values to bin

YAML Syntax¶

Shorthand Syntax¶

For simple cases where defaults are acceptable:

columns:
  - field: trend_data
    spark: line       # Just specify the type

Full Syntax¶

For customizing appearance:

columns:
  - field: trend_data
    spark:
      type: line
      color: "#3b82f6"
      width: 80
      height: 24
      show_last: true

Options Reference¶

Common Options (All Types)¶

Option	Type	Default	Description
`type`	string	`"line"`	Spark chart type
`color`	string	`"#3b82f6"`	Primary color (CSS)
`width`	int	80/100	Width in pixels
`height`	int	24/16	Height in pixels

Line/Area Options¶

Option	Type	Default	Description
`show_last`	bool	`false`	Show dot on last value
`show_min_max`	bool	`false`	Show dots on min/max
`fill_opacity`	float	`0.3`	Area fill opacity (area only)

Progress Options¶

Option	Type	Default	Description
`max`	float	`100`	Maximum value
`thresholds`	dict	`null`	Color thresholds

Preparing Data¶

Spark charts require pre-aggregated data. Each row should contain the array or value for the spark column.

DuckDB / PostgreSQL¶

SELECT
  region,
  SUM(sales) as total_sales,
  ARRAY_AGG(monthly_sales ORDER BY month) as monthly_trend,
  (SUM(sales) / quota * 100)::int as quota_pct
FROM sales
JOIN quotas USING (region)
GROUP BY region, quota

Snowflake¶

SELECT
  region,
  SUM(sales) as total_sales,
  ARRAY_AGG(monthly_sales) WITHIN GROUP (ORDER BY month) as monthly_trend
FROM sales
GROUP BY region

BigQuery¶

SELECT
  region,
  SUM(sales) as total_sales,
  ARRAY_AGG(monthly_sales ORDER BY month) as monthly_trend
FROM sales
GROUP BY region

Complete Example¶

title: Regional Performance Dashboard

queries:
  regional_data:
    sql: |
      SELECT
        region,
        total_sales,
        quota_pct,
        ARRAY_AGG(monthly_sales ORDER BY month) as monthly_trend
      FROM regional_metrics
      GROUP BY region, total_sales, quota_pct
    source: analytics_db

charts:
  performance_table:
    type: table
    query: regional_data
    title: Regional Performance
    settings:
      columns:
        - field: region
          label: Region
        - field: total_sales
          label: Total Sales
          format: "$,.0f"
        - field: quota_pct
          label: Quota
          spark:
            type: progress
            max: 100
            thresholds:
              0: "#ef4444"
              70: "#f59e0b"
              85: "#22c55e"
        - field: monthly_trend
          label: 6-Month Trend
          spark:
            type: line
            color: "#3b82f6"
            show_last: true

rows:
  - performance_table

Best Practices¶

Keep it simple: Sparklines work best for showing general trends, not precise values
Use consistent colors: Match spark colors to your dashboard theme
Order data correctly: For time series, ensure arrays are ordered chronologically
Cap array sizes: Too many points make sparklines hard to read (10-30 is ideal)
Use thresholds wisely: Progress bar thresholds help quickly identify status