---
title: Local SQL Dashboards as Plain-Text Files | DuckLocal
description: "Build DuckDB dashboards as plain-text .dash files: SQL queries, charts, cards, maps and cross-filters that run on your computer, review in git, and that an AI agent can edit and validate."
image: https://ducklocal.app/og-image.jpg?v=2
language: en
---

# 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.

## A dashboard is a short file

`source` blocks name data files, `query` blocks hold SQL, `plot` blocks say how to draw each result, and a `filter` block makes a click on one plot narrow the others. Paths are relative to the `.dash` file.

```hcl
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

Line, area, bar, stacked bar, scatter, histogram, heatmap, map and timeline plots, number cards with a change indicator, sortable tables and text panels, on a 12-column grid. See [plot types](https://ducklocal.app/docs/dashboards#plot-types).

## Review a dashboard like a document

Hover a plot, click the speech bubble and write what should change. An AI agent reads the same threads with `ducklocal comments`, edits the spec, validates it and replies; the open window redraws within a second.

```bash
ducklocal comments sales.dash
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, runs every query read-only and confirms each plot's columns exist in the real result. Every problem is listed at once as `file:line: message`, with exit codes a script or CI job can act on.

## 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.

## 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.

**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.

**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.

**Can an AI agent build or change a dashboard?** Yes. An agent writes or edits the .dash file, runs `ducklocal check`, and answers review comments with `ducklocal comments`.

**Can I keep dashboards in git?** Yes. A .dash file is short plain text. Review comments live in a separate `NAME.dash.comments.json` file that you can leave out of version control.

## Links

- [Download DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Dashboard guide](https://ducklocal.app/docs/dashboards)
- [SQL for AI agents](https://ducklocal.app/use-cases/ai-agent-sql/)
- [What Claude Dashboards taught me about DuckLocal](https://ducklocal.app/blog/claude-dashboards-ducklocal/)

Source: https://ducklocal.app/use-cases/sql-dashboards/
