AI エージェントにローカルデータを SQL でクエリさせる

Claude Code、Codex、Cursor などのコーディングエージェントに、CSV、Parquet、JSON、DuckDB データを扱うヘッドレスな DuckDB ワークフローを。GUI の自動操作も、データベースサーバーも、独自 API も要りません。

CLI は既定で JSON を出力し、引数、SQL、I/O の失敗には明確な終了コードを使います。

まず把握し、それからクエリ

公式のワークフローは、エージェントが列名を推測したり、部分的なプレビューをデータセット全体と取り違えたりするのを防ぎます。

  1. スキーマを把握する

    ducklocal schema ./data/ を実行すると、リレーション、そのままクエリに使える FROM 式、列、型が得られます。カタログが大きい場合は、掘り下げるためのヒント付きの要約が返ります。

  2. 範囲内でプレビューする

    1 つの SQL ステートメントと小さめの --limit で、代表的な行を確認します。コマンドの終了ステータスと、JSON の truncated フィールドを確認してください。

  3. SQL で答えを計算する

    切り捨てられたプレビューをエージェントのコンテキストで合計するのではなく、フィルター、結合、集計を DuckDB で実行します。答えに必要な根拠だけを返します。

Claude Code、Codex、Cursor での設定

どのエージェントにも必要なのは 2 つ、PATH 上の ducklocal コマンドと、その使い方の説明です。どちらもアプリの Command line & AI…(タイトルバーのロボットボタン、または DuckLocal メニュー)から用意できます。

Claude Code:スキルをインストール

Install command、続いて Add to Claude Code をクリックします。スキルは ~/.claude/skills/ducklocal に書き込まれ、Claude Code はどのプロジェクトでもそれを見つけます。依頼がスキルに合えば Claude Code がスキルを読み込み、言われなくてもスキーマから確認するワークフローに従います。

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

1 つのプロジェクトだけでスキルを使うなら、skills/ducklocal をそのプロジェクトの .claude/skills/ にコピーしてください。

Codex:説明を AGENTS.md に貼り付け

Install command、続いて Copy brief をクリックし、説明をプロジェクトのルートにある AGENTS.md に貼り付けます。Codex はセッションの開始時にこのファイルを読みます。説明の抜粋:

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.

お使いの Codex がスキルに対応していれば、同じ SKILL.md と references/cli.md をそのスキルディレクトリにコピーする方法もあります。

Cursor:説明をプロジェクトルールとして保存

Install command、続いて Copy brief をクリックし、説明をプロジェクトルール(たとえば .cursor/rules/ducklocal.mdc)として保存します。以後 Cursor のエージェントは、そのプロジェクトで作業するときにこのコマンドを知っています。ターミナルツールには ducklocal を実行する許可が必要です。schema と query は許可し、ファイルに書き込む操作は引き続き都度承認してください。

# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.

エージェントにプレビューを合計させてはいけない理由

行を読んで自分のコンテキストで合計するエージェントは、見せられた分だけで答えます。120 万行のファイルと既定の 1,000 行の上限では、見えるのはデータの 0.1% 未満です。報告される合計はもっともらしく見えても、桁違いに間違っていることがあります。

DuckLocal はその欠落を黙って隠さず、見えるようにします。プレビューは "truncated": true を返し、total_rows で結果が本当は何行あったかがわかります。数え上げが途中で止まった場合、total_rows_exact は false で、その合計は下限にすぎません。スキルはエージェントに、それをサンプルとして扱い、すべての行を読む DuckDB に計算を任せるよう教えます。

上限、予算、出力の形式

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}

1 つのコマンド、1 つの SQL ステートメント

呼び出しごとに専用の DuckDB 接続を作成し、入力にステートメントが正確に 1 つだけ含まれていることを検証して、機械可読な結果を stdout に書き出します。エラーは JSON として stderr に出て、非ゼロの終了コードが返ります。

クエリの契約を読む

ターミナル
$ 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/

リレーションを見つける

SQL を書く前に、ファイル、テーブル、ビューとその列を一覧できます。

ducklocal schema sales.csv --stats

1 つのリレーションをプロファイルする

