ducklocal schema ./data/リレーションを見つける
SQL を書く前に、ファイル、テーブル、ビューとその列を一覧できます。
Claude Code、Codex、Cursor などのコーディングエージェントに、CSV、Parquet、JSON、DuckDB データを扱うヘッドレスな DuckDB ワークフローを。GUI の自動操作も、データベースサーバーも、独自 API も要りません。
CLI は既定で JSON を出力し、引数、SQL、I/O の失敗には明確な終了コードを使います。
公式のワークフローは、エージェントが列名を推測したり、部分的なプレビューをデータセット全体と取り違えたりするのを防ぎます。
ducklocal schema ./data/ を実行すると、リレーション、そのままクエリに使える FROM 式、列、型が得られます。カタログが大きい場合は、掘り下げるためのヒント付きの要約が返ります。
1 つの SQL ステートメントと小さめの --limit で、代表的な行を確認します。コマンドの終了ステータスと、JSON の truncated フィールドを確認してください。
切り捨てられたプレビューをエージェントのコンテキストで合計するのではなく、フィルター、結合、集計を DuckDB で実行します。答えに必要な根拠だけを返します。
どのエージェントにも必要なのは 2 つ、PATH 上の ducklocal コマンドと、その使い方の説明です。どちらもアプリの Command line & AI…(タイトルバーのロボットボタン、または DuckLocal メニュー)から用意できます。
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/ にコピーしてください。
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 をそのスキルディレクトリにコピーする方法もあります。
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.
説明の正確な文面はインストール済みのアプリから取得され、ducklocal がまだ PATH にない場合はコマンドのフルパスが含まれます。スキルをインストールして中身を確認 →
行を読んで自分のコンテキストで合計するエージェントは、見せられた分だけで答えます。120 万行のファイルと既定の 1,000 行の上限では、見えるのはデータの 0.1% 未満です。報告される合計はもっともらしく見えても、桁違いに間違っていることがあります。
DuckLocal はその欠落を黙って隠さず、見えるようにします。プレビューは "truncated": true を返し、total_rows で結果が本当は何行あったかがわかります。数え上げが途中で止まった場合、total_rows_exact は false で、その合計は下限にすぎません。スキルはエージェントに、それをサンプルとして扱い、すべての行を読む DuckDB に計算を任せるよう教えます。
$ 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}
呼び出しごとに専用の 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 --statsnull の正確な数、異なる値の数、範囲、中央値、日付の網羅範囲が得られます。
ducklocal query --sql "…"既定では型付きの JSON を、--format md を付けると Markdown の表を受け取ります。
ducklocal open --title "…" --run --sql "…"結果のレビューや追加の探索が必要なときは、デスクトップアプリでクエリを開きます。
既定の返却上限は 1,000 行で、さらに 2,000,000 セルの予算が適用されます。DuckLocal は 1 行余分に読み取ることで、レスポンスが途中で切れたかどうかを判定し、それを truncated として公開します。
GROUP BY、ORDER BY、集計などのクエリは、上限付きの結果を返す前に、入力全体に対して計算されます。
row_count、truncated、elapsed_msオープンソースの DuckLocal スキルは、スキーマを調べ、上限付きのサンプルをプレビューし、SQL で集計し、切り捨てを確認し、返された値から答えることをエージェントに教えます。アプリから Claude Code 用にインストールするか、同じ説明を別のコーディングエージェントにコピーしてください。
DuckLocal はローカルファイルを DuckLocal のサービスにアップロードしませんが、任意の SQL が無害であるふりもしません。読み取り専用のデータベースモードは、ファイルシステムやネットワークのサンドボックスではありません。COPY などの SQL、拡張機能のインストール、明示的な外部アクセスには副作用が伴う可能性があります。
--read-write を使うducklocal --help を確認する代わりに視覚的なワークフローが必要ですか? デスクトップアプリでのローカルデータ分析を見る →
ducklocal schema を実行してリレーションと列を把握し、次に ducklocal query で 1 つの SQL ステートメントを実行します。このコマンドはデスクトップウィンドウを開かず、サーバーも起動せずに、既定で構造化 JSON を返します。ducklocal query の呼び出しは、それぞれ正確に 1 つの SQL ステートメントを受け付けます。複数ステートメントのスクリプトは一部だけ実行されることなく拒否されるため、各ツール呼び出しを検査しやすくなります。AGENTS.md やプロジェクトルールに貼り付けます。関連: DuckDB GUI · Parquet ビューア · SQL で CSV をクエリ · SQL ダッシュボード · DuckLocal と DBeaver
DuckLocal をインストールし、コマンドを PATH に通して、データに実際に何が入っているかを尋ねるところから始めてください。