Lassen Sie KI-Agenten lokale Daten mit SQL abfragen

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.

Erst entdecken, dann abfragen

Der offizielle Workflow hindert einen Agenten daran, Spaltennamen zu raten oder eine Teilvorschau für den ganzen Datensatz zu halten.

  1. Das Schema erfassen

    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.

  2. Innerhalb der Grenzen prüfen

    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.

  3. Die Antwort in SQL berechnen

    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.

Einrichtung in Claude Code, Codex oder Cursor

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ü).

Claude Code: den Skill installieren

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.

Codex: die Anleitung in AGENTS.md einfügen

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.

Cursor: die Anleitung als Projektregel speichern

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.

Warum der Agent die Vorschau nicht aufsummieren sollte

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.

Limits, Budgets und das Ausgabeformat

Terminal
$ 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}

Ein Befehl, eine SQL-Anweisung

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.

Den Abfrage-Vertrag lesen

Terminal
$ 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}

Eine kleine Oberfläche mit klaren Verträgen

ducklocal schema ./data/

Relationen entdecken

Dateien, Tabellen, Views und ihre Spalten auflisten, bevor Sie SQL schreiben.

ducklocal schema sales.csv --stats

Eine Relation profilieren

Exakte NULL-Werte, verschiedene Werte, Bereiche, Mediane und die Datumsabdeckung erhalten.

ducklocal query --sql "…"

Eine Anweisung ausführen

Standardmäßig typisiertes JSON oder mit --format md eine Markdown-Tabelle.

ducklocal open --title "…" --run --sql "…"

Arbeit an einen Menschen übergeben

Öffnen Sie eine Abfrage in der Desktop-App, wenn das Ergebnis geprüft oder weiter erkundet werden soll.

Eine Ausgabe, die dem Agenten sagt, wann sie unvollständig ist

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.

  • Typisierte Spalten und Zeilen in einer stabilen JSON-Hülle
  • Explizite Angaben zu row_count, truncated und elapsed_ms
  • Exit 2 bei ungültigen Argumenten, Exit 1 bei Ausführungsfehlern
  • JSON-Fehler auf stderr, stdout bleibt leer
  • Markdown-Ausgabe für gut lesbare Berichte

Den Workflow lehren, nicht nur den Befehl

Der 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 →

Eine lokale CLI – kein versteckter Cloud-Dienst und keine Sandbox

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.

  • Ausgabepfade, Überschreiben und Datenbankänderungen freigeben
  • Installation von Erweiterungen und externen Zugriff freigeben
  • Ein Ziel prüfen, bevor ein fehlgeschlagenes Schreiben wiederholt wird
  • --read-write nur für eine bewusste Datenbankänderung verwenden
  • ducklocal --help prüfen, bevor Sie sich auf einen Befehl verlassen

Fragen zu SQL für KI-Agenten

Wie fragt ein KI-Agent lokale Daten mit DuckLocal ab?
Der Agent führt 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.
Gibt die CLI standardmäßig vollständige Daten zurück?
Nein. Die Abfrageausgabe ist bewusst begrenzt: Das Standard-Limit liegt bei 1.000 Zeilen, zusätzlich gilt ein Budget von 2.000.000 Zellen. Die JSON-Antwort meldet, ob sie gekürzt wurde. Vollständige Aggregate sollten in SQL berechnet werden.
Kann DuckLocal SQL-Skripte für einen Agenten ausführen?
Jeder Aufruf von 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.
Funktioniert DuckLocal mit Codex und Cursor oder nur mit Claude Code?
Jeder Agent, der einen Terminalbefehl ausführen kann, kann es nutzen. Claude Code bekommt den offiziellen Skill mit einem Klick in der App. Für Codex, Cursor und andere Agenten erzeugt der Knopf Copy brief in der App eine Anleitung zum Einfügen in AGENTS.md oder eine Projektregel.
Ist DuckLocal ein MCP-Server oder eine Sicherheits-Sandbox?
Nein. DuckLocal bietet eine Befehlszeilenschnittstelle und einen optionalen Agent-Skill, keinen MCP-Server und keine Sicherheits-Sandbox. Mögliche Schreibvorgänge, die Installation von Erweiterungen und externer Zugriff erfordern weiterhin die übliche Freigabe.

Geben Sie Ihrem Agenten einen SQL-Workflow, der beim Schema beginnt

Installieren Sie DuckLocal, legen Sie den Befehl in den PATH und fragen Sie zuerst, was wirklich in den Daten steckt.