SQL dashboards you can read, diff and review

A DuckLocal dashboard is a plain-text .dash file: data sources, DuckDB SQL queries and the plots that draw them. It runs on your computer against your local files, sits in git like code, and can be written by you or by an AI agent.

No BI server, no account, no data upload. Free and open source for macOS, Windows and Linux.

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.

Every block and attribute

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

Terminal
$ 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.

Validate a dashboard

  • 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: source names data files, query holds one DuckDB SQL statement, plot draws a result and filter makes 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 check to confirm every query runs and every plot's columns exist, and answers review comments with ducklocal 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.json file that you can leave out of version control.

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.