scoresql

Analyze a SQL query against CSV file caches (stats, moarstats, frequency) to produce a performance score with actionable optimization suggestions BEFORE running the query. Supports Polars (default) and DuckDB modes.

Table of Contents | Source: src/cmd/scoresql.rs | 🐻‍❄️🪄

Description | Examples | Usage | Scoresql Options | Common Options

Description ↩

Analyze a SQL query against CSV file caches (stats, moarstats, frequency) to produce a performance score with actionable optimization suggestions BEFORE running the query.

Accepts the same input/SQL arguments as sqlp. Outputs a human-readable performance report (default) or JSON (--json). Supports Polars mode (default) and DuckDB mode (--duckdb).

Scoring factors include:

• Query plan analysis (EXPLAIN output from Polars or DuckDB)
• Type optimization (column types vs. usage in query)
• Join key cardinality and data distribution
• Filter selectivity from frequency cache
• Query anti-pattern detection (SELECT *, missing LIMIT, cartesian joins, etc.)
• Infrastructure checks (index files, cache freshness)

Caches are auto-generated when missing:

• stats cache via qsv stats --everything --stats-jsonl
• frequency cache via qsv frequency --frequency-jsonl

Examples ↩

Score a simple filter query against a single CSV file

qsv scoresql data.csv "SELECT * FROM data WHERE col1 > 10"

Output the score report as JSON instead of the default human-readable format

qsv scoresql --json data.csv "SELECT col1, col2 FROM data ORDER BY col1"

Score a join query across two CSV files

qsv scoresql data.csv data2.csv "SELECT * FROM data JOIN data2 ON data.id = data2.id"

Use DuckDB for query plan analysis instead of Polars

qsv scoresql --duckdb data.csv "SELECT * FROM data WHERE status = 'active'"

Use _t_N aliases just like sqlp (see sqlp documentation)

qsv scoresql data.csv data2.csv "SELECT * FROM _t_1 JOIN _t_2 ON _t_1.id = _t_2.id"

Score a query from a SQL script file (only the last query is scored)

qsv scoresql data.csv script.sql

For more examples, see tests.

See also https://github.com/dathere/qsv/wiki/SQL-and-Polars#scoresql

Usage ↩

qsv scoresql [options] <input>... <sql>
qsv scoresql --help

Scoresql Options ↩

Option	Type	Description	Default
‑‑json	flag	Output results as JSON instead of human-readable report.
‑‑duckdb	flag	Use DuckDB for query plan analysis instead of Polars. Uses the QSV_DUCKDB_PATH environment variable if set, otherwise looks for "duckdb" in PATH.
‑‑try‑parsedates	flag	Automatically try to parse dates/datetimes and time.
‑‑infer‑len	integer	Number of rows to scan when inferring schema.	10000
‑‑ignore‑errors	flag	Ignore errors when parsing CSVs.
‑‑truncate‑ragged‑lines	flag	Truncate lines with more fields than the header.

Common Options ↩

Option	Type	Description	Default
‑h, ‑‑help	flag	Display this message
‑o, ‑‑output	string	Write output to instead of stdout.
‑d, ‑‑delimiter	string	The field delimiter for reading CSV data. Must be a single character.	,
‑q, ‑‑quiet	flag	Do not print informational messages to stderr.

---

Source: src/cmd/scoresql.rs | Table of Contents | README