Dashboards (.dash)
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, um Änderungen zu wünschen.
Ein vollständiges Beispiel
Dieses Dashboard fragt die Beispieldatei des Tutorials ab. Laden Sie sales.dash in dasselbe Verzeichnis wie sales.csv herunter und öffnen Sie es dann.
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).
Diagramme liegen auf einem 12-Spalten-Raster: Jedes spannt seine width, 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 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 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
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 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, ohne Fenster:
ducklocal comments sales.dash{
"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:
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolveDas 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 lehrt diese Schleife, ein Agent damit muss also nur „bearbeite die Kommentare zu sales.dash“ hören.
Neu in 0.4.0
Ein Agent kann eine Änderung vorschlagen, 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
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 beschreibt die Optionen. Diese Anzeigen zeigen lokale Aktivität; sie senden keine Arbeit an einen Agenten.
Blöcke
Eine Datei ist eine Folge von Blöcken, jeder ein Typ, ein Name in Anführungszeichen und ein Rumpf:
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.
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:
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 oder als String |
Ein Abfrageblock enthält sql und sonst nichts. Er kann $name für einen Filter 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. 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.
dashboard
Ein optionaler dashboard-Block hält Einstellungen für die ganze Datei:
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
| 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 |
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.
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
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:
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
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:
plot "revenue_total" {
type = "card"
query = query.totals
value = revenue
format = "usd0"
delta = growth
delta_format = "pct1"
note = "vs last week"
}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
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); 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
Ein Filter macht ein Diagramm klickbar und lässt den dort gewählten Wert andere Abfragen einengen:
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 = truefü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
$channelalsTRUE, 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.
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
Ein Heredoc enthält Text über mehrere Zeilen – in der Praxis SQL:
sql = <<SQL
SELECT 1
SQL- Das Trennwort nach
<<ist ein beliebiges Wort (SQLper 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
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,PIVOTundUNPIVOT. - Abgelehnt: alles, was Daten oder Dateien ändern könnte –
CREATE,INSERT,UPDATE,DELETE,DROP,COPY,ATTACH,INSTALL,LOADund so weiter. Das Öffnen einer.dash-Datei, die Ihnen jemand geschickt hat, kann Ihre Daten nicht ändern. - Eine Anweisung pro Abfrage.
- Ein
PIVOTin einer anderen Abfrage nennt seine Werte. Eine Abfrage, die mitPIVOTbeginnt, darf die Werte DuckDB überlassen (PIVOT orders ON channel USING sum(amount)). Eines, das in einemSELECToder einemWITHverschachtelt ist, braucht eine ausdrückliche Liste:ON channel IN ('Web', 'Store'). $namemuss einen Filterblock benennen. Die Schreibschutzprüfung beurteilt das SQL mit jedem$namealsTRUE. 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-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
ducklocal check validiert eine Datei, ohne ein Fenster zu öffnen – der Schritt, den Sie ausführen, bevor Sie jemandem ein Dashboard übergeben:
ducklocal check sales.dash
ducklocal check sales.dash --database warehouse.duckdb
ducklocal check sales.dash --summaryZuerst 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
--databaselaufen die Abfragen im Speicher, was alles ist, was ein Dashboard über seine eigenensource-Dateien braucht. Eine Abfrage, die eine Tabelle liest, die keine Quelle definiert, wird unterunresolvedgelistet, statt als Fehler zu gelten, und die Spalten ihrer Diagramme bleiben ungeprüft – sie ist vermutlich für eine Datenbank gedacht. - Mit
--database PATHlaufen 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 enthält die Details.
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.
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 |
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.