null の正確な数、異なる値の数、範囲、中央値、日付の網羅範囲が得られます。

ducklocal query --sql "…"

ステートメントを 1 つ実行する

既定では型付きの JSON を、--format md を付けると Markdown の表を受け取ります。

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

作業を人に渡す

結果のレビューや追加の探索が必要なときは、デスクトップアプリでクエリを開きます。

結果が不完全であることをエージェントに伝える出力

既定の返却上限は 1,000 行で、さらに 2,000,000 セルの予算が適用されます。DuckLocal は 1 行余分に読み取ることで、レスポンスが途中で切れたかどうかを判定し、それを truncated として公開します。

GROUP BY、ORDER BY、集計などのクエリは、上限付きの結果を返す前に、入力全体に対して計算されます。

  • 安定した JSON エンベロープに型付きの列と行
  • 明示的な row_count、truncated、elapsed_ms
  • 引数が不正なら終了コード 2、実行失敗なら 1
  • エラーは JSON で stderr に、stdout は空のまま
  • 人向けのレポートには Markdown 出力

コマンドだけでなく、ワークフローを教える

オープンソースの DuckLocal スキルは、スキーマを調べ、上限付きのサンプルをプレビューし、SQL で集計し、切り捨てを確認し、返された値から答えることをエージェントに教えます。アプリから Claude Code 用にインストールするか、同じ説明を別のコーディングエージェントにコピーしてください。

スキルをインストールして中身を見る

読む: Claude Dashboards が DuckLocal について教えてくれたこと →

ローカルの CLI であって、隠れたクラウドサービスでもサンドボックスでもありません

DuckLocal はローカルファイルを DuckLocal のサービスにアップロードしませんが、任意の SQL が無害であるふりもしません。読み取り専用のデータベースモードは、ファイルシステムやネットワークのサンドボックスではありません。COPY などの SQL、拡張機能のインストール、明示的な外部アクセスには副作用が伴う可能性があります。

  • 出力パス、上書き、データベースの変更を承認する
  • 拡張機能のインストールと外部アクセスを承認する
  • 書き込みに失敗したら、再試行の前に出力先を確認する
  • 意図してデータベースを変更するときだけ --read-write を使う
  • コマンドに頼る前に ducklocal --help を確認する

AI エージェントと SQL に関する質問

AI エージェントは DuckLocal でローカルデータをどうクエリしますか?
エージェントは ducklocal schema を実行してリレーションと列を把握し、次に ducklocal query で 1 つの SQL ステートメントを実行します。このコマンドはデスクトップウィンドウを開かず、サーバーも起動せずに、既定で構造化 JSON を返します。
CLI は既定で完全なデータを返しますか?
いいえ。クエリの出力は意図的に上限を設けています。既定の行数上限は 1,000 行で、さらに 2,000,000 セルの予算も適用されます。JSON レスポンスは切り捨てが起きたかどうかを報告します。完全な集計は SQL の中で計算してください。
DuckLocal はエージェントのために SQL スクリプトを実行できますか?
ducklocal query の呼び出しは、それぞれ正確に 1 つの SQL ステートメントを受け付けます。複数ステートメントのスクリプトは一部だけ実行されることなく拒否されるため、各ツール呼び出しを検査しやすくなります。
DuckLocal は Codex や Cursor でも使えますか?Claude Code 専用ですか?
ターミナルコマンドを実行できるエージェントなら、どれでも使えます。Claude Code はアプリから公式スキルをワンクリックで入れられます。Codex、Cursor などのエージェントには、アプリの Copy brief ボタンで作った説明を AGENTS.md やプロジェクトルールに貼り付けます。
DuckLocal は MCP サーバーやセキュリティサンドボックスですか?
いいえ。DuckLocal が提供するのはコマンドラインインターフェースと任意のエージェントスキルであり、MCP サーバーでもセキュリティサンドボックスでもありません。書き込みの可能性、拡張機能のインストール、外部アクセスには、これまでどおり通常の承認が必要です。

エージェントにスキーマファーストの SQL ワークフローを

DuckLocal をインストールし、コマンドを PATH に通して、データに実際に何が入っているかを尋ねるところから始めてください。