---
title: ローカルデータを扱う AI エージェント向けの SQL | DuckLocal CLI
description: AI エージェントがスキーマを調べ、ローカルのファイルを単一ステートメントの DuckDB SQL でクエリし、上限付きの JSON 出力を得られます。
image: https://ducklocal.app/og-image.jpg?v=2
language: ja
---

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

**まずスキーマ。ステートメントは 1 つ。出力は構造化。**

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

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

1. **スキーマを把握する。** `ducklocal schema ./data/` は、リレーション、そのままクエリに使える `FROM` 式、列、型を返します。カタログが大きい場合は、掘り下げるためのヒント付きの要約が返ります。
2. **範囲内でプレビューする。** 小さめの上限を付けて、SQL ステートメントを 1 つ実行します。終了ステータスと JSON の `truncated` フィールドを確認してください。
3. **SQL で計算する。** 部分的なプレビューをエージェントのコンテキストで合計するのではなく、フィルター、結合、集計を DuckDB で実行します。

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

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

## 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 がスキルを読み込み、言われなくてもスキーマから確認するワークフローに従います。

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

1 つのプロジェクトだけでスキルを使うなら、[`skills/ducklocal`](https://github.com/JetSquirrel/DuckLocal/tree/main/skills/ducklocal) をそのプロジェクトの `.claude/skills/` にコピーしてください。

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

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

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

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

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

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

```text

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

説明の正確な文面はインストール済みのアプリから取得され、`ducklocal` がまだ `PATH` にない場合はコマンドのフルパスが含まれます。[スキルをインストールして中身を確認 →](https://ducklocal.app/docs/ja/cli#install-the-official-skill)

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

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

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

[上限、予算、出力の形式](https://ducklocal.app/docs/ja/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}
```

## 上限付きで明示的な出力

既定の上限は 1,000 行で、さらに 2,000,000 セルの予算が適用されます。DuckLocal は 1 行余分に読み取り、結果が途中で切れたかどうかを判定します。

JSON エンベロープには次のものが含まれます。

- 型付きの列と行
- `row_count`
- `truncated`
- `elapsed_ms`

終了コード 2 は引数が不正、終了コード 1 は実行失敗を意味します。`--format md` を付けると、同じ結果が人に読める Markdown の表として描画されます。

## 公式のエージェントスキル

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

エージェントは `ducklocal open` で作業を実行中のデスクトップアプリに渡し、`ducklocal open --state` で表示中のタブと結果のプレビューを読み取れます。

## セキュリティの境界

DuckLocal はローカルファイルを DuckLocal のサービスにアップロードしませんが、セキュリティサンドボックスではありません。読み取り専用のデータベースモードでも、SQL が他のファイルを書き込んだりネットワークにアクセスしたりすることを防げません。

実行前に、出力パス、上書き、データベースの変更、拡張機能のインストール、外部アクセスを承認してください。

## リンク

- [DuckLocal をダウンロード](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [CLI リファレンス](https://ducklocal.app/docs/ja/cli)
- [公式スキルをインストール](https://ducklocal.app/docs/ja/cli#install-the-official-skill)
- [ローカルデータ分析](https://ducklocal.app/ja/use-cases/local-data-analysis/)
- [Claude Dashboards が DuckLocal について教えてくれたこと](https://ducklocal.app/ja/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/ja/use-cases/duckdb-gui/)
- [Parquet ビューア](https://ducklocal.app/ja/use-cases/parquet-viewer/)
- [SQL で CSV をクエリ](https://ducklocal.app/ja/use-cases/query-csv-with-sql/)
- [SQL ダッシュボード](https://ducklocal.app/ja/use-cases/sql-dashboards/)
- [DuckLocal と DBeaver](https://ducklocal.app/ja/compare/ducklocal-vs-dbeaver/)

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