A dashboard is a short file
source blocks name data files, query blocks hold SQL, and plot blocks say how to draw each result. A filter block makes a click on one plot narrow the others. There are no functions or templates to learn, just SQL and a few attributes.
Paths are relative to the .dash file, so a folder with the spec and its data works wherever you copy it.
source "orders" { path = "orders.csv" } query "revenue" { sql = <<SQL SELECT channel, sum(amount) AS total FROM orders GROUP BY channel ORDER BY total DESC SQL } plot "revenue" { type = "bar" query = query.revenue x = channel y = total }
The plots a dashboard needs
Standard charts, numbers and maps, laid out on a 12-column grid.
- line · areaTime series, with up to 12 series per plot
- bar · stacked_barRankings and parts of a whole, with totals
- scatter · histogramRelationships and distributions
- heatmapWeekday by hour, region by month
- mapPoints by latitude and longitude, sized and coloured
- timelineEvents at their real distance in time, in lanes
- cardOne number, with its change, good or bad
- table · textSortable rows, headings and notes
Review a dashboard like a document
Hover a plot, click the speech bubble and write what should change, for example “rank these, biggest channel first”. Threads have replies and can be resolved, and a plot with open threads shows their count.
An AI agent reads the same threads with ducklocal comments. Each thread names its plot and the lines of its block in the file. The agent edits the spec, validates it and replies. The open window redraws within a second and shows the reply, marked Agent.
Review with comments · What Claude Dashboards taught me about DuckLocal
$ ducklocal comments sales.dash {"open":1, "threads":[{"id":"c1", "plot":"revenue_by_channel", "plot_lines":[68,75], ...}]} $ ducklocal check sales.dash $ ducklocal comments sales.dash --reply c1 \ --text "Sorted by revenue, descending" --resolve
Checked before anyone opens it
ducklocal check parses the file, resolves every reference and runs every query read-only. Then it confirms each plot's columns exist in the real result, so a typo, a failing cast or a glob that matches nothing is caught in the terminal, not in a meeting.
Every problem is listed at once, one file:line: message each, with exit codes a script or CI job can act on.
- Syntax, names and references checked
- Each query's SQL run through DuckDB
- Plot columns checked against real results
- Filters checked with a value picked
- Queries that return no rows flagged
Your data stays local, the file travels
Queries run in the DuckDB engine inside DuckLocal, against files on your disk or a DuckDB database. Send someone the folder and they see the same dashboard over their copy of the data, with nothing to publish and no workspace to share.
SQL dashboard questions
- What is a .dash file?
- A plain-text file that declares a dashboard as blocks:
sourcenames data files,queryholds one DuckDB SQL statement,plotdraws a result andfiltermakes a click on one plot narrow the others. There is no code to write. - Does a dashboard need a server or a BI account?
- No. DuckLocal opens the file and runs its queries with the DuckDB engine inside the app, on your computer. The data files stay where they are.
- Which charts are available?
- Line, bar, stacked bar, area, scatter, pie, heatmap, histogram, map and timeline plots, plus tables, number cards with a change indicator, and text panels, laid out on a 12-column grid.
- Can an AI agent build or change a dashboard?
- Yes. An agent writes or edits the .dash file, runs
ducklocal checkto confirm every query runs and every plot's columns exist, and answers review comments withducklocal comments. The open window redraws within a second. - Can I keep dashboards in git?
- Yes. A .dash file is short plain text, so it diffs and reviews like code. Review comments live in a separate
NAME.dash.comments.jsonfile that you can leave out of version control.
Related: SQL for AI agents · Local data analysis · DuckDB GUI · Query CSV with SQL
Open the sample dashboard
Download DuckLocal, save the tutorial's sales.csv and sales.dash side by side, and drop the dashboard onto the window.