Chart Generation Guide

This guide walks you through generating charts from BenchBox benchmark results. Whether you’re inspecting results in a terminal, creating CI summaries, or comparing platforms, this guide covers the end-to-end workflow.

Prerequisites

No additional dependencies are required. BenchBox visualization is built entirely on the Python standard library and renders directly to the terminal.

Verify Installation

benchbox visualize --help

Quick Start

Generate Charts from Latest Result

benchbox visualize

This auto-detects the most recent result in benchmark_runs/results/ and generates default charts.

See Chart Types for examples of each chart type.

Generate from Specific Results

benchbox visualize benchmark_runs/results/tpch_duckdb_sf1.json

Compare Multiple Platforms

benchbox visualize duckdb.json snowflake.json bigquery.json

Workflow by Content Type

Flagship Analysis (Multi-Platform Comparison)

For comprehensive “State of the Data Warehouse” style analysis:

benchbox visualize results/*.json --template flagship

Generates:

Performance bar chart (platform comparison)
Query variance heatmap (per-query analysis)
Cost-performance scatter (ROI analysis, if cost data available)
Distribution box plot (consistency analysis)

Head-to-Head Comparison

For “DuckDB vs Snowflake” style comparisons:

benchbox visualize duckdb.json snowflake.json --template head_to_head

Generates:

Performance bar chart (side-by-side comparison)
Distribution box plot (consistency comparison)
Query variance heatmap (per-query winners)

Performance Trend Analysis

For tracking performance over time:

benchbox visualize runs/2024/*.json runs/2025/*.json --template trends

Generates:

Time-series line chart
Latest snapshot bar chart

Cost Optimization Analysis

For ROI and cost analysis:

benchbox visualize cloud_results/*.json --template cost_optimization

Generates:

Cost-performance scatter
Performance comparison bar chart

Smart Chart Selection

When no template or specific chart types are specified, --chart-type auto (the default) renders all supported chart types based on the available data:

Data Characteristics	Charts Generated
Single platform	Query breakdown bar + distribution box
Multiple platforms	Platform comparison bar + heatmap
Cost data present	Adds cost-performance scatter
Multiple timestamps	Adds time-series trend

benchbox visualize results/*.json

benchbox visualize results/*.json --chart-type performance_bar

The first command lets BenchBox decide which charts to generate. The second generates specific charts only.

Display Options

Dark Theme

benchbox visualize results/*.json --theme dark

Pipe-Friendly Output

benchbox visualize results/*.json --no-color > charts.txt

benchbox visualize results/*.json --no-unicode

--no-color strips ANSI colors for file output. --no-unicode uses ASCII-only characters for basic terminals.

Specific Chart Types

benchbox visualize results/*.json --chart-type performance_bar,cost_scatter

Troubleshooting

Empty or Missing Charts

Check that your result JSON includes the required fields:

Performance bar: total_time_ms or avg_time_ms
Distribution box: per-query execution_time_ms values
Heatmap: At least 2 platforms with query-level timings
Cost scatter: cost_summary.total_cost

“No result sources provided”

Either specify files explicitly or ensure benchmark_runs/results/ contains JSON files:

benchbox visualize benchmark_runs/results/my_result.json

Charts Look Different Than Expected

Check --theme setting (light vs dark)
Ensure you’re using the intended --template
Verify terminal supports Unicode if using block characters (try --no-unicode as a fallback)

Best Practices

Use templates for consistent chart sets across analyses
Use --no-color when piping output to files
Name output files clearly when saving (> comparison-2025-q1.txt)
Keep source JSON files for reproducibility
Use MCP tools for programmatic chart generation in AI workflows

Next Steps

Chart Types - Understand each chart type in detail
Templates - Learn about predefined templates
Customization - Fine-tune colors, themes, and styling
CLI Reference - Complete command reference