User Guide¶

Your daily reference for using BenchBox. This section covers configuration, running benchmarks, and understanding results.

Quick Links¶

Task	Guide
Configure BenchBox	Configuration
Generate test data	Data Generation
Preview before running	Dry Run
Find example scripts	Examples Directory
Understand your results	Understanding Results
Fix common issues	Troubleshooting

Configuration¶

Configuration Guide - YAML layouts, environment overrides, and precedence rules
Intelligent Guidance - How the CLI adapts to your hardware profile

Running Benchmarks¶

Data Generation - Generating benchmark datasets at various scales
Dry Run - Preview queries and configuration without executing
Dialect Translation - SQL dialect translation vs platform adapters

Examples¶

Examples Directory - 40+ runnable examples organized by difficulty
Code Snippets - Inline Python and shell examples
Example Scripts - Categorized example scripts

Help & Support¶

FAQ - Frequently asked questions
Troubleshooting - Common issues and solutions

Concepts¶

Core concepts for understanding BenchBox:

Concepts Overview - Architecture, workflow, and terminology
Glossary - Terms and definitions
Data Model - Data structures and relationships

Next Steps¶

Run benchbox profile to capture a baseline system profile
Pick a platform with benchbox platforms list
Execute a benchmark: benchbox run --platform duckdb --benchmark tpch --scale 0.01
View results: benchbox results --limit 1