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
Cloud Sorted Ingestion - Opt-in deep sorting strategy for cloud DW comparisons
TPC Logical Tuning Profiles - Tuned-template profile coverage and comparison semantics
Databricks Liquid Clustering - Strategy control and migration from Z-ORDER

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

Getting Started - First-time setup
CLI Reference - Complete command documentation
Guides - Task-oriented how-to guides