---
title: SQL für KI-Agenten auf lokalen Daten | DuckLocal CLI
description: Lassen Sie KI-Agenten Schemas prüfen und lokale Dateien mit DuckDB-SQL in einer Anweisung abfragen – begrenzte JSON-Ausgabe.
image: https://ducklocal.app/og-image.jpg?v=2
language: de
---

# Lassen Sie KI-Agenten lokale Daten mit SQL abfragen

**Erst das Schema. Eine Anweisung. Strukturierte Ausgabe.**

DuckLocal gibt Claude Code, Codex, Cursor und anderen Coding-Agenten einen headless DuckDB-Workflow für CSV-, Parquet-, JSON- und DuckDB-Daten. GUI-Automatisierung, Datenbankserver oder eigene API sind nicht nötig.

## Erst entdecken, dann abfragen

1. **Das Schema erfassen.** `ducklocal schema ./data/` liefert Relationen, direkt abfragbare `FROM`-Ausdrücke, Spalten und Typen. Große Kataloge liefern eine Zusammenfassung mit Hinweisen zum Tiefergehen.
2. **Innerhalb der Grenzen prüfen.** Führen Sie eine SQL-Anweisung mit kleinem Limit aus. Prüfen Sie den Exit-Status und das JSON-Feld `truncated`.
3. **In SQL rechnen.** Führen Sie Filter, Joins und Aggregationen in DuckDB aus, statt eine Teilvorschau im Kontext des Agenten zu summieren.

```bash
ducklocal schema ./data/
ducklocal schema sales.csv --stats
ducklocal query --sql "SELECT channel, sum(revenue) FROM 'sales.csv' GROUP BY channel"
```

Jeder `query`-Aufruf öffnet eine eigene Verbindung, prüft, dass genau eine SQL-Anweisung vorliegt, und schreibt ein maschinenlesbares Ergebnis nach stdout. Fehler erscheinen als JSON auf stderr, mit einem Exit-Code ungleich null.

## 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.

```text

# 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`](https://github.com/JetSquirrel/DuckLocal/tree/main/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:

```text
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.

```text

# 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 →](https://ducklocal.app/docs/de/cli#install-the-official-skill)

## 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](https://ducklocal.app/docs/de/cli#query-options)

```bash
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}
```

## Begrenzte, explizite Ausgabe

Das Standard-Limit liegt bei 1.000 Zeilen, dazu ein Budget von 2.000.000 Zellen. DuckLocal liest eine zusätzliche Zeile, um festzustellen, ob das Ergebnis abgeschnitten wurde.

Die JSON-Hülle enthält:

- typisierte Spalten und Zeilen
- `row_count`
- `truncated`
- `elapsed_ms`

Exit-Code 2 bedeutet ungültige Argumente, Exit-Code 1 eine fehlgeschlagene Ausführung. `--format md` stellt dasselbe Ergebnis als Markdown-Tabelle für Menschen dar.

## Offizieller Agent-Skill

Der Open-Source-Skill 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. Er lässt sich in der App für Claude Code installieren oder als Anleitung für einen anderen Agenten verwenden.

Ein Agent kann Arbeit mit `ducklocal open` an die laufende Desktop-App übergeben und dann mit `ducklocal open --state` die sichtbaren Tabs und Ergebnisvorschauen lesen.

## Sicherheitsgrenze

DuckLocal lädt lokale Dateien nicht in einen DuckLocal-Dienst hoch, ist aber keine Sicherheits-Sandbox. Der schreibgeschützte Datenbankmodus verhindert nicht, dass SQL andere Dateien schreibt oder auf das Netzwerk zugreift.

Geben Sie Ausgabepfade, Überschreiben, Datenbankänderungen, die Installation von Erweiterungen und externen Zugriff vor der Ausführung frei.

## Links

- [DuckLocal herunterladen](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Vollständige CLI-Referenz](https://ducklocal.app/docs/de/cli)
- [Offiziellen Skill installieren](https://ducklocal.app/docs/de/cli#install-the-official-skill)
- [Lokale Datenanalyse](https://ducklocal.app/de/use-cases/local-data-analysis/)
- [Was mir Claude Dashboards über DuckLocal beigebracht hat](https://ducklocal.app/de/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/de/use-cases/duckdb-gui/)
- [Parquet-Viewer](https://ducklocal.app/de/use-cases/parquet-viewer/)
- [CSV mit SQL abfragen](https://ducklocal.app/de/use-cases/query-csv-with-sql/)
- [SQL-Dashboards](https://ducklocal.app/de/use-cases/sql-dashboards/)
- [DuckLocal vs DBeaver](https://ducklocal.app/de/compare/ducklocal-vs-dbeaver/)

Source: https://ducklocal.app/de/use-cases/ai-agent-sql/
