Textplot

Recipes for inline ASCII / Unicode plots in the DuckDB CLI — distributions, trends, bars, and QR codes that live as VARCHAR columns in your SELECT output.

See the shape of a column

The headline use — point an aggregate at tp_density and you’ve got a one-line distribution plot in CLI output:

SELECT tp_density(array_agg(value)) AS distribution
FROM measurements;

For a wider plot or a different character set:

SELECT tp_density(array_agg(value), width := 40, style := 'height') AS distribution
FROM measurements;

Available styles: shaded (default), ascii, dots, height, circles, safety, rainbow_circle, rainbow_square, moon, sparse, white. See tp_density for the full parameter list.

Sparkline per row in a status table

The pattern that makes tp_sparkline most useful — pre-aggregate a series per entity, render a sparkline cell:

SELECT host,
       tp_sparkline(cpu_history, theme := 'utf8_blocks', width := 24) AS cpu_24h
FROM hosts_status
ORDER BY host;

Three modes change what the sparkline encodes:

-- Absolute mode (default) — height ∝ value
SELECT tp_sparkline([45.2, 47.1, 46.8, 49.3, 52.1, 48.7]);

-- Delta mode — direction of change between consecutive points
SELECT tp_sparkline([100, 105, 102, 108, 95], mode := 'delta');

-- Trend mode — direction with magnitude
SELECT tp_sparkline([100, 110, 105, 125, 90], mode := 'trend', theme := 'intensity');

Threshold-colored health bars

tp_bar with a thresholds list is the natural shape for SLA, disk-utilization, or risk indicators. Each block adopts the highest threshold ≤ value:

SELECT host,
       disk_pct,
       tp_bar(disk_pct, min := 0, max := 100, width := 14,
              thresholds := [
                {'threshold': 90, 'color': 'red'},
                {'threshold': 75, 'color': 'yellow'},
                {'threshold':  0, 'color': 'green'}
              ]) AS disk
FROM hosts_status
ORDER BY disk_pct DESC;

Sort by the underlying number; let the bar carry the visual.

ASCII output for portable terminals

When the destination doesn’t render emoji or wide Unicode reliably (older terminals, log aggregators, plain-text email), pin every function to its ASCII vocabulary:

-- Density
SELECT tp_density([1, 5, 3, 8, 2], style := 'ascii');

-- Sparkline
SELECT tp_sparkline([1, 3, 2, 5, 4, 6], theme := 'ascii_basic');

-- Bar with custom characters ("on" / "off" are reserved — quote them)
SELECT tp_bar(0.7, "on" := '#', "off" := '-', width := 15);

-- QR code in ASCII blocks
SELECT tp_qr('https://query.farm', "on" := '##', "off" := '  ');

Per-row charts on a generated series

Useful when you’re prototyping or want to demo the styling vocabulary without a real dataset:

SELECT round(n, 4) AS value,
       tp_bar(n,
              width := 14,
              shape := 'circle',
              off_color := 'black',
              filled := true,
              thresholds := [
                (0.8, 'red'), (0.7, 'orange'), (0.6, 'yellow'), (0.0, 'green')
              ]) AS bar
FROM (SELECT random() AS n FROM generate_series(1, 10));

QR codes for terminal output

-- Default monochrome
SELECT tp_qr('Hello, World!');

-- High error correction (more redundancy, slightly larger code)
SELECT tp_qr('https://query.farm', ecc := 'high');

-- Custom emoji styling
SELECT tp_qr('https://query.farm', ecc := 'high', "on" := '🟡', "off" := '⚫');

In the DuckDB CLI, .mode ascii gives the cleanest rendering of QR output — the default table borders interact poorly with the multi-line block grid.

Pair with fuzzycomplete for a CLI-first workflow

Textplot makes CLI output readable; fuzzycomplete makes CLI input tolerable (VS-Code-style fuzzy tab-completion across schemas and databases). Install both if you live in the DuckDB REPL:

INSTALL fuzzycomplete FROM community;
LOAD fuzzycomplete;

INSTALL textplot FROM community;
LOAD textplot;

Tips

1. Pick widths to match your output — width 20–30 for dashboards, 10–15 for compact reports, ≥40 for distribution shapes you want to actually read.
2. Combine with raw numbers, don’t replace them — the visual is for shape; the number is for precision. Show both.
3. Sparklines shine in tables — one cell per row is where they earn their keep.
4. ASCII for portability, emoji for impact — emoji needs a Unicode-capable terminal and font.
5. For real visualization, use a real tool — Textplot is for eyeballing in the CLI, not for the dashboard you ship to stakeholders.