# Dashboards (.dash)

> Erstellen Sie DuckLocal-Dashboards als .dash-Dateien mit DuckDB SQL: Diagramme, Kreuzfilter, Kommentare, die ein KI-Agent beantworten kann, und Prüfung mit ducklocal check.

Source: https://ducklocal.app/docs/de/dashboards

Eine `.dash`-Datei beschreibt ein Dashboard als Daten: **source**-Blöcke
benennen Datendateien, **query**-Blöcke enthalten SQL, **plot**-Blöcke zeichnen
die Ergebnisse, und **filter**-Blöcke lassen einen Klick auf ein Diagramm die
anderen einengen. Es gibt keinen Code zu schreiben. Sowohl Menschen als auch
KI-Agenten können die Datei erstellen, sie in einem Diff prüfen und validieren,
bevor jemand sie öffnet.

Eine `.dash`-Datei zeichnet Standarddiagramme, Tabellen, Zahlen und Karten aus
gespeicherten Abfragen. Ihr reines Textformat macht sie außerdem nützlich für
die Arbeit mit einem KI-Agenten: Der Agent schreibt oder bearbeitet die Datei,
`ducklocal check` prüft, dass sie läuft, und Sie
[kommentieren die Diagramme](#review-with-comments), um Änderungen zu wünschen.

## Ein vollständiges Beispiel {#a-complete-example}

Dieses Dashboard fragt die [Beispieldatei des Tutorials](tutorial.md#sample-file)
ab. Laden Sie [sales.dash](https://ducklocal.app/docs/samples/sales.dash) in
dasselbe Verzeichnis wie `sales.csv` herunter und öffnen Sie es dann.

```hcl
source "sales" {
  path = "sales.csv"
}

query "totals" {
  sql = <<SQL
    SELECT round(sum(revenue), 2) AS revenue, sum(orders) AS orders,
           count(DISTINCT region) AS regions
    FROM sales
    WHERE $channel
  SQL
}

query "by_channel" {
  sql = <<SQL
    SELECT channel, round(sum(revenue), 2) AS revenue
    FROM sales
    GROUP BY channel
    ORDER BY revenue DESC
  SQL
}

query "daily" {
  sql = <<SQL
    SELECT date, region, round(sum(revenue), 2) AS revenue
    FROM sales
    WHERE $channel
    GROUP BY date, region
    ORDER BY date
  SQL
}

plot "revenue" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  width = 4
}

plot "orders" {
  type  = "card"
  query = query.totals
  value = orders
  title = "Orders"
  width = 4
}

plot "regions" {
  type  = "card"
  query = query.totals
  value = regions
  title = "Regions"
  width = 4
}

plot "revenue_by_channel" {
  type  = "bar"
  query = query.by_channel
  x     = channel
  y     = revenue
  title = "Revenue by channel"
  width = 5
}

plot "daily_revenue" {
  type   = "line"
  query  = query.daily
  x      = date
  y      = revenue
  series = region
  title  = "Daily revenue, per region"
  width  = 7
}

plot "daily_table" {
  type  = "table"
  query = query.daily
  title = "The numbers behind it"
}

filter "channel" {
  plot = plot.revenue_by_channel
}
```

Es öffnet sich mit drei Zahlen oben quer, dem Balkendiagramm und dem
Liniendiagramm nebeneinander und der Tabelle darunter. Jede Abfrage läuft
einmal, egal wie viele Diagramme aus ihr zeichnen: `totals` speist alle drei
Karten, und `daily` speist sowohl das Liniendiagramm als auch die Tabelle.
Klicken Sie in **Revenue by channel** auf einen Balken, verengen sich die
Karten, das Liniendiagramm und die Tabelle auf diesen Kanal; das Balkendiagramm
selbst bleibt vollständig, sodass Sie einen anderen anklicken können.

## Ein Dashboard öffnen

Jedes davon öffnet eine `.dash`-Datei als Dashboard-Tab neben Ihren Abfragen:

- das **+** am Ende der Tab-Leiste, dann **Dashboard öffnen**;
- die Datei auf das Fenster ziehen;
- sie auf der Befehlszeile nennen: `ducklocal sales.dash`;
- aus einem Skript oder von einem Agenten in das bereits laufende Fenster:
  `ducklocal open sales.dash` (siehe die
  [CLI-Referenz](cli.md#show-work-in-the-running-window)).

Diagramme liegen auf einem 12-Spalten-Raster: Jedes spannt seine
[`width`](#layout), Diagramme füllen eine Zeile von links nach rechts, und ein
Diagramm, das nicht mehr passt, beginnt die nächste Zeile. Ziehen Sie die
Trenner zwischen den Zeilen, um sie zu vergrößern; ein Dashboard, das höher als
der Tab ist, scrollt. Ein Diagramm, das nicht zeichnen kann – seine Abfrage ist
gescheitert oder eine Spalte fehlt –, zeigt den Grund in seinem eigenen Bereich,
und der Rest des Dashboards zeichnet weiter. Offene Dashboards kommen beim
nächsten Start zurück, und zuletzt geöffnete stehen unter **Dashboards** in der
Seitenleiste.

Fahren Sie mit dem Zeiger über ein Diagramm, um seine Bedienelemente oben rechts
einzublenden:

- **SQL** schaltet das Diagramm auf das SQL um, das seine Abfrage zuletzt
  ausgeführt hat – mit seinen Quellen und den aktuellen Filterauswahlen
  ausgefüllt, sodass es so läuft, wie es steht –, mit **Kopieren** und
  **In einem Abfrage-Tab öffnen**. **Chart** schaltet zurück.
- Die Sprechblase öffnet die [Kommentare](#review-with-comments) des Diagramms.
- **Dieses Diagramm vergrößern** dehnt es auf den ganzen Dashboard-Tab aus.
  Verwenden Sie **Zurück zum Dashboard (Esc)** oder drücken Sie **Esc**, um zum
  Raster zurückzukehren.

Die SQL-Ansicht hebt die Syntax hervor. Machen Sie einen Rechtsklick auf eine
Zelle einer Dashboard-Tabelle, um die Zelle, ihre tabulatorgetrennte Zeile oder
ihre Spalte in der angezeigten Reihenfolge zu kopieren.

Klicken Sie auf die Spaltenüberschrift eines `table`-Diagramms, um zu sortieren:
absteigend, aufsteigend, dann zurück zur Reihenfolge der Abfrage. Zahlen
sortieren als Zahlen und `NULL` steht zuletzt; eine für einen
[Filter](#filters) gewählte Zeile bleibt über eine Sortierung hinweg gewählt.

**Spezifikation anzeigen** in der Werkzeugleiste schaltet den Tab auf einen
Editor für die Datei um, mit Syntaxhervorhebung (das SQL in Heredocs wird wie
im SQL-Editor gefärbt), Vervollständigung und Inline-Diagnosen. **Speichern**
oder **⌘S** schreibt sie zurück und zeichnet neu. Scheitert die gespeicherte
Datei an der Validierung, behält der Tab das letzte funktionierende Dashboard
und zeigt den Fehler darüber. Dasselbe geschieht, wenn ein anderes Programm die
Datei ändert. **Zurück zum Dashboard** kehrt zu den Diagrammen zurück.
**Neu laden** liest die Datei erneut und führt jede Abfrage erneut aus.

## Mit Kommentaren prüfen {#review-with-comments}

Mit Kommentaren prüfen Sie ein Dashboard wie ein Dokument und übergeben die
Änderungen einem KI-Agenten. Die Produktidee hinter diesem Workflow wird in
[Was mir Claude Dashboards über DuckLocal gezeigt hat](https://ducklocal.app/blog/claude-dashboards-ducklocal/)
beschrieben.

**Im Fenster**: Fahren Sie mit dem Zeiger über ein Diagramm und klicken Sie auf
die Sprechblase. Über dem Dashboard öffnet sich eine Karte, die den Titel des
Diagramms zitiert, mit den bereits vorhandenen Threads und einem Feld zum
Schreiben. Schreiben Sie, was sich ändern soll – *„diese sortieren, größter
Kanal zuerst“* –, und drücken Sie **Kommentar** (oder **⌘/Ctrl+Enter**). Jeder
Thread hat **Antworten** und **Erledigen**; ein erledigter Thread bleibt
gedimmt stehen, bis jemand darauf antwortet. Ein Diagramm mit offenen Threads
behält eine Sprechblase mit ihrer Anzahl im Blick, sodass Sie auf einen Blick
sehen, was wartet.

**Der Agent** liest und beantwortet die Threads mit
[`ducklocal comments`](cli.md#review-comments-on-a-dashboard), ohne Fenster:

```bash
ducklocal comments sales.dash
```

```json
{
  "file": "sales.dash",
  "comments_file": "sales.dash.comments.json",
  "open": 1,
  "threads": [
    {
      "id": "c1",
      "plot": "revenue_by_channel",
      "plot_title": "Revenue by channel",
      "plot_query": "by_channel",
      "plot_lines": [68, 75],
      "plot_missing": false,
      "resolved": false,
      "comments": [
        { "author": "user", "text": "Rank these, biggest channel first", "at": "2026-10-10T14:03:00+08:00" }
      ]
    }
  ]
}
```

Jeder Thread nennt sein Diagramm, die Abfrage des Diagramms und die Zeilen
seines `plot`-Blocks in der Datei, sodass der Agent weiß, was zu bearbeiten ist.
Er ändert die Spezifikation, führt `ducklocal check` aus und antwortet:

```bash
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolve
```

Das Fenster beobachtet beide Dateien. Innerhalb einer Sekunde zeichnet das
Diagramm aus der bearbeiteten Spezifikation neu, und die Antwort des Agenten
erscheint in ihrem Thread, markiert als **Agent**.

Die Threads liegen neben dem Dashboard, in `NAME.dash.comments.json`, und reisen
also mit ihm wie seine `source`-Dateien. Sie sind Arbeitsnotizen, kein Teil des
Dashboards: Lassen Sie sie aus der Versionsverwaltung heraus oder löschen Sie
die Datei, wenn das Review erledigt ist.

Der [offizielle Agent-Skill](cli.md#install-the-official-skill) lehrt diese
Schleife, ein Agent damit muss also nur *„bearbeite die Kommentare zu
sales.dash“* hören.

::: info Neu in 0.4.0
Ein Agent kann eine [Änderung vorschlagen](agent-workflows.md#propose), statt die Datei zu bearbeiten. Der Tab bietet dann **Prüfen** mit dem Diff und den Checks, und nur Sie können sie übernehmen.
:::

### Einen Agenten bei der Arbeit sehen {#agent-presence}

Während ein Agent `check`, `comments` oder `presence` für dieses offene Dashboard
ausführt, erscheint sein Name in der Ecke, mit der Marke seines Herstellers –
Claude, OpenAI, Gemini, Cursor, DeepSeek – oder seinem Anfangsbuchstaben.
Klicken Sie den Namen an, um das Sitzungsprotokoll zu sehen. Wenn er die Datei
bearbeitet, bleiben geänderte und hinzugefügte Diagramme markiert (**Claude hat
dies geändert**, **Claude hat dies hinzugefügt**), bis Sie sie einen Moment im
Blick hatten; ein entferntes Diagramm hinterlässt einen Hinweis, den Sie
verwerfen können.

Ein Agent kann seine nächste Bearbeitung mit `ducklocal presence sales.dash
--doing editing --plot revenue_by_channel` ankündigen. Dieses Diagramm bekommt
einen Ring; ein Diagrammname, den es noch nicht gibt, bekommt einen Platzhalter
unter dem Dashboard. Die Sitzung endet nach 30 Sekunden ohne Aktivität oder mit
einem ausdrücklichen `--doing idle`. Ein fertiger Agent bleibt in der Ecke,
solange ein von ihm beantworteter Thread auf Ihre Antwort wartet, mit der Anzahl
an seinem Avatar. Kommentare halten fest, welcher Agent sie geschrieben hat,
und zeigen seine Marke. Die [CLI-Referenz](cli.md#agent-presence) beschreibt die
Optionen. Diese Anzeigen zeigen lokale Aktivität; sie senden keine Arbeit an
einen Agenten.

## Blöcke {#blocks}

Eine Datei ist eine Folge von Blöcken, jeder ein Typ, ein Name in
Anführungszeichen und ein Rumpf:

```hcl
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }
```

Namen müssen innerhalb ihrer Art eindeutig sein: Zwei Abfragen können sich
keinen Namen teilen, zwei Diagramme ebenso wenig – aber eine Abfrage und ein
Diagramm dürfen es.

::: info Neu in 0.4.1
Ein `view`-Block hält Aufbereitungsschritte, die mehrere Abfragen teilen, ein `filter` kann
mehrere Werte sammeln (`multiple = true`), ein `timeline`-Diagramm platziert
Ereignisse nach ihrem tatsächlichen zeitlichen Abstand, und ein `dashboard`-Block
legt die Zone fest, in der jede `TIMESTAMPTZ` angezeigt wird.
:::

### source

| Attribut | Erforderlich | Wert |
| --- | --- | --- |
| `path` | ja | Eine `.csv`-, `.tsv`-, `.txt`-, `.parquet`-, `.json`-, `.jsonl`- oder `.ndjson`-Datei (auch gzip-komprimiert, etwa `.csv.gz`) oder ein Glob darüber (`exports/orders-*.csv`), gelesen als eine Relation |

Eine Quelle gibt Datendateien einen Namen, den die Abfragen lesen: Mit
`source "sales"` sagt eine Abfrage `FROM sales`. Der Pfad ist **relativ zur
`.dash`-Datei**, nicht zu dem Ort, an dem DuckLocal gestartet wurde, sodass ein
Dashboard und seine Daten gemeinsam umziehen können; `~` und absolute Pfade
funktionieren ebenfalls.

Eine Quelle berührt die Verbindung nie: Sie wird zu einem `WITH sales AS (…)`
vor jeder Abfrage, die sie nennt, sodass nichts in der Seitenleiste erscheint,
nichts den Tab überlebt und eine Quelle eine gleichnamige Tabelle nur für die
Abfragen dieses Dashboards verdeckt. Der Name muss ein reiner Bezeichner sein
(Buchstaben, Ziffern und `_`). Eine Arbeitsmappe kann keine Quelle sein; öffnen
Sie sie in DuckLocal und fragen Sie die Tabelle ab, die daraus wird.

### view

Eine View hält Aufbereitungsschritte, die mehrere Abfragen teilen, einmal geschrieben. Sie
enthält ein `sql`-Attribut unter denselben Regeln wie das einer Abfrage, und jede
Abfrage, die sie nennt, liest sie als Tabelle:

```hcl
view "events" {
  sql = <<SQL
    SELECT r.eventName AS event_name, r.eventTime AS event_time
    FROM (SELECT unnest(Records) AS r FROM trail)
  SQL
}

query "totals" {
  sql = "SELECT count(*) AS events, count(DISTINCT event_name) AS kinds FROM events"
}
```

Eine View liest die Quellen und die über ihr definierten Views, teilt ihre Namen
mit Quellen und nimmt kein `$filter` – lesen Sie den Filter in den Abfragen, die
die View lesen. Wie eine Quelle wird sie vor jede Abfrage gestellt, die sie
nennt, und erzeugt nichts auf der Verbindung. Greifen Sie zu einer, wenn Abfragen
sonst dasselbe CTE wiederholen würden, etwa beim Abflachen von verschachteltem JSON.

### query

| Attribut | Erforderlich | Wert |
| --- | --- | --- |
| `sql` | ja | Eine schreibgeschützte SQL-Anweisung, als [Heredoc](#heredocs) oder als String |

Ein Abfrageblock enthält `sql` und sonst nichts. Er kann `$name` für einen
[Filter](#filters) lesen.

### plot

| Attribut | Für | Wert |
| --- | --- | --- |
| `type` | alle, erforderlich | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"` oder `"text"` – ein String in Anführungszeichen |
| `query` | alle außer `text`, erforderlich | Ein Verweis auf einen Abfrageblock: `query.by_channel` |
| `x` | Diagramme, erforderlich | Die Spalte auf der horizontalen Achse; die Segmente eines `pie`; die Zahl, die ein `histogram` in Klassen einteilt; die Zeit eines `timeline`. Ein `table` zeigt jede Spalte und braucht keine |
| `y` | Diagramme, erforderlich | Die Spalte, die gezeichnet wird; muss numerisch sein. Die Segmentgrößen eines `pie`. Ein `histogram` und ein `timeline` nehmen keine |
| `series` | `line`, `bar`, `stacked_bar`, `area`, `scatter`, `heatmap`, `timeline` | Eine Spalte, deren Werte die Zeilen in je eine Reihe aufteilen; die Zeilen einer `heatmap`; die Schwimmbahnen eines `timeline` |
| `title` | alle | Eine Überschrift für das Diagramm als String in Anführungszeichen; die Beschriftung einer Karte |
| `width` | alle | Wie viele der 12 Rasterspalten das Diagramm spannt, `1`–`12`. Standard 12, bei einer Karte 3 |
| `value` | `card` | Die Spalte, die angezeigt wird, aus der ersten Zeile. Standard: die erste Spalte |
| `note` | `card` | Text unter dem Wert: ein String in Anführungszeichen oder ein reiner Spaltenname, der aus der ersten Zeile gelesen wird |
| `tone` | `card` | `"accent"`, `"good"`, `"warning"` oder `"critical"`; färbt die obere Linie und den Wert |
| `format` | Diagramme und `card` | Was die Zahlen sind: siehe [Zahlenformate und Veränderung](#number-formats-and-change). Eine `map` oder `table` nimmt keine |
| `delta` | `card` | Eine numerische Spalte mit der Veränderung, unter dem Wert angezeigt |
| `delta_format` | `card` | Ein Format für die Veränderung. Standard: das der Karte |
| `down_is_good` | `card` | `true` macht einen Rückgang grün und einen Anstieg rot, für Kosten, Latenz oder Abwanderung |
| `description` | alle, **0.4.0+** | Was das Diagramm zeigt und wie man es liest; erscheint beim Überfahren eines ⓘ neben dem Titel |
| `text` | `text` | Fließtext als String oder Heredoc; geben Sie `title`, `text` oder beides an, ohne `query` |
| `caption` | `timeline` | Die Spalte, die sagt, was jedes Ereignis war; steht unter seinem Punkt, wo sie passt, und im Tooltip |
| `lat`, `lng` | `map` | Breiten- und Längengradspalten in Grad. Eines kann entfallen, wenn der Name der numerischen Spalte die Koordinate anzeigt – `lat`, `latitude`, `geo_lat`; `lng`, `lon`, `longitude` |
| `color` | `map` | Eine Spalte, nach der die Punkte gefärbt werden; entfällt sie, wird eine gewählt, wenn eine Textspalte nur wenige Werte hat |
| `size` | `map` | Eine numerische Spalte, nach der die Punkte bemessen werden |
| `size_scale` | `map` | `"sqrt"` (der Standard) oder `"log"`, dafür, wie `size` skaliert |
| `tooltip` | `map` | Eine Liste der Spalten, die der Tooltip eines Punktes zeigt: `[name, passengers]` |

Spaltenattribute benennen Spalten des Abfrageergebnisses, ohne Rücksicht auf
Groß- und Kleinschreibung. Schreiben Sie einen reinen Namen ohne
Anführungszeichen (`x = date`); setzen Sie einen, der kein reiner Bezeichner
ist, in Anführungszeichen (`y = "revenue (EUR)"`). Ein Attribut, das der Typ des
Diagramms nicht braucht – `lat` bei einer Linie, `x` bei einer Karte, `series`
bei einem Kreis –, ist ein Fehler und wird nicht stillschweigend ignoriert.

### filter

| Attribut | Erforderlich | Wert |
| --- | --- | --- |
| `plot` | ja | Das Diagramm, auf dem ein Klick einen Wert wählt: `plot.revenue_by_channel`. Ein `bar`, ein `stacked_bar` oder ein `table` |
| `column` | bei einem `table` | Die Spalte, deren Wert gewählt wird. Bei einem `bar` oder `stacked_bar` dessen `x`, wenn sie entfällt |
| `multiple` | `bar`, `stacked_bar` | `true` lässt jeden Klick seinen Wert hinzufügen und einen zweiten Klick ihn entfernen; `$name` wird zu `IN (…)`. Eine Tabelle wählt eine Zeile, daher ist `multiple` an einer Tabelle ein Prüffehler |

Was ein Filter tut, steht unter [Filter](#filters).

### dashboard

Ein optionaler `dashboard`-Block hält Einstellungen für die ganze Datei:

```hcl
dashboard "Ops" {
  timezone = "+08:00"     # or "UTC", or "local"
}
```

`timezone` ist die Zone, in der jede `TIMESTAMPTZ` im Dashboard angezeigt wird;
die Zone steht über den Diagrammen. Ein Versatz (`"+08:00"`), `"UTC"` und
`"local"` werden akzeptiert; IANA-Namen wie `Asia/Shanghai` nicht. Ein reiner
`TIMESTAMP` hat keine Zone und wird so angezeigt, wie er geschrieben steht, und
eine Spalte, die ein Filter wählt, behält ihren gespeicherten Wert, damit
Auswahlen weiter übereinstimmen. Eine Datei enthält höchstens einen
`dashboard`-Block.

## Diagrammtypen {#plot-types}

| Typ | Zeichnet |
| --- | --- |
| `line` | Eine Linie pro Reihe, ungefüllt |
| `area` | Eine gefüllte Fläche pro Reihe |
| `bar` | Einen Balken pro Zeile, eine Farbe pro Reihe. Mit `series` stehen die Balken der Reihen in jeder Gruppe nebeneinander. Eine einzelne Reihe beschriftet jeden Balken mit seinem Wert |
| `stacked_bar` | Einen Balken pro `x`, seine `series` gestapelt: positive Teile von null nach oben, negative nach unten, mit der Summe oben und im Tooltip |
| `heatmap` | `x` waagerecht und `series` senkrecht, jede Zelle nach `y` auf einer Blau-Skala gefärbt, dunkler für mehr (im dunklen Modus heller). Ein Paar, das die Abfrage nicht zurückgibt, bleibt leer |
| `histogram` | Die Zeilen, gezählt in jedem Bereich eines numerischen `x`, in Klassen mit runder Breite. Lassen Sie die Abfrage die Zeilen selbst zurückgeben, keine Gruppierung |
| `scatter` | Einen Punkt pro Zeile, unverbunden, eine Farbe pro Reihe |
| `pie` | Ein Segment pro `x`-Wert, nach `y` bemessen, größtes zuerst; ab 8 Segmenten falten sich die kleinsten in „Sonstige“. Gezeichnet als Ring mit der Summe in der Mitte; klicken Sie einen Eintrag der Legende an, um ein Segment herauszuwählen, und erneut, um es zurückzusetzen |
| `text` | Einen Titel, erklärenden Text oder beides; es läuft keine Abfrage |
| `map` | Einen Punkt pro Zeile, an seinem `lat` und `lng`; siehe [Karten](#maps) |
| `timeline` | Ein Ereignis pro Zeile zu seiner `x`-Zeit, platziert nach seinem tatsächlichen Abstand zu den anderen, sodass Lücken sichtbar werden. `series` gibt jedem Akteur eine Schwimmbahn, `caption` sagt, was geschah, und `tooltip` listet die überfahrenen Spalten. Nimmt kein `y`; zeichnet höchstens 12 Bahnen und 1.000 Ereignisse (darüber gleichmäßig ausgedünnt, und es wird gesagt) und zählt Zeilen, deren Zeit nicht lesbar ist, statt sie zu zeichnen |
| `table` | Das Ergebnis der Abfrage als Raster, Spalten nach ihrem Inhalt bemessen; klicken Sie eine Überschrift an, um zu sortieren |
| `card` | Eine Zahl, groß, mit dem `title` als Beschriftung. Mit Tausendertrennung, ein langer Bruch gerundet (`11439704.020000005` → `11,439,704.02`) und verkleinert, um in die Karte zu passen, statt abgeschnitten zu werden |

Fahren Sie über ein Diagramm, um seine Werte zu sehen, formatiert wie die Achse
sie zeigt (`4.4M`, nicht `4400000`).

Ein Balkendiagramm beschriftet **jede** Kategorie. Wenn die Beschriftungen nicht
unter ihre Balken passen, legt sich das Diagramm auf die Seite, mit den
Beschriftungen in einer Spalte links. Nur eine Zeitachse dünnt ihre
Beschriftungen aus und behält so viele, wie passen – immer die erste und die
letzte –, und ein Balken über einer `DATE`-Spalte füllt die Tage, für die die
Abfrage nichts zurückgab, als leere Bänder, sodass eine ruhige Strecke als Lücke
lesbar bleibt und nicht verschwindet. Linien-, Flächen- und
Streudiagrammachsen dünnen ihre Beschriftungen auf dieselbe Weise aus.

Die x-Achse ist für jeden Diagrammtyp kategorisch: Die Werte sind gleichmäßig
in der Reihenfolge verteilt, in der die Abfrage sie zurückgibt, nicht nach ihrem
Abstand zueinander. Ein `scatter` zweier numerischer Spalten ist daher kein
echtes x-y-Diagramm.

Zeilen werden in der Reihenfolge gezeichnet, in der die Abfrage sie zurückgibt;
beenden Sie eine Abfrage, die ein Diagramm speist, daher mit `ORDER BY`.

::: info Neu in 0.4.0
Ein `line` oder `scatter` eines Dashboards über Zeiten wird nach Zeit platziert, ungleichmäßige Abstände sehen also ungleichmäßig aus, und es zeichnet in Zeitreihenfolge, unabhängig vom `ORDER BY`. Eine Zeile mit NULL-Zeit entfällt, mit einem Hinweis. Ein NULL-Messwert, den die Abfrage zurückgibt, unterbricht die Linie. Ein `area` bleibt gleichmäßig verteilt und sagt das auch. Eine Reihe behält ihre Farbe über den Namen, und jedes Diagramm sagt, wenn seine Abfrage abgeschnitten wurde.
:::

Eine Karte zeigt die erste Zeile ihrer Abfrage. Gibt die Abfrage mehr als eine
Zeile zurück, sagt die Karte das unter der Zahl; gibt sie keine zurück, zeigt
sie `—`.

### Karten und Textbereiche {#cards-and-text-panels}

Karten können eine Zahl mit `note` erklären und ihr mit `tone` eine Statusfarbe
geben. Karten in derselben Zeile teilen eine Schriftgröße für den Wert.
Textbereiche fügen Überschriften oder Kontext hinzu, ohne SQL auszuführen:

```hcl
plot "revenue_summary" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  note  = "Current channel selection"
  tone  = "accent"
  width = 4
}

plot "reading_guide" {
  type  = "text"
  title = "How to read this dashboard"
  text  = "Click a channel to filter the daily chart and revenue cards."
  width = 8
}
```

Ein Textbereich akzeptiert nur `type`, `title`, `text` und `width`. Verwenden
Sie `text = <<TEXT` mit einer abschließenden `TEXT`-Zeile für eine längere
Erklärung. Diagramme, Kreise und Karten verwenden acht verschiedene Farbtöne,
deren Schattierungen an das aktuelle Design angepasst sind, mit einer Legende
für mehrere Reihen.

### Zahlenformate und Veränderung {#number-formats-and-change}

`format` formt den Wert einer Karte, die Werteachse, Balkenbeschriftungen und
Tooltips:

| Wert | Liest sich als |
| --- | --- |
| `"num0"`, `"num1"`, `"num2"` | Eine Zahl mit so vielen Nachkommastellen |
| `"pct"` (dasselbe wie `"pct1"`), `"pct0"`, `"pct2"` | Ein Anteil: 0.421 liest sich als 42.1%, geben Sie also den Bruchteil zurück, nicht ×100 |
| `"usd"`, `"eur"`, `"gbp"`, `"cny"` | Geld, mit zwei Nachkommastellen |
| `"usd0"`, `"eur0"`, `"gbp0"`, `"cny0"`, `"jpy"` | Geld, in ganzen Einheiten |

Eine Karte zeigt eine Veränderung mit `delta` unter dem Wert als `▲ 12.3%` oder
`▼ $125`. Sie ist grün, wenn sie gut ist, und rot, wenn nicht, und die `note`
folgt ihr und sagt, wogegen. Berechnen Sie die Veränderung in der Abfrage der
Karte:

```hcl
plot "revenue_total" {
  type         = "card"
  query        = query.totals
  value        = revenue
  format       = "usd0"
  delta        = growth
  delta_format = "pct1"
  note         = "vs last week"
}
```

### Layout {#layout}

`width` gibt an, wie viele der zwölf Spalten des Dashboards ein Diagramm spannt.
Diagramme füllen eine Zeile von links in der Reihenfolge, in der sie geschrieben
sind, und brechen um, wenn das nächste nicht passt, sodass vier Karten (je `3`)
eine Zahlenzeile ergeben und zwei Diagramme mit `width = 6` nebeneinander
darunter sitzen. Eine Zeile, die keine zwölf Spalten füllt, lässt den Rest leer.
Eine Zeile aus nichts als Karten startet in geringer Höhe, eine Zeile aus nichts
als Tabellen startet so hoch wie die Zeilen ihrer längsten Tabelle, bis zur Höhe
eines Diagramms. Eine Zeile aus Textbereichen passt sich ihrem Text an; andere
Zeilen starten in Diagrammhöhe. Griffe zum Vergrößern von Zeilen erscheinen beim
Überfahren.

### Karten {#maps}

```hcl
plot "stations" {
  type       = "map"
  query      = query.stations
  lat        = geo_lat
  lng        = geo_lng
  color      = line
  size       = passengers
  size_scale = "log"
  tooltip    = [name, passengers]
}
```

Eine Karte zeichnet jede Zeile als Punkt, auf einer an die Punkte angepassten
Web-Mercator-Projektion, über einem Breiten-/Längengradraster mit
Gradbeschriftung.

- **`color`**: bis zu fünf Werte bekommen je eine Farbe; bei mehr bekommen die
  vier häufigsten eine, und der Rest teilt eine „Sonstige“-Farbe. Eine Legende
  liest sie zurück. Entfällt sie, werden die Punkte nach einer Textspalte mit
  nur wenigen verschiedenen Werten gefärbt, wenn das Ergebnis eine hat.
- **`size`**: Die *Fläche* eines Punktes folgt dem Wert, doppelter Wert ist also
  doppelte Tinte. `size_scale = "log"` passt zu Werten über mehrere
  Größenordnungen. Eine Legende in der Ecke liest die Größen zurück.
- **`tooltip`**: Ohne ihn listet der Tooltip eines Punktes die Größenspalte und
  die anderen Zahlen und dann die Koordinaten.

Unter den Punkten kann eine Karte eine **OpenStreetMap**-Basiskarte zeichnen.
Sie ist aus, bis Sie sie einschalten – **Ansicht → Online-Basiskarte
(OpenStreetMap)** –, weil das Laden von Kacheln das Netzwerk braucht. Gesendet
wird, welche Kartenkacheln sie möchte, was ungefähr den betrachteten Bereich
verrät, nie eine Zeile Ihrer Daten. Kacheln werden eine Woche lang auf der
Festplatte zwischengespeichert (siehe
[Einstellungen und App-Daten](settings-and-data.md#where-things-are-stored));
offline oder aus zeichnet die Karte nur über ihrem Breiten-/Längengradraster.
Derselbe Schalter gilt für die Karte im **Chart**-Tab der Abfrageergebnisse.

## Filter {#filters}

Ein Filter macht ein Diagramm klickbar und lässt den dort gewählten Wert andere
Abfragen einengen:

```hcl
filter "channel" {
  plot = plot.revenue_by_channel     # a click on a bar picks its channel
}

filter "day" {
  plot   = plot.days                 # a table: a selected row picks …
  column = day                       # … the value of this column
}

filter "channel" {
  plot     = plot.revenue_by_channel
  multiple = true                    # clicks collect channels
}

query "daily" {
  sql = "SELECT date, sum(orders) AS orders FROM sales WHERE $channel AND $day GROUP BY 1"
}
```

Eine Abfrage liest einen Filter als **`$name`, eine Bedingung**: Schreiben Sie
ihn dorthin, wo eine Bedingung steht. Solange nichts gewählt ist, ist er `TRUE`,
das Dashboard öffnet sich also genau so, als gäbe es den Filter nicht. Sobald
ein Wert gewählt ist, wird er zu `("channel" = 'Web')` – die Spalte, benannt wie
die `column` des Filters, verglichen mit dem gewählten Wert; eine als `NULL`
angezeigte Zelle trifft SQL NULL oder den Literaltext `NULL`. Mit `multiple = true`
an einem Balken oder gestapelten Balken fügt jeder Klick seinen Wert hinzu und ein
zweiter Klick nimmt ihn heraus, und `$name` wird zu
`("channel" IN ('Web', 'App'))`, mit `OR "channel" IS NULL`, wenn NULL einer
davon ist. Mehrere Filter kombinieren sich so, wie die Abfrage sie kombiniert.

- **In einem Balkendiagramm**: Klicken Sie einen Balken an, um ihn zu wählen; er
  behält seine Farbe, während die anderen verblassen. Klicken Sie ihn erneut an,
  um die Auswahl zu löschen. Mit `multiple = true` fügt jeder Klick einen Wert
  hinzu und ein zweiter Klick entfernt ihn.
- **In einer Tabelle**: Wählen Sie eine Zeile, per Klick oder mit den
  Pfeiltasten.
- Die aktiven Auswahlen erscheinen als Chips über den Diagrammen; das ✕ eines
  Chips löscht seinen Filter, und **Alle löschen** löscht jede Auswahl. Ein
  Mehrfachauswahl-Filter zeigt einen Chip pro gewähltem Wert.
- **Das auswählende Diagramm wird nie von seinem eigenen Filter eingeengt.**
  Seine Abfrage liest `$channel` als `TRUE`, auch während ein Kanal gewählt ist
  – sonst würde ein Klick das Balkendiagramm auf den gerade geklickten Balken
  reduzieren, ohne dass etwas zum Weiterklicken übrig bliebe. Das ist
  Kreuzfiltern, wie in Mosaic oder crossfilter.
- **Nur was sich ändert, läuft erneut.** Eine Auswahl führt die Abfragen erneut
  aus, deren SQL sie ändert; eine Abfrage, die keinen Filter liest, behält ihr
  Ergebnis.

Ein Filter hält jeweils einen Wert, oder mehrere mit `multiple = true`. Auswählbare Diagramme enthalten einen
Klick-zum-Filtern-Hinweis unter dem Titel. Reihen behalten ihre Farben, während
das Filtern ändert, welche Gruppen bleiben. Eine Abfrage, die `$channel`
verwendet, muss die Spalte des Filters dort bereitstellen, wo dieses Prädikat
verwendet wird; `ducklocal check` bindet inzwischen auch eine Variante mit
gewähltem Wert, sodass eine fehlende Spalte vor dem ersten Klick auffällt.

::: info Neu in 0.4.0
Das Wählen einer als `NULL` angezeigten Zelle wählt nur SQL NULL, und der Text `'NULL'` wählt nur sich selbst. Auswählbare Diagramme zeigen keinen Klick-zum-Filtern-Hinweis mehr unter dem Titel.
:::

Der gewählte Wert geht als Literal in Anführungszeichen in das SQL, und DuckDB
wandelt ihn beim Vergleichen in den Typ der Spalte um, sodass Daten und Zahlen
ebenso funktionieren wie Text. Auswahlen halten, solange der Tab offen ist, und
überstehen ein Neuladen, solange der Filter noch in der Datei steht; zwischen
Starts werden sie nicht gemerkt.

## Werte

| Form | Beispiel | Verwendet für |
| --- | --- | --- |
| String | `"Revenue by channel"` | `type`, `title`, `path`, `size_scale`, `tone`, Literal-`note`, `text`, Spaltennamen in Anführungszeichen, kurzes `sql` |
| Heredoc | `<<SQL` … `SQL` | `sql`, `text` |
| Verweis | `query.daily`, `plot.revenue_by_channel` | die `query` eines Diagramms, die `plot` eines Filters |
| Reiner Name | `channel` | Spaltenattribute |
| Zahl | `6` | `width` |
| Liste | `[name, "Unique IPs"]` | `tooltip` |

Ein String endet an seiner Zeile und versteht `\n`, `\t`, `\"` und `\\`.

`#` und `//` beginnen einen Kommentar, der bis zum Zeilenende läuft. Attribute
brauchen kein Trennzeichen; Zeilenumbrüche sind nur Leerraum.

Das ist die ganze Sprache: keine Variablen, keine Funktionen, keine bedingten
Anweisungen und keine Interpolation außer dem `$name` eines Filters.

### Heredocs {#heredocs}

Ein Heredoc enthält Text über mehrere Zeilen – in der Praxis SQL:

```hcl
  sql = <<SQL
    SELECT 1
  SQL
```

- Das Trennwort nach `<<` ist ein beliebiges Wort (`SQL` per Konvention), und in
  seiner Zeile darf nichts darauf folgen.
- Das Heredoc endet an der ersten Zeile, die genau das Trennwort ist, abgesehen
  von umgebenden Leerzeichen.
- Die Einrückung der Schlusszeile wird von jeder Zeile des Textes entfernt,
  sodass das SQL auf der Einrückung des Blocks stehen kann, ohne sie
  mitzutragen.

## SQL-Regeln {#sql-rules}

Ein Dashboard führt seine Abfragen aus, wann immer es geöffnet, neu geladen oder
gespeichert wird, und wenn DuckLocal mit wiederhergestelltem Tab startet – eine
Abfrage darf daher nur **lesen**:

- **Erlaubt:** `SELECT`, `WITH …`, `FROM`-first-Abfragen, `VALUES`, `SHOW`,
  `DESCRIBE`, `SUMMARIZE`, `PIVOT` und `UNPIVOT`.
- **Abgelehnt:** alles, was Daten oder Dateien ändern könnte – `CREATE`,
  `INSERT`, `UPDATE`, `DELETE`, `DROP`, `COPY`, `ATTACH`, `INSTALL`, `LOAD` und
  so weiter. Das Öffnen einer `.dash`-Datei, die Ihnen jemand geschickt hat,
  kann Ihre Daten nicht ändern.
- **Eine Anweisung pro Abfrage.**
- **Ein `PIVOT` in einer anderen Abfrage nennt seine Werte.** Eine Abfrage, die
  mit `PIVOT` beginnt, darf die Werte DuckDB überlassen (`PIVOT orders ON
  channel USING sum(amount)`). Eines, das in einem `SELECT` oder einem `WITH`
  verschachtelt ist, braucht eine ausdrückliche Liste: `ON channel IN ('Web',
  'Store')`.
- **`$name` muss einen Filterblock benennen.** Die Schreibschutzprüfung
  beurteilt das SQL mit jedem `$name` als `TRUE`. Ein `$` in einem String, einem
  Bezeichner in Anführungszeichen, einem Kommentar oder einem `$$ … $$`-String
  bleibt unberührt.

Abfragen laufen auf der eigenen Verbindung des Fensters und sehen daher alles,
was der SQL-Editor sieht: geöffnete Dateien, angehängte Datenbanken und Zustand
auf Verbindungsebene wie `TEMP`-Tabellen.

### Pfade in SQL

Seit v0.2.2 werden relative Dateipfade im Dashboard-SQL auch im Ordner der
`.dash`-Datei gesucht. `FROM 'sales.csv'` kann zum Beispiel die CSV neben dem
Dashboard lesen, wenn es aus einem anderen Verzeichnis geöffnet wird. Das gilt
im Fenster und in `ducklocal check`.

DuckDB prüft bei einer einzelnen, direkt in SQL genannten Datei weiterhin zuerst
das Arbeitsverzeichnis: Eine gleichnamige Datei dort kann Vorrang bekommen. Ein
[source](#source)-Block löst seinen Pfad ausdrücklich gegen den Dashboard-Ordner
auf und vermeidet diese Mehrdeutigkeit. Absolute Pfade und registrierte Views
bleiben verfügbar.

## Grenzen

| Grenze | Was geschieht |
| --- | --- |
| 12 Reihen pro Diagramm | Weitere Reihen entfallen, und ein Hinweis nennt, wie viele es waren |
| 1.500 Punkte pro Reihe | Punkte werden auf Klassenmittelwerte reduziert, um zu passen |
| 200 Balken | Weitere Balken entfallen |
| 8 Kreissegmente | Die kleinsten falten sich in ein Segment „Sonstige“ |
| 200 Heatmap-Spalten, 12 Zeilen | Weitere Spalten und Zeilen entfallen |
| 5–40 Histogramm-Klassen | Etwa √Zeilen, jede 1, 2, 2,5 oder 5 × eine Zehnerpotenz breit |
| 20.000 Kartenpunkte | Weitere Punkte entfallen, und ein Hinweis sagt es |
| 12 Bahnen, 1.000 Ereignisse pro Zeitstrahl | Weitere Ereignisse werden gleichmäßig ausgedünnt, und ein Hinweis sagt es; Zeilen, deren Zeit nicht lesbar ist, werden gezählt, nicht gezeichnet |

## Ein Dashboard validieren {#validate-a-dashboard}

`ducklocal check` validiert eine Datei, ohne ein Fenster zu öffnen – der
Schritt, den Sie ausführen, bevor Sie jemandem ein Dashboard übergeben:

```bash
ducklocal check sales.dash
ducklocal check sales.dash --database warehouse.duckdb
ducklocal check sales.dash --summary
```

Zuerst die statischen Prüfungen: die Syntax, die Namen und Verweise, die
erforderlichen Attribute, jedes `$name` gegen die Filterblöcke und das SQL jeder
Abfrage durch DuckDBs eigenen Parser. Dann **läuft jede Abfrage**,
schreibgeschützt, mit ihren Quellen und ohne Auswahl, und die Spalten jedes
Diagramms werden gegen die Spalten geprüft, die seine Abfrage wirklich
zurückgibt – einschließlich, dass `y`, die Koordinaten einer Karte und ihr
`size` numerisch sind und dass die `column` jedes Filters eine ist, die die
Abfrage seines Diagramms zurückgibt. Ausführen ist wichtig: Eine Umwandlung, die
scheitert, oder ein Glob, der nichts trifft, zeigt sich erst, wenn Zeilen
gelesen werden.

- **Ohne `--database`** laufen die Abfragen im Speicher, was alles ist, was ein
  Dashboard über seine eigenen `source`-Dateien braucht. Eine Abfrage, die eine
  Tabelle liest, die keine Quelle definiert, wird unter `unresolved` gelistet,
  statt als Fehler zu gelten, und die Spalten ihrer Diagramme bleiben ungeprüft
  – sie ist vermutlich für eine Datenbank gedacht.
- **Mit `--database PATH`** laufen sie gegen diese Datenbank, schreibgeschützt
  geöffnet. Übergeben Sie sie immer, wenn die Abfragen Tabellen einer Datenbank
  lesen.

Jede Abfrage, die einen Filter verwendet, wird zusätzlich mit einem gewählten
Wert gebunden, ohne diese Variante auszuführen. Das fängt Prädikate ab, die auf
eine in dieser Abfrage nicht verfügbare Spalte verweisen. Blöcke mit Fehlern
hindern fehlerfreie Blöcke nicht an der Prüfung: Diagnosen umfassen sowohl
Spezifikationsfehler als auch Abfragefehler desselben Laufs.

Erfolg gibt eine JSON-Zusammenfassung der Quellen, Abfragen (mit ihren
Ergebnisspalten und wie viele `rows` jede zurückgab), Filter und Diagramme aus,
plus `empty`: die Abfragen, die liefen und keine Zeilen zurückgaben. Das ist
kein Fehler, aber meist ein regulärer Ausdruck, ein Filter oder ein Join, der
nichts traf; sehen Sie sich jede an, bevor Sie das Dashboard übergeben.
`--summary` gibt eine JSON-Zeile mit Anzahlen und den Namen der unaufgelösten
und leeren Abfragen aus. Ein Fehler endet bei Spezifikationsdiagnosen mit Status
**2** und listet jedes Problem auf einmal, je ein `file:line: message`.
Nur-SQL-, Datenbank- oder Dateifehler enden mit **1**. Die
[CLI-Referenz](cli.md#check-a-dashboard-spec) enthält die Details.

::: info Neu in 0.4.0
`ducklocal check FILE --restricted --allow-read PATH` prüft ein Dashboard, das Sie nicht geschrieben haben, unter Grenzen. Siehe [SQL begrenzen, das Sie nicht geschrieben haben](agent-workflows.md#restricted).
:::

### Häufige Meldungen

| Meldung | Behebung |
| --- | --- |
| `type is a string in quotes` | Schreiben Sie `type = "line"`, nicht `type = line` |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | Verwenden Sie einen der gelisteten Typen |
| `plot block "p" requires y` | Jeder Diagrammtyp braucht ein `y`; `table`, `map`, `card` und `text` nicht |
| `plot "p" draws query "q", which the file does not define` | Fügen Sie den Abfrageblock hinzu oder korrigieren Sie den Namen in `query = query.…` |
| `query names a query block: query = query.some_name` | Das Attribut `query` nimmt einen Verweis, keinen String |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | Richten Sie `y` auf eine Zahlenspalte oder verwenden Sie `type = "table"` |
| `A map plot places points by lat and lng; it takes no x` | Eine Karte hat keine Achsen: Geben Sie `lat` und `lng` an oder überlassen Sie sie den Spaltennamen |
| `width is how many of the dashboard's 12 columns the plot spans` | Schreiben Sie eine ganze Zahl von 1 bis 12 |
| `query "q" reads $chanel, but no filter block is named "chanel"` | Korrigieren Sie den Namen oder fügen Sie den Block `filter` hinzu |
| `filter "f" picks on plot "p", a line; a value is picked on a bar or table plot` | Richten Sie den Filter auf ein Balkendiagramm oder eine Tabelle |
| `a dashboard query must be a single read-only statement` | Verschieben Sie Schreibvorgänge in den SQL-Editor oder benennen Sie die Werte eines verschachtelten `PIVOT` mit `IN`; siehe [SQL-Regeln](#sql-rules) |
| `Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }` | Jeder Bereich ist ein Diagrammblock, Karten und Textbereiche auch |
| `"minutes" is a SQL keyword, so as a column alias it needs AS` | Schreiben Sie `count(*) AS minutes` oder setzen Sie den Alias in Anführungszeichen |
| `Unterminated heredoc: no line is exactly SQL` | Fügen Sie das schließende Trennwort in einer eigenen Zeile hinzu |

## Im eigenen Editor bearbeiten

`ducklocal lsp` ist ein Language Server für `.dash`-Dateien: Diagnosen während
des Tippens, Vervollständigung für Blocktypen, Attribute, Diagrammtypen und die
Namen nach `query.` und `plot.`, Hover-Dokumentation und Sprung zur Definition
von einem Verweis `query.name` oder `plot.name` zu seinem Block. Die Einrichtung
für Neovim und VS Code steht in der
[CLI-Referenz](cli.md#edit-a-dashboard-spec-with-lsp).
