Reference

ParQL commands

Every command supports the global flags --format, --quiet, --verbose, --threads, and --memory-limit.

parql tail

Show the last N rows.

parql tail data/sales.parquet -n 20
parql tail data/sales.parquet -c "timestamp,revenue" -n 5

parql schema

Display column names, types, and nullability.

parql schema data/sales.parquet
parql schema s3://bucket/data.parquet

parql sample

Take a random sample of rows.

parql sample data/sales.parquet --fraction 0.05
parql sample data/sales.parquet --rows 100 --seed 42

Options

  • --fraction — sample fraction (0.0–1.0)
  • --rows — exact row count
  • --seed — deterministic sampling

parql count

Count rows, optionally with a filter.

parql count data/sales.parquet
parql count data/sales.parquet -w "country = 'US'"

parql distinct

Distinct rows or distinct values for the given columns.

parql distinct data/sales.parquet -c "country,category"

parql select

Project, filter, and order — pandas-like column selection with WHERE.

parql select data/sales.parquet -c "country,revenue" -w "revenue > 100" -o "revenue DESC" -l 20
parql select data/sales.parquet --distinct -c country

parql sql

Run arbitrary SQL. Register any number of files as tables with -p.

parql sql "SELECT country, SUM(revenue) AS total FROM t GROUP BY country" \
  -p t=data/sales.parquet

parql sql "SELECT u.country, COUNT(*) AS orders
           FROM users u JOIN orders o USING (user_id) GROUP BY 1" \
  -p users=data/users.parquet -p orders=data/orders.parquet

parql agg

GROUP BY with named aggregations. Format: <expr>:<alias> comma-separated.

parql agg data/sales.parquet \
  -g "country,category" \
  -a "sum(revenue):total,count():orders,avg(price):avg_price" \
  -h "total > 10000" \
  -o "total DESC" -l 20

parql join

Join two Parquet files.

parql join data/users.parquet data/orders.parquet --on user_id --how inner
parql join data/users.parquet data/orders.parquet --on user_id --how left \
  -c "users.name,orders.amount" -l 10

parql window

Apply a SQL window function.

parql window data/events.parquet \
  --partition user_id --order ts \
  --expr "row_number() as rn"

parql window data/sales.parquet \
  --partition country --order revenue \
  --expr "rank() as rev_rank"

parql pivot

Reshape long data into wide format.

parql pivot data/sales.parquet \
  -i country -c product -v amount -f sum

parql profile

Per-column statistics: type, nulls, distinct count, numeric range, string length. Add --include-all for outlier counts and top values.

parql profile data/sales.parquet
parql profile data/sales.parquet -c "revenue,country" --include-all

parql assert

Data-quality assertions. Multiple --rule flags run in sequence; exit code is non-zero on any failure.

parql assert data/sales.parquet \
  --rule "row_count > 1000" \
  --rule "no_nulls(user_id)" \
  --rule "unique(order_id)"

# Any DuckDB boolean expression works too
parql assert data/sales.parquet --rule "revenue >= 0"

Supported rule forms

  • row_count OP N where OP ∈ {==, !=, >, <, >=, <=}
  • no_nulls(column)
  • unique(column)
  • Any other string is treated as a SQL boolean expression

parql nulls

Null count and percentage per column, or for a single column.

parql nulls data/sales.parquet
parql nulls data/sales.parquet -c email

parql outliers

Detect outliers with z-score or IQR.

parql outliers data/sales.parquet -c revenue --method zscore --threshold 3
parql outliers data/sales.parquet -c revenue --method iqr --threshold 1.5

parql compare-schema

Diff the schema of two Parquet files. Optional --fail-on-change for pipelines.

parql compare-schema data/v1.parquet data/v2.parquet
parql compare-schema data/v1.parquet data/v2.parquet --fail-on-change

parql corr

Correlation matrix (Pearson) between numeric columns.

parql corr data/sales.parquet -c "quantity,price,revenue"

parql percentiles

Detailed percentile statistics for numeric columns.

parql percentiles data/sales.parquet -c revenue
parql percentiles data/sales.parquet -c revenue --percentiles "10,50,90,99"

parql hist

Text histogram with rendered bars.

parql hist data/sales.parquet -c revenue --bins 20

parql plot

ASCII charts: histogram, bar, line, scatter.

parql plot data/sales.parquet -c revenue --chart-type hist --bins 20
parql plot data/sales.parquet -c country --chart-type bar
parql plot data/sales.parquet -c revenue -x quantity --chart-type scatter

parql str

String manipulation. Patterns and replacements are parameterized to avoid SQL injection.

parql str data/users.parquet -c name --operation upper
parql str data/users.parquet -c email --operation extract --pattern "@(.+)$"
parql str data/notes.parquet -c body --operation replace \
  --pattern "hello" --replacement "hi"

Operations

  • Case: upper, lower, title, capitalize
  • Whitespace: strip, lstrip, rstrip
  • Info: length, split
  • Regex/text: extract, replace, contains, startswith, endswith

parql pattern

Search rows by LIKE pattern or regex across text columns.

parql pattern data/logs.parquet --pattern "%error%"
parql pattern data/logs.parquet --pattern "^ERROR" --regex --case-sensitive
parql pattern data/logs.parquet --pattern "%timeout%" --count-only

parql write

Export a filtered query result to Parquet, CSV, TSV, JSON, or NDJSON.

parql write data/sales.parquet out.csv --format csv -w "country='US'"
parql write data/sales.parquet out.parquet --compression zstd

parql shell

Interactive REPL for exploratory analysis.

parql shell
parql> \l data/sales.parquet sales
parql> \l data/users.parquet users
parql> SELECT u.country, SUM(s.revenue)
       FROM users u JOIN sales s ON u.user_id = s.user_id
       GROUP BY 1;

parql config

Manage named configuration profiles.

parql config set --profile prod --threads 8 --memory-limit 16GB
parql config show --profile prod
parql config unset --profile prod threads

parql cache

Inspect and clear the query cache. Cached results are stored as Parquet under ~/.parql/cache.

parql cache info
parql cache clear

Something missing? Open an issue on GitHub — we ship monthly.