KI-CLI und offizieller Skill
Eine aufgabenorientierte Übersicht finden Sie unter SQL für KI-Agenten auf lokalen Daten. Diese Seite ist die vollständige Referenz zu Befehlen und Ausgabe.
Ohne Fenster ausführen
ducklocal --help listet zehn Unterbefehle:
| Befehl | Wirkung |
|---|---|
ducklocal query | Eine SQL-Anweisung ausführen und das Ergebnis als JSON ausgeben |
ducklocal schema | Auflisten, was sich abfragen lässt, mit Spalten; --stats für die Spaltenstatistik einer Relation |
ducklocal open | SQL, ein Dashboard oder Daten im laufenden Fenster zeigen; --state liest zurück, was es zeigt |
ducklocal check | Ein .dash-Dashboard prüfen |
ducklocal metrics | Die Metriken eines semantischen Modells auflisten; mit compile oder query kompilieren oder abfragen |
ducklocal comments | Review-Kommentare lesen und beantworten, die Personen an einem Dashboard hinterlassen haben |
ducklocal propose | Eine Dashboard-Änderung vorschlagen, die die Person prüfen und übernehmen kann |
ducklocal project | Einen portablen Analyseordner und seine Anforderungen prüfen; relink korrigiert verschobene Pfade |
ducklocal session | Zurücklesen, wie eine Analyse dorthin gelangt ist, wo sie ist |
ducklocal presence | Zeigen, wer an einem offenen Dashboard arbeitet und wo eine Bearbeitung landen wird |
ducklocal lsp, der Language Server, den Editoren für .dash-Dateien starten, und ducklocal profile, der alte Alias für schema --stats, funktionieren weiterhin, fehlen aber in --help.
propose, project und session sowie die Optionen --restricted, --wait und --if-revision sind in 0.4.0 hinzugekommen und werden in Agent-Workflows beschrieben. metrics und --format html sind neuer als 0.4.1: Sie sind auf dem Branch main und erscheinen mit dem nächsten Release. metrics wird in Semantische Metriken beschrieben.
ducklocal query führt SQL aus, ohne die GUI, den Verlauf, registrierte Dateien, Spracheinstellungen oder die globale GUI-Verbindung zu initialisieren. Jeder Aufruf erstellt eine eigene Verbindung. Wenn Sie DuckLocal ohne Befehle aufrufen – oder nur mit Dateipfaden, Ordnern und Glob-Mustern –, öffnet sich die normale GUI. Um einen GUI-Pfad zu öffnen, dessen Name mit einem Befehl übereinstimmt (query, schema, open, check, metrics, comments, propose, project, session, presence, profile oder lsp), stellen Sie ./ voran, etwa ./query.
Den Befehl installieren
DuckLocal unterstützt macOS 12+ auf Apple Silicon, Windows (x86_64) und Linux (x86_64). Die CLI läuft direkt aus der Anwendungsdatei, Sie brauchen also keine separate DuckDB-CLI.
Am schnellsten landet der Befehl über die App auf Ihrem PATH (ab 0.1.1): Öffnen Sie Befehlszeile & KI… – die Roboter-Schaltfläche in der Titelleiste oder das DuckLocal-Menü – und klicken Sie auf Befehl installieren. Derselbe Dialog installiert den Skill für KI-Agenten; siehe Den offiziellen Skill installieren. Wenn Sie die Installation überspringen, rufen Sie die ausführbare Datei an ihrem Ort auf:
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --helpAus einem Source-Checkout baut cargo build --locked./target/debug/ducklocal. Die Beispiele unten setzen voraus, dass ducklocal auf Ihrem PATH liegt. Ältere Releases haben möglicherweise kein query; prüfen Sie zuerst --help. JSON- und Parquet-Unterstützung ist eingebaut und wird nicht zur Abfragezeit heruntergeladen.
Abfrageoptionen
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"- Genau eines von
--sql SQLund--sql-file FILEist erforderlich. Dateien müssen UTF-8 sein;-liest von stdin. Das SQL muss genau eine Anweisung enthalten. Der Parser von DuckDB prüft das, bevor die Zieldatenbank geöffnet oder irgendetwas ausgeführt wird; Kommentare, Semikolons in Anführungszeichen und abschließende Semikolons sind in Ordnung. Skripte werden abgelehnt, nicht teilweise ausgeführt. --database PATHöffnet eine vorhandene Datei, standardmäßig schreibgeschützt. Ohne diese Option entsteht eine frische In-Memory-Datenbank.--read-writeerfordert--databaseund erlaubt ausdrücklich Schreibzugriffe und das Anlegen einer Datenbank (nicht der übergeordneten Ordner). Datenbankfehler fallen nie auf den Speicher zurück. Wenn DuckDB eine Datei ablehnt, beginnt die Fehlermeldung mit dem Grund, den DuckLocal aus dem Dateikopf liest – von einer neueren DuckDB geschrieben, eine Datei aus der v0.9-Zeit, eine SQLite-Datei oder überhaupt keine Datenbank – und damit, was stattdessen auszuführen ist (bei einer neueren Datei die Kopie perATTACH … (STORAGE_VERSION)/COPY FROM DATABASEfür jenes Release; bei SQLite dasATTACH, das sie liest), noch vor DuckDBs eigener Meldung.--limit Nist eine positive Ganzzahl, standardmäßig 1000, und begrenzt die zurückgegebenen Zeilen. Zusätzlich gilt ein Budget von 2.000.000 Zellen. Nach der Grenze zählt die CLI bis zu 100.000 weitere Zeilen, ohne deren Werte zu kodieren, und meldettotal_rowsundtotal_rows_exact. Das begrenzt die Ausgabe, nicht die Berechnung oder den Speicher: Sortierungen und Aggregate können weiterhin die gesamte Eingabe verarbeiten. Ein Ausführungsfehler nach der Ausgabegrenze lässt den Befehl trotzdem scheitern.--format json(der Standard) ist der unten beschriebene Vertrag.--format mdgibt dasselbe Ergebnis als Markdown-Tabelle aus, für ein Dokument oder einen Agenten, der sie liest.--format htmlgibt es als eine in sich geschlossene Webseite aus; siehe HTML-Ausgabe. Sonst ändert sich nichts: dasselbe SQL, dieselben Grenzen, dieselben Fehler.- Wiederholte oder unbekannte Flags, fehlende Werte, leeres SQL und ungültige Limits sind Fehler. Optionen verwenden getrennte Werte, nicht
--flag=value. Relative Pfade werden relativ zum Arbeitsverzeichnis des Prozesses aufgelöst, nicht zum Verzeichnis der SQL-Datei. Shell-Pfade in Anführungszeichen setzen; innerhalb von SQL Apostrophe verdoppeln ('O''Brien.csv'). SQL-Bezeichner stehen in doppelten Anführungszeichen.
Schreibgeschützt ist keine Dateisystem- oder Netzwerk-Sandbox. SQL wie COPY kann Dateien schreiben, auch wenn die Datenbank schreibgeschützt ist. Geben Sie Ausgabepfade, Überschreibungen, Datenbankänderungen, die Installation von Erweiterungen und externen Zugriff vor der Ausführung frei. DuckLocal installiert Erweiterungen nicht automatisch und wiederholt Vorgänge nicht. Ausdrückliches INSTALL/LOAD-SQL bleibt mit Freigabe möglich; installierte Erweiterungen können automatisch geladen werden. Ein gescheiterter Befehl kann bereits Nebenwirkungen gehabt haben (etwa vor einem Ausgabefehler); prüfen Sie das Ziel, bevor Sie es erneut versuchen.
Markdown-Ausgabe
--format md ist eine Darstellung, kein zweiter Vertrag: Die Werte sind die aus dem JSON, geschrieben so, wie das Ergebnisraster sie zeigt.
| Wert | Dargestellt als |
|---|---|
NULL | NULL |
| Ganze Zahl, Dezimalzahl, Float | genau die Ziffern, die der Wert trägt – ein DECIMAL(38,10) behält seine Skala, NaN/inf/-inf werden ausgeschrieben |
DATE | YYYY-MM-DD |
TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fffffffff], mit dem Bruchteil nur, wenn der Wert einen hat, und mit so vielen Ziffern, wie er hat. Es wird keine Zeitzone angehängt; --format json behält den Rohzähler |
TIME | HH:MM:SS[.ffffff] |
INTERVAL | wie DuckDB ihn schreibt: 1 month 2 days 00:00:00.000003 |
BLOB, GEOMETRY | 0x00ff, bei langer Ausgabe mit … gekürzt |
LIST, STRUCT, MAP | [1, 2], {x: 1}, ab 120 Zeichen mit … gekürzt |
Ein | in einer Zelle wird maskiert und ein Zeilenumbruch wird zu <br>, damit ein Wert die Tabelle nicht sprengt. Auf ein Ergebnis ohne Zeilen folgt _0 rows._, und auf ein Ergebnis, das durch --limit oder das Zellenbudget gekürzt wurde, folgt _Truncated at 2 of 5000 rows, so this is not the whole answer._ (of at least … jenseits der 100.000-Zeilen-Zählung) – eine Vorschau soll nicht wie eine vollständige Antwort klingen. Fehler bleiben unverändert: JSON auf stderr, leeres stdout.
HTML-Ausgabe
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html--format html schreibt dieselben Werte wie --format md als eine einzige Webseite:
- Zeilen- und Spaltenzahl, die verstrichene Zeit und das SQL hinter dem Ergebnis, eingeklappt.
- Die Spaltennamen mit ihren Typen. Zahlen sind rechtsbündig,
NULL-Werte sind markiert. - Ein Klick auf eine Spaltenüberschrift sortiert;
NULL-Werte bleiben am Ende. Eingaben im Filterfeld behalten nur die passenden Zeilen. - Ein Ergebnis, das
--limitoder das Zellbudget gekürzt hat, sagt das, wie in Markdown.
Stil und Skript sind eingebettet, und die Seite lädt nichts nach. Sie öffnet sich also direkt von der Festplatte und lässt sich unverändert veröffentlichen, etwa auf GitHub Pages. Jede Zelle wird HTML-maskiert.
Erfassen, was abfragbar ist
ducklocal schema beantwortet „Was gibt es, und welche Spalten hat es?“ in einem Aufruf, während DESCRIBE es Relation für Relation beantwortet. Es ist das Erste, was ein Agent ausführen sollte.
ducklocal schema ./data/ # files, folders, globs
ducklocal schema --database warehouse.duckdb # tables and views
ducklocal schema warehouse.duckdb --table orders # one relation, whole
ducklocal schema ./logs/ --full # everything, however largePATHs werden so aufgelöst wie beim Ablegen auf das Fenster: die Datendateien eines Ordners rekursiv (versteckte übersprungen, höchstens 256), die Treffer eines Glob und eine Datenbankdatei, als wäre sie mit --database angegeben. Zurück kommt ein JSON-Objekt:
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}| Feld | Bedeutung |
|---|---|
name | Der Pfad einer Datei wie angegeben (relativ zum Arbeitsverzeichnis, wenn sie darunter liegt), oder der Name einer Tabelle, wie SQL auf dieser Verbindung ihn erreicht: ohne Präfix im Standardschema, sonst schema.table |
kind | file, glob, table, view oder workbook |
from | Das SQL, das es liest, bereit nach FROM: ein Pfad in Anführungszeichen oder ein Bezeichner in Anführungszeichen, wo einer nötig ist |
rows | Die Schätzung des Katalogs für eine Tabelle, exakt für Parquet (aus seinem Footer), null, wo das Wissen einen Scan erfordern würde – CSV, JSON, Views |
column_count, columns | Die Spalten, wie DuckDB sie beschreibt |
files | Bei einem glob: wie viele Dateien er trifft |
Ein Glob, dessen Treffer alle dasselbe Format haben, ist eine Relation und wird so gelesen, wie ein source in .dash sie liest (ducklocal schema 'logs/*.csv'); --stats profiliert ihn als eine. Ein Glob über gemischte Formate und ein Ordner listen ihre Dateien einzeln auf.
Ein kleiner Katalog kommt vollständig zurück ("detail": "full"). Ab 12 Relationen oder 400 Spalten ist er stattdessen eine Zusammenfassung ("detail": "summary"). Die 5 Relationen mit den meisten Zeilen behalten ihre Spalten; die übrigen listen Name, Art, Zeilen und Spaltenzahl, und without_columns zählt sie. Für mehr nennt hint die beiden Wege: --table NAME für eine Relation (passend über ihren Namen, ihren reinen Tabellennamen oder den Namen einer Datei) und --full für alle. Eine Arbeitsmappe wird mit ihren sheets und ohne Spalten gelistet, da sie keine Tabellenfunktion hat; --stats liest ihr erstes Blatt. Ein PATH, der nicht existiert, oder ein --table, das nichts benennt, ist Exit 2.
Gzip-komprimierter Text wie .json.gz und .csv.gz ist hier eine Datendatei, ebenso wie für source-Blöcke und das Fenster. Eine Datei, deren Datensätze in einer einzigen Liste liegen – etwa CloudTrails {"Records": [...]} –, kommt mit einem hint zurück: dem SQL, das diese Datensätze als Zeilen liest, weil die eine Zeile und die eine Spalte sonst nur den Wrapper beschreiben.
Dateien erkunden und konvertieren
Nachdem bestätigt ist, dass die Datei tatsächlich existiert:
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"Raten Sie nicht, dass amount existiert: Führen Sie zuerst ducklocal schema oder DESCRIBE aus. Berechnen Sie vollständige Aggregate in SQL, statt eine gekürzte Vorschau zu summieren. CLI-Aufrufe teilen weder die registrierten Views der GUI noch ihre In-Memory-Tabellen untereinander. Persistieren Sie ausdrücklich, wenn es nötig ist:
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"Ein Konflikt um die Datenbanksperre ist ein Fehler. Schließen Sie den anderen Schreiber (auch die GUI) oder verwenden Sie eine freigegebene Kopie; löschen Sie niemals Sperrdateien und legen Sie nicht stillschweigend eine andere Datenbank an.
JSONL und verschachteltes JSON
read_ndjson_objects ist der Leser für zeilengetrenntes JSON (ein Objekt pro Zeile, .jsonl/.ndjson); read_json/read_json_auto lesen JSON-Dokumente (ein Array oder ein einzelnes Objekt). Nennen Sie den Leser für eine JSONL-Datei ausdrücklich, statt sich auf die automatische Erkennung zu verlassen. json_extract_string(col, '$.a.b[0].c') durchläuft einen verschachtelten Pfad – Objektschlüssel und Array-Indizes – und liefert VARCHAR:
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"Verwenden Sie stattdessen json_extract, wenn das Blatt kein String ist und Sie es als JSON möchten.
Spaltenstatistiken
ducklocal schema --stats beantwortet die Fragen, die ein Diagramm, eine Skala und ein Zahlenformat entscheiden, bevor etwas darauf aufgebaut wird. DESCRIBE sagt, dass eine Spalte DOUBLE ist; ihre Statistik sagt, dass sie zwei Nachkommastellen nutzt, dass ihr größter Wert tausendmal so groß wie ihr Median ist und dass ihre Daten in der Mitte elf Tage überspringen.
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats--stats profiliert eine Relation: die einzige, die die Argumente benennen, oder die, die --table auswählt – zwei oder mehr ohne --table ist Exit 2, mit einem Hinweis darauf. Es lässt sich nicht mit --full kombinieren. ducklocal profile TARGET [--database PATH] aus früheren Releases liefert denselben Bericht und funktioniert weiterhin.
Die Relation ist eine Datendatei – csv, tsv, txt, parquet, json, ndjson, jsonl – oder eine Arbeitsmappe (xlsx, xls, xlsb, ods; ihr erstes Blatt wird als TEMP-Tabelle importiert und profiliert) oder, mit --database, der Name einer Tabelle oder View. Ein Name mit Punkt wird als schema.table gelesen und jeder Teil in Anführungszeichen gesetzt, sodass ein Name mit Leerzeichen oder Großbuchstaben so funktioniert, wie er geschrieben ist. Eine Relation, die nichts benennt, ist ein Argumentfehler (Exit 2), kein SQL-Fehler.
Zurück kommt ein JSON-Objekt: target, relation (das SQL, gegen das die Statistiken liefen), row_count, elapsed_ms und columns in der Reihenfolge der Relation. Pro Spalte:
| Feld | Bedeutung |
|---|---|
name, type | wie DESCRIBE sie meldet |
nulls | Zeilen, in denen die Spalte NULL ist |
distinct | exakt, nicht geschätzt |
unique | vorhanden und true, wenn distinct gleich row_count ist |
min, max | als Text, damit ein DECIMAL seine Ziffern behält |
decimals | Ziffern nach dem Punkt, die die Spalte tatsächlich nutzt, was nicht ihre deklarierte Skala ist |
median | ein Wert, den die Spalte enthält, keine Interpolation zwischen zwei Werten |
max_over_median | wie oft der größte Wert größer als der Median ist – die Zahl, die zwischen linearer und logarithmischer Achse entscheidet |
covered_days, span_days, missing_days | Tage, die die Spalte benennt, Tage zwischen ihren Enden und die Differenz: 0 ist eine durchgehende Reihe, alles andere sind Lücken, über die eine Linie hinwegzeichnen würde |
decimals, median und max_over_median erscheinen bei numerischen Spalten; die Tagesfelder bei Daten und Zeitstempeln. Spalten vom Typ LIST, STRUCT, MAP und UNION melden nur nulls – min und max sind auf ihnen nicht definiert.
Eine Textspalte, die Zahlen und ein kurzes Wort wie Rs NA enthält, meldet zusätzlich null_marker und null_marker_rows. Der Bericht ergänzt dann einen hint, der den read_csv-Aufruf nennt, der die Spalte als Zahlen liest.
Statistiken sind exakt und lesen die ganze Relation, kosten also einen vollständigen Scan. --limit gilt nicht: Ein Profil einer Stichprobe ist kein Profil.
Arbeit im laufenden Fenster zeigen
ducklocal open übergibt etwas an das bereits laufende DuckLocal-Fenster – und startet eines, wenn keines läuft – und holt es nach vorn. So legt ein Agent seine Arbeit einer Person vor, die dort weiterarbeiten kann:
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch- PATHs öffnen sich so, wie ein Ablegen auf das Fenster sie öffnet: eine
.dash-Datei als Tab, eine DuckDB-Datenbankdatei als Datenbank des Fensters, Datendateien, Ordner und Globs als angehängte Views. Relative PATHs werden relativ zum Verzeichnis des Befehls aufgelöst. Eine Anfrage, die eintrifft, während das Fenster noch startet, wartet, bis sein Start-Öffnen abgeschlossen ist. --sqloder--sql-file(-liest stdin) öffnet einen neuen Abfrage-Tab mit dem Titel aus--title.--runführt die Abfrage aus, sobald die PATHs angehängt sind.--no-launchschlägt mit der Artnot_runningfehl, statt ein Fenster zu starten – für einen Rechner, auf dem ein ungefragt erscheinendes Fenster unerwünscht wäre.
Erfolg gibt {"delivered": true, "launched": BOOL} aus: die Übergabe, kein Ergebnis. Was sich öffnet, läuft in der eigenen Sitzung des Fensters – seiner Verbindung, seinen angehängten Views, seinem Verlauf – und jeder Fehler erscheint dort, nicht auf stdout. Exit 2 bei Argumentfehlern; 1 mit der Art not_running (kein Fenster erreichbar), refused (das Fenster hat die Anfrage abgelehnt) oder launch.
Das Fenster lauscht auf einem Loopback-Port. Es schreibt den Port und ein zufälliges Token in eine Datei, die nur Ihr Konto lesen kann (siehe Einstellungen und App-Daten); ein anderer Benutzer auf dem Rechner oder eine Webseite, die auf localhost zielt, kann es nicht erreichen.
Lesen, was das Fenster zeigt
ducklocal open --state geht den umgekehrten Weg: Es öffnet nichts, startet nie ein Fenster und gibt aus, was das laufende Fenster zeigt – so kann ein Agent dort ansetzen, wo eine Person aufgehört hat, statt sie zu bitten, ihre Abfrage einzufügen.
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}databaseist die geöffnete Datenbankdatei oder":memory:";attachedlistet die Dateien, die das Fenster als Views registriert hat, mit dem View-name. Eine CLI-Abfrage kann diese Views nicht lesen – verwenden Sie denpath.- Ein Abfrage-Tab hat
sql, den Text des Editors unabhängig davon, ob er lief, undresult:statusistempty,running,rows,affected,failed,explainoderprofile. Bei Zeilen:columns,row_count,truncated,preview(die ersten 20 Zeilen, wie das Raster sie zeigt, als Strings),elapsed_msund dassql, das sie erzeugt hat; beiaffectedcountundelapsed_ms; bei einem Fehlererror. - Sobald die Person im Chart-Tab Spalten gewählt hat, hat ein Ergebnis auch
chart:type,x,y,splitunddash, also einenquery- und einenplot-Block, die dasselbe Diagramm in einem Dashboard zeichnen. explainist, was Explain zeigt:plan, dieEXPLAIN-Ausgabe von DuckDB als Array von Textzeilen, undelapsed_ms.profileist, was Profile zeigt (siehe SQL-Editor):plan, den vonEXPLAIN ANALYZEgemessenen Operatorbaum als Array von Wurzeln, jede{operator, seconds, rows, estimated, children}–secondsist die Eigenzeit des Operators ohne seine Kinder,rows, was er produziert hat,estimateddie Schätzung des Optimierers fürrows(null, wo der Plan keine nennt),childrendieselbe Form erneut.operator_secondsist die Summe der Eigenzeiten aller Operatoren, also das, wozu sich die Anteile addieren, nicht die Wanduhr;elapsed_msist der ganze Lauf.- Ein Dashboard-Tab hat
path,unsavedunddashboard: dessencomments_file-Pfad,plots(Name, Typ, Titel, Abfrage, Zeilen,open_commentsundfailure, wenn eines nicht zeichnen kann) und seinefiltersmit dem, was jeder gewählt hat:picked,value(der erste Wert),values(jeder gewählte Wert, in Reihenfolge) undmultiple.value: nullmitpicked: truebedeutet, dass der NULL-Wert gewählt wurde.
Mit --state sales.dash bleiben nur Tabs übrig, die dieses Dashboard zeigen, mit --state --active nur der aktive Tab. Ein Pfad, der nicht offen ist, liefert Exit 1, Art not_open, mit den offenen Dashboards im Hinweis. active_tab ist der Index des aktiven Tabs innerhalb der zurückgegebenen tabs oder null, wenn er nicht darunter ist; database und attached bleiben enthalten.
--state akzeptiert entweder einen .dash-PATH oder --active, nicht beides. --no-launch wird akzeptiert und ändert nichts. Andere Optionen, auch --sql und --run, sind ungültig (Exit 2). Exit 1 mit der Art not_running, wenn kein Fenster läuft, und timeout, wenn es nicht innerhalb von 5 Sekunden antwortet.
Eine Dashboard-Spezifikation prüfen
Das Format selbst – Blöcke, Attribute, Diagrammtypen, SQL-Regeln und häufige Meldungen – ist in Dashboards (.dash) beschrieben; dieser Abschnitt behandelt den Befehl.
Eine .dash-Datei deklariert ein Dashboard so, wie Terraform Infrastruktur deklariert – Abfragen und Diagramme als Blöcke, Verweise dazwischen –, statt es zu skripten. Sie ist für eine Person oder einen Agenten leicht zu schreiben und zu diffen.
query "latency" {
sql = <<SQL
SELECT timestamp, service, avg(latency) AS latency
FROM logs
GROUP BY timestamp, service
SQL
}
plot "latency" {
type = "line"
query = query.latency
x = timestamp
y = latency
series = service
}ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summaryEin source-Block benennt Datendateien, relativ zur .dash-Datei, die die Abfragen lesen, und ein view-Block hält SQL, das mehrere Abfragen teilen. Ein query-Block enthält ein sql-Attribut – eine schreibgeschützte Anweisung, als Heredoc oder als String. SELECT, WITH, FROM-first, VALUES, SHOW, DESCRIBE, SUMMARIZE und PIVOT werden akzeptiert; alles, was schreiben könnte – DDL, DML, COPY, ATTACH, INSTALL –, ist eine Diagnose, und die GUI weigert sich, es auszuführen, weil die Abfragen eines Dashboards bei jedem Öffnen der Datei laufen. Ein plot-Block enthält type (eines von line, bar, stacked_bar, area, scatter, pie, heatmap, histogram, map, timeline, table, card, text), query (einen Verweis wie query.latency auf einen Abfrageblock derselben Datei), seine Spalten und optional title und width. Ein filter-Block macht ein Balkendiagramm oder eine Tabelle klickbar – einen Wert, oder mehrere mit multiple = true an einem Balken –, und eine Abfrage liest die Auswahl als $name. # und // kommentieren bis zum Zeilenende. Dashboards (.dash) enthält jedes Attribut.
Ein text-Diagramm ist die Ausnahme: Es enthält title, text oder beides und nimmt keine query. Karten können außerdem note und tone verwenden; siehe Karten und Textbereiche.
Zuerst die statischen Prüfungen: das SQL jeder Abfrage durch den echten DuckDB-Parser auf einer Wegwerf-Verbindung, so wie query vor dem Ausführen prüft, und jedes $name gegen die Filterblöcke – das SQL wird mit jedem $name als TRUE geparst und ausgeführt, was dem entspricht, was das Dashboard ausführt, bevor etwas gewählt ist.
Dann läuft jede Abfrage, genau wie das Öffnen des Dashboards sie ausführen würde – schreibgeschützt, mit ihren Quellen, über denselben Codepfad und dasselbe Zeilenbudget –, und die Spalten jedes Diagramms werden gegen die Spalten geprüft, die die Abfrage tatsächlich zurückgibt: ein y, das nicht numerisch ist, ist ein Fehler für jeden Diagrammtyp, ebenso nicht-numerische Koordinaten oder size einer Karte, und ebenso eine Filter-column, die die Abfrage ihres Diagramms nicht zurückgibt.
- 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, kann für eine Datenbank gedacht sein, die der Prüfung nicht mitgegeben wurde: Sie wird unterunresolved(Abfrage, Zeile, Grund) gelistet statt als Fehler behandelt, und die Spalten ihrer Diagramme bleiben ungeprüft. - Mit
--database PATH(vorhandene Datei, schreibgeschützt) laufen sie auf dieser Datenbank. Übergeben Sie sie immer, wenn die Abfragen Tabellen einer Datenbank lesen: Alles unterunresolvedblieb ungeprüft.
Jede Abfrage, die einen Filter liest, wird zusätzlich mit einem gewählten Wert gebunden, ohne diese Variante auszuführen. Das fängt eine Filterspalte ab, die in einer konsumierenden Abfrage fehlt, auch wenn die erste Variante mit $name = TRUE funktioniert. Ein Filter muss außerdem auf eine Spalte verweisen, die sein auswählendes Diagramm zurückgibt.
Ausführen statt nur Planen ist wichtig: Manche Fehler, etwa eine Umwandlung, die der Build nicht durchführen kann, oder ein Wert, der sich nicht konvertieren lässt, zeigen sich erst, wenn Zeilen gelesen werden, und eine Prüfung, die sie durchgehen lässt, würde ein Dashboard übergeben, das nicht zeichnen kann. Abfragen laufen vollständig, eine Prüfung gegen eine große Datenbank dauert also so lange wie das Öffnen des Dashboards.
Erfolg ist ein JSON-Objekt, das die Quellen der Datei (mit jedem resolved-Pfad), die Views, die Abfragen (mit ihren Ergebnisspalten und rows, wie viele jede ohne Auswahl zurückgab, plus truncated: true, wenn das Zeilenbudget des Dashboards sie abgeschnitten hat), die Filter (mit den queries, die jeden lesen), die Diagramme, unresolved und empty – die Abfragen, die liefen und keine Zeilen zurückgaben – auflistet. Eine leere Abfrage besteht jede andere Prüfung, ist aber meist ein regulärer Ausdruck, ein Filter oder ein Join, der nichts traf; sehen Sie sich jede an. Mit --summary ist Erfolg eine kompakte JSON-Zeile:
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}Die fünf Blockfelder sind Anzahlen; unresolved listet die Abfragen, die nicht geprüft werden konnten, und empty die, die keine Zeilen zurückgaben.
Ein fehlerhafter Block wird ausgelassen, während gültige Blöcke weiter durch die Validierung laufen. Spezifikationsfehler und Abfragefehler werden im selben Lauf gesammelt, je ein file:line: message. Existiert eine Spezifikationsdiagnose, ist der Exit 2 mit der Art spec; scheitert nur die SQL-Ausführung oder -Bindung, ist er 1 mit der Art sql. Datenbank- und I/O-Fehler enden ebenfalls mit 1. --summary verbirgt keine Diagnosen.
Dieselbe Datei öffnet sich als Dashboard-Tab in der GUI – ducklocal dashboard.dash, ducklocal open dashboard.dash oder per Ziehen auf das Fenster –, mit Diagrammen auf einem 12-Spalten-Raster, und ein Diagramm, das nicht zeichnen kann, zeigt den Grund direkt an. Siehe Dashboards (.dash).
Metriken aus einem semantischen Modell
ducklocal metrics # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
--views reports/investigation.dash --restricted --allow-read dataducklocal metrics liest ein Apache-Ossie-Modell, model.ossie.yaml, und listet seine Metriken und Felder. compile gibt das eine DuckDB-SELECT aus, das eine Anfrage beantwortet, und liest keine Daten; query führt es aus wie ducklocal query und fügt ein semantic-Objekt mit dem SQL und dem sha256 des Modells hinzu. Eine Anfrage, die das Modell nicht exakt beantworten kann, wird abgelehnt, mit Exit-Code 2 und einem kind wie metric_fanout. Semantische Metriken beschreibt das Modellformat, jede Option und jede Ablehnung.
Review-Kommentare zu einem Dashboard
Personen prüfen ein Dashboard, indem sie seine Diagramme im Fenster kommentieren – mit dem Zeiger auf ein Diagramm und einem Klick auf die Sprechblase (siehe Mit Kommentaren prüfen). ducklocal comments ist die Seite des Agenten: Es liest die Threads und beantwortet sie, ohne Fenster.
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"- Ohne Aktion werden die offenen Threads ausgegeben:
{file, comments_file, open, threads}.--allschließt erledigte ein. - Jeder Thread hat
id,plotund was der Agent braucht, um ihn in der Spezifikation zu finden:plot_title,plot_queryundplot_lines, die erste und die letzte Zeile desplot-Blocks (null, wenn die Spezifikation nicht parst).plot_missingisttrue, wenn kein Diagramm dieses Namens mehr übrig ist. Dannresolvedundcomments, jeweils mitauthor(useroderagent), bei einem Kommentar eines Agenten dessenname(der Name, denpresencezeigt),textundat(RFC 3339, lokale Zeit). --reply ID --text TEXTfügt die Antwort des Agenten hinzu. Eine Antwort auf einen erledigten Thread öffnet ihn wieder, sofern nicht auch--resolveangegeben ist.--resolve IDund--reopen IDändern den Zustand eines Threads;--add PLOT --text TEXTstartet einen Thread, signiert als der Agent.- Die Nummer eines Threads funktioniert als seine ID:
--reply 1bedeutetc1.--addlehnt ein Diagramm ab, das die Spezifikation nicht hat (Exit 2), und der Hinweis listet ihre Diagramme auf. - Eine Aktion gibt
{thread}aus, wie er geändert wurde.
Die Threads liegen neben der Spezifikation, in FILE.comments.json. Ein laufendes Fenster bemerkt eine Änderung innerhalb einer Sekunde und zeigt sie am Diagramm. Eine unbekannte Thread-ID ist Exit 2, mit einem Hinweis zum Auflisten der Threads; eine Spezifikationsdatei, die nicht existiert, ist Exit 1.
Ein Review von Anfang bis Ende: die offenen Threads lesen, die Spezifikation bearbeiten, ducklocal check ausführen, dann jeden Thread mit dem, was sich geändert hat, beantworten und mit --resolve abschließen. Verwenden Sie --reply ohne --resolve, um der Person eine Rückfrage zu stellen.
Agentenaktivität zeigen
check und comments teilen einem laufenden Fenster automatisch mit, an welchem Dashboard der Agent arbeitet. presence kann eine Bearbeitung ankündigen, bevor sie geschieht:
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle--doingakzeptiertreading,editingoderidle(doneist ein Alias füridle).--plotnimmt kommagetrennte Diagrammnamen. Beieditingsind neue Namen erlaubt und erscheinen als Platzhalter. Beireadingoderidleist ein unbekannter Name Exit 2.- Der angezeigte Name kommt aus
--agent, dannDUCKLOCAL_AGENT, dann der erkannten Agentenumgebung (Claude, Codex, Cursor oder Gemini), mit Rückfall aufAgent. - Die Ausgabe ist
{delivered}. Ohne laufendes Fenster entsteht{"delivered":false}ohne Fehler und ohne ein Fenster zu starten.
Der Name bleibt in der Ecke des Dashboards, solange Befehle die Sitzung aktiv halten. Klicken Sie ihn für das Aktivitätsprotokoll an. Dreißig Sekunden Stille oder --doing idle beenden die Sitzung; geänderte und hinzugefügte Diagramme bleiben markiert, bis sie angesehen wurden, und Hinweise auf entfernte Diagramme, bis sie verworfen werden. Siehe Einen Agenten bei der Arbeit sehen.
Eine Dashboard-Spezifikation mit LSP bearbeiten
ducklocal lsp ist ein Language-Server-Protocol-Server für .dash-Dateien über stdio, den Editoren starten. Er gibt jedem LSP-fähigen Editor, was der Spezifikationseditor der GUI selbst hat:
- Diagnosen: die, die
checkmeldet, veröffentlicht bei jedem Öffnen und jeder Änderung (Volltext-Synchronisierung, alle mit Schweregrad Error – es sind Fehler, kein Stil). - Vervollständigung: Blocktypen, Attributnamen, Diagrammtypen und die Namen nach
query.undplot., jeweils mit einer Textänderung, die das gerade getippte Wort ersetzt. - Hover: Dokumentation für Blöcke, Attribute und Verweise.
- Zur Definition springen: von einem Verweis
query.nameoderplot.namezum Namen seines Blocks.
Mit --database PATH wird das SQL jeder Abfrage zusätzlich vom echten DuckDB-Parser validiert, so wie check --database es tut.
Richten Sie die generische LSP-Unterstützung Ihres Editors für *.dash-Dateien auf ducklocal lsp – der Befehl nimmt keine Dokumentargumente; der Editor spricht über stdio mit ihm. In Neovim (0.10+):
vim.api.nvim_create_autocmd("FileType", {
pattern = "dash",
callback = function(event)
vim.lsp.start({
name = "ducklocal",
cmd = { "ducklocal", "lsp" },
root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
})
end,
})In VS Code tut jede generische LSP-Erweiterung dasselbe mit dem Befehl ducklocal, den Argumenten ["lsp"] und dem Dokumentselektor dash. Exitcodes: 0 nach einem sauberen shutdown/exit, 1, wenn der Client ohne eines verschwindet, 2 bei einer fehlerhaften Befehlszeile oder einem gescheiterten Protokoll-Handshake.
JSON-Vertrag
Erfolgreiche Abfragen schreiben genau ein JSON-Objekt nach stdout, gefolgt von einem Zeilenumbruch:
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}columns und jede Zeile bewahren die Spaltenreihenfolge und doppelte Spaltennamen. type ist die Arrow-Debug-Darstellung, nicht der ursprüngliche DuckDB-SQL-Typname (HUGEINT und DECIMAL können sich etwa einen Arrow-Träger teilen). row_count zählt zurückgegebene Zeilen. total_rows zählt die erzeugten Zeilen, einschließlich der nach der Ausgabegrenze gezählten; total_rows_exact: false bedeutet, dass das Zählen nach bis zu 100.000 weiteren Zeilen aufhörte, diese Summe also eine Untergrenze ist. Keine der beiden Zahlen ist eine Anzahl betroffener Zeilen. elapsed_ms misst Vorbereitung, Ausführung und Zeilenkodierung, nicht das Laden von Dateien oder den Verbindungsaufbau. Ergebnisse ohne Zeilen behalten ihre Metadaten. DDL/DML legen das tatsächliche DuckDB-Ergebnis offen, einschließlich Count-Spalten: INSERT/COPY liefern üblicherweise [[N]]; CREATE TABLE liefert üblicherweise keine Zeilen. Sie werden nicht am ersten SQL-Schlüsselwort klassifiziert.
Kodierungen von Zellen:
| SQL-Wert | JSON-Kodierung |
|---|---|
| NULL | null (nie der String "NULL") |
| Boolean, endlicher Float | JSON-Boolean/JSON-Zahl |
| Ganzzahl innerhalb ±9.007.199.254.740.991 | JSON-Zahl |
| Größere Ganzzahl, auch HUGEINT/UHUGEINT | {"encoding":"integer","value":"9007199254740992"} |
| Dezimalzahl | {"encoding":"decimal","value":"123.450"} mit exaktem Dezimaltext |
| Text, Enum | JSON-String |
| Blob, Geometrie | {"encoding":"hex","value":"00ff"}; Kleinbuchstaben-Bytes, Geometrie verwendet WKB |
| Datum | {"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}; Tage seit 1970-01-01 |
| Zeitstempel | {"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}; vorzeichenbehaftete Zählung seit der Unix-Epoche; die Einheit kann auch Second/Millisecond/Microsecond sein |
| Zeit | {"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}; Zählung seit Mitternacht |
| Intervall | {"encoding":"interval","months":1,"days":2,"nanos":"3000"} |
| NaN, positive/negative Unendlichkeit | {"encoding":"float","value":"NaN"} / "inf" / "-inf" |
| Liste, Array | JSON-Array, rekursiv kodiert (auch verschachtelte Nullen) |
| Struct | {"encoding":"struct","fields":[["name",VALUE],...]} |
| Map | {"encoding":"map","entries":[[KEY,VALUE],...]}; kein JSON-Objekt, damit Schlüssel ihre Typen behalten |
| Union | {"encoding":"union-value","value":VALUE}; nur der aktive Wert, das Mitglieds-Tag bleibt nicht erhalten |
Temporale values sind exakte Zählungen, es geht also keine Bruchteilsgenauigkeit verloren; Unendlichkeits-Sentinels von Datum und Zeitstempel bleiben rohe Zählungen. Daneben ist iso derselbe Wert als ISO-8601-Text zum Lesen, mit so vielen Bruchziffern, wie die Einheit fasst. Ein Zeitstempel aus einer Spalte mit Zeitzone (Arrow-Metadaten) ist ein UTC-Zeitpunkt, und sein iso endet auf Z. --format md stellt Daten und Zeitstempel ebenfalls lesbar dar. Weil der festgelegte Arrow-Wrapper von DuckDB verschachtelte HUGEINT, UHUGEINT und DECIMAL(38,0) nicht unterscheiden kann, erzeugen Nicht-NULL-Vorkommen einen klaren Fehler, statt stillschweigend Vorzeichen oder Genauigkeit zu ändern. Casten Sie solche Felder in SQL ausdrücklich nach VARCHAR. Unbekannte nicht unterstützte Typen erzeugen ebenfalls einen Fehler; verwechseln Sie einen Fehler nicht mit einem leeren Ergebnis. Die Union-Kodierung ist eine Darstellung des aktiven Werts, kein verlustfreier Roundtrip einer Union.
Fehler schreiben ein JSON-Objekt nach stderr und lassen stdout leer:
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}hint ist da, wenn der nächste Schritt bekannt ist, in den Begriffen dieser CLI selbst: das Flag, das ein falsch geschriebenes hätte sein sollen, --read-write für einen Schreibvorgang, der auf einer schreibgeschützten Datenbank abgelehnt wurde, ducklocal schema für eine Tabelle, die nicht existiert, TRY_CAST für einen Wert, der sich nicht konvertieren lässt, das Aufteilen eines Skripts mit mehr als einer Anweisung, oder AS für ein Schlüsselwort, das als reiner Spaltenalias verwendet wird (SELECT count(*) AS minutes, oder setzen Sie es in Anführungszeichen). Ein Agent sollte darauf reagieren, bevor er das SQL neu schreibt. Er fehlt, wenn DuckDBs eigener Meldung nichts hinzuzufügen ist, etwa bei einem Syntaxfehler.
Exitcodes: 0 Erfolg, 2 ungültige Argumente/Anweisungsanzahl, 1 SQL-, Datenbank-, I/O- oder Ausgabefehler. Die Fehlerarten sind argument, sql, database, io, output, spec für check und not_running, not_open, refused, timeout oder launch für open. Prüfen Sie den Exit-Status, bevor Sie stdout parsen, und truncated, bevor Sie Vollständigkeit melden. Hilfe und Version sind reine Textausnahmen. Transportfehler wie eine geschlossene stdout-Pipe können keinen leeren oder vollständigen Ausgabestrom garantieren.
Den offiziellen Skill installieren
Der Skill bringt einem Agenten die Gewohnheiten bei, die seine Antworten ehrlich halten: das Schema prüfen, eine begrenzte Stichprobe ansehen, Aggregate in SQL berechnen, truncated prüfen und aus zurückgegebenen Werten antworten. Er deckt Schema-Einsicht, Spaltenstatistiken, Konvertierungen, Datenbankabfragen, .dash-Dashboards und ihre Review-Kommentare sowie das Übergeben von Arbeit an das Fenster und das Zurücklesen ab; er bietet keinen S3-Browser, raumspezifische Befehle, Sitzungsgedächtnis oder einen MCP-Server.
Aus der App. Öffnen Sie Befehlszeile & KI… (die Roboter-Schaltfläche in der Titelleiste oder das DuckLocal-Menü):
- Befehl installieren legt
ducklocalauf IhrenPATH, sodass die Shell eines Agenten ihn ausführen kann. - Zu Claude Code hinzufügen schreibt den Skill nach
~/.claude/skills/ducklocal, wo Claude Code ihn in jedem Projekt findet. Es werden nur die beiden Dateien des Skills geschrieben; alles andere in diesem Ordner bleibt erhalten. Wenn ein DuckLocal-Update einen neueren Skill mitbringt, bietet der Dialog Skill aktualisieren an. - Kurzanleitung kopieren kopiert eine kurze Erklärung für jeden anderen Agenten – Codex, Cursor, ein Chatfenster –, die den Befehl und seine Verwendung nennt.
Von Hand. Der Skill ist skills/ducklocal. Um ihn stattdessen einem einzelnen Projekt hinzuzufügen (Beispiel für Claude Code):
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/Prüfen Sie ein vorhandenes Ziel zuerst, statt lokale Änderungen zu überschreiben. Andere Agenten können dieselbe SKILL.md plus references/cli.md in ihrem unterstützten Skill-Verzeichnis verwenden.
