ducklocal schema ./data/Relationen entdecken
Dateien, Tabellen, Views und ihre Spalten auflisten, bevor Sie SQL schreiben.
Geben Sie Claude Code, Codex, Cursor und anderen Coding-Agenten einen headless DuckDB-Workflow für CSV-, Parquet-, JSON- und DuckDB-Daten. Keine GUI-Automatisierung, kein Datenbankserver und keine eigene API nötig.
Die CLI gibt standardmäßig JSON aus und verwendet eindeutige Exit-Codes für Fehler bei Argumenten, SQL und I/O.
Der offizielle Workflow hindert einen Agenten daran, Spaltennamen zu raten oder eine Teilvorschau für den ganzen Datensatz zu halten.
Führen Sie ducklocal schema ./data/ aus, um Relationen, direkt abfragbare FROM-Ausdrücke, Spalten und Typen zu erhalten. Große Kataloge liefern eine Zusammenfassung mit Hinweisen zum Tiefergehen.
Nutzen Sie eine SQL-Anweisung und ein kleines --limit, um repräsentative Zeilen anzusehen. Prüfen Sie den Exit-Status des Befehls und das JSON-Feld truncated.
Führen Sie Filter, Joins und Aggregationen in DuckDB aus, statt eine gekürzte Vorschau im Kontext des Agenten zu summieren. Geben Sie nur die Belege zurück, die die Antwort braucht.
Jeder Agent braucht zwei Dinge: den Befehl ducklocal in seinem PATH und eine Anleitung, wie er ihn benutzt. Beides kommt aus Command line & AI… in der App (der Roboter-Knopf in der Titelleiste oder das DuckLocal-Menü).
Klicken Sie auf Install command und dann auf Add to Claude Code. Der Skill wird nach ~/.claude/skills/ducklocal geschrieben, wo Claude Code ihn in jedem Projekt findet. Passt eine Anfrage dazu, lädt Claude Code den Skill und folgt dem Schema-zuerst-Workflow, ohne dass man es ihm sagen muss.
# In any project, ask in plain language:
Which channel brought in the most revenue in data/sales.csv?
Use DuckLocal and show me the query.
Um den Skill nur in einem Projekt zu nutzen, kopieren Sie skills/ducklocal in das .claude/skills/ dieses Projekts.
Klicken Sie auf Install command und dann auf Copy brief, und fügen Sie die Anleitung in AGENTS.md im Stammverzeichnis Ihres Projekts ein. Codex liest diese Datei zu Beginn einer Sitzung. Die Anleitung, gekürzt:
DuckLocal is installed on this machine. Its command, ducklocal, runs DuckDB SQL over local CSV, TSV, Parquet, JSON and Excel files and databases, and prints JSON. - Start with `ducklocal --help` for the options. - See what there is to query, with columns, before writing SQL: `ducklocal schema ./data/` (or `--database file.duckdb`). - Profile what you will chart or summarize: `ducklocal schema data.csv --stats`. - Compute totals in SQL, not from sample rows; check `truncated` in the output. - It opens data read-only by default. Answer from the values it returns, and say which query produced them.
Wenn Ihre Codex-Version Skills unterstützt, können Sie stattdessen dieselben Dateien SKILL.md und references/cli.md in ihr Skill-Verzeichnis kopieren.
Klicken Sie auf Install command und dann auf Copy brief, und speichern Sie die Anleitung als Projektregel, zum Beispiel .cursor/rules/ducklocal.mdc. Der Agent von Cursor kennt den Befehl dann, sobald er in diesem Projekt arbeitet. Sein Terminal-Werkzeug braucht die Erlaubnis, ducklocal auszuführen: Erlauben Sie schema und query, und bestätigen Sie weiterhin alles, was Dateien schreibt.
# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.
Der genaue Text der Anleitung stammt aus Ihrer installierten App und enthält den vollständigen Pfad des Befehls, falls ducklocal noch nicht im PATH liegt. Den Skill installieren und ansehen →
Ein Agent, der Zeilen liest und sie im eigenen Kontext summiert, antwortet aus dem, was man ihm gezeigt hat. Bei einer Datei mit 1,2 Millionen Zeilen und dem Standardlimit von 1.000 Zeilen sieht er weniger als 0,1 % der Daten. Die gemeldete Summe kann plausibel aussehen und trotzdem um Größenordnungen danebenliegen.
DuckLocal macht diese Lücke sichtbar, statt sie zu verschweigen. Eine Vorschau meldet "truncated": true, und total_rows zeigt, wie viele Zeilen das Ergebnis wirklich hatte. Hört das Zählen früh auf, ist total_rows_exact false und die Summe nur eine Untergrenze. Der Skill sagt dem Agenten, das als Stichprobe zu behandeln und die Rechnung an DuckDB zurückzugeben, das jede Zeile liest.
$ ducklocal query --sql \ "SELECT * FROM 'events.csv'" {..., "row_count":1000, "truncated":true, "total_rows":101000, "total_rows_exact":false} $ ducklocal query --sql \ "SELECT count(*) AS n, sum(amount) AS total FROM 'events.csv'" {..., "rows":[[1204381,8812094.5]], "truncated":false}
Jeder Aufruf öffnet eine eigene DuckDB-Verbindung, prüft, dass die Eingabe genau eine Anweisung enthält, und schreibt ein maschinenlesbares Ergebnis nach stdout. Fehler erscheinen als JSON auf stderr, dazu ein Exit-Code ungleich null.
$ ducklocal query --sql \ "SELECT channel, round(sum(revenue), 2) AS revenue FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC" {"columns":[...], "rows":[["Mobile app",290549.76],...], "row_count":4, "truncated":false, "elapsed_ms":14}
ducklocal schema ./data/Dateien, Tabellen, Views und ihre Spalten auflisten, bevor Sie SQL schreiben.
ducklocal schema sales.csv --statsExakte NULL-Werte, verschiedene Werte, Bereiche, Mediane und die Datumsabdeckung erhalten.
ducklocal query --sql "…"Standardmäßig typisiertes JSON oder mit --format md eine Markdown-Tabelle.
ducklocal open --title "…" --run --sql "…"Öffnen Sie eine Abfrage in der Desktop-App, wenn das Ergebnis geprüft oder weiter erkundet werden soll.
Das Standard-Limit liegt bei 1.000 Zeilen, zusätzlich gilt ein Budget von 2.000.000 Zellen. DuckLocal liest eine Zeile mehr, um festzustellen, ob die Antwort abgeschnitten wurde, und gibt das als truncated aus.
Abfragen mit GROUP BY, ORDER BY und Aggregationen rechnen weiterhin über die vollständige Eingabe, bevor sie ihr begrenztes Ergebnis zurückgeben.
row_count, truncated und elapsed_msDer Open-Source-Skill von DuckLocal bringt einem Agenten bei, das Schema zu prüfen, eine begrenzte Stichprobe anzusehen, in SQL zu aggregieren, die Kürzung zu verifizieren und aus den zurückgegebenen Werten zu antworten. Installieren Sie ihn in der App für Claude Code, oder kopieren Sie dieselbe Anleitung in einen anderen Coding-Agenten.
Den Skill installieren und ansehen
Lesen: Was mir Claude Dashboards über DuckLocal beigebracht hat →
DuckLocal lädt lokale Dateien nicht in einen DuckLocal-Dienst hoch, tut aber auch nicht so, als wäre beliebiges SQL harmlos. Der schreibgeschützte Datenbankmodus ist keine Dateisystem- oder Netzwerk-Sandbox: SQL wie COPY, die Installation von Erweiterungen oder ausdrücklicher externer Zugriff können Nebenwirkungen haben.
--read-write nur für eine bewusste Datenbankänderung verwendenducklocal --help prüfen, bevor Sie sich auf einen Befehl verlassenLieber den visuellen Workflow? Lokale Datenanalyse in der Desktop-App ansehen →
ducklocal schema aus, um Relationen und Spalten zu ermitteln, und dann ducklocal query mit einer SQL-Anweisung. Der Befehl gibt standardmäßig strukturiertes JSON zurück, ohne das Desktop-Fenster zu öffnen oder einen Server zu starten.ducklocal query akzeptiert genau eine SQL-Anweisung. Skripte mit mehreren Anweisungen werden abgelehnt statt teilweise ausgeführt, was jeden Tool-Aufruf leichter prüfbar macht.AGENTS.md oder eine Projektregel.Verwandt: DuckDB GUI · Parquet-Viewer · CSV mit SQL abfragen · SQL-Dashboards · DuckLocal vs DBeaver
Installieren Sie DuckLocal, legen Sie den Befehl in den PATH und fragen Sie zuerst, was wirklich in den Daten steckt.