Textplot

What you can do with one query

The shortest path from “a column of numbers” to “I can see what’s going on” — without leaving the DuckDB CLI:

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

tp_density renders the array as a one-line Unicode density plot — enough to tell whether the data is roughly normal, bimodal, or has a long tail. No notebook, no matplotlib, no BI tool round-trip. The same shape works for sparklines and threshold-colored bars in any result table:

SELECT host,
       tp_sparkline(cpu_history, theme := 'utf8_blocks', width := 24) AS cpu,
       tp_bar(disk_pct, min := 0, max := 100, width := 12,
              thresholds := [(90, 'red'), (75, 'yellow'), (0, 'green')]) AS disk
FROM hosts_status
ORDER BY disk_pct DESC;

One sparkline per row, one threshold-colored bar per row, all inline in the result table.

How it fits the CLI workflow

Every function returns a single VARCHAR. That’s the whole API: any chart you produce is just another column in the result set. It composes with .mode line, .mode markdown, log redirection, tee to a file, or paste into a status email — same as any other string column.

The companion piece for the CLI is fuzzycomplete, which fixes tab-completion for table and column names. Together they’re the two extensions worth installing for “I live in the DuckDB REPL” workflows: fuzzycomplete makes typing queries painless, textplot makes reading their output painless.

Function map

Styling vocabulary

The named-parameter surface is shared in spirit across functions:

• Shapes / styles / themes — shape := 'circle' | 'square' | 'heart' on tp_bar; named character-set styles on tp_density (shaded, ascii, dots, height, circles, rainbow_circle, …); per-mode themes on tp_sparkline (utf8_blocks, arrows, faces, slopes, …).
• Colors — on_color / off_color on tp_bar and tp_density. thresholds := [(threshold, color), ...] gives value-conditional coloring; each block uses the highest threshold it satisfies.
• Custom characters — every function with on / off accepts arbitrary strings (single chars, emoji, multi-char sequences). They’re SQL reserved words — quote them as "on" and "off".
• Width — fixed character width keeps charts aligned in tables.

Portability: ASCII vs Unicode

Defaults use Unicode block characters and emoji, which look great in modern terminals but vary by font. For maximum portability:

-- ASCII-only density plot
SELECT tp_density([1, 5, 3, 8, 2], style := 'ascii');

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

-- ASCII bar with custom characters
SELECT tp_bar(0.7, "on" := '#', "off" := '-', width := 15);

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

For QR codes specifically, .mode ascii in the CLI gives the cleanest rendering — the default table borders interact poorly with multi-line block output.

When to reach for it (and when not to)

Reach for Textplot when:

• You’re in the DuckDB CLI doing ad-hoc analysis and want to see a distribution or trend without copying values out.
• You need per-row visual cells in a result table — sparklines per host, bars per SLA, etc.
• The output goes to a terminal, log file, status email, or README.

Reach for a real charting tool when:

• You’re building an interactive web dashboard with hover/zoom/drilldown.
• You need precise pixel control for publication-quality figures.
• The audience expects polished graphics and the data deserves them.

The two are complementary, not competing — Textplot is the “I’m at a SQL prompt right now” tool.

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.