csvql

AI エージェント向けの、CSV ファイル上で直接実行できる読み取り専用 SQL です。

データベースは、データを 取り込む ためのものです。csvql は、データがすでにある場所で実行するクエリです。

csvql は CSV ファイル上でそのまま SELECT を実行します。インポート、取り込み、サーバーは不要です。生の CSV に対する速度は DuckDB や polars とほぼ同等で、メモリ使用量は 3～11 倍少なくなります。MCP サーバーとして提供されるため、エージェントはギガバイト級のファイルについて質問し、ファイル全体ではなく数行だけを取得できます。静的な Zig バイナリ 1 つで動作し、ネットワーク呼び出しはなく、データを書き換える手段もありません。

$ csvql "SELECT cab_type, COUNT(*) FROM 'trips.csv' GROUP BY cab_type"
cab_type,COUNT(*)
green,32447
yellow,967553

ウェブサイト · クイックスタート · エージェント向け · インストール · パフォーマンス · SQL · ドキュメント

---

これが必要な理由

エージェントが企業データにアクセスするようになっています。一般的な方法は、データベースに接続するか、ファイルをモデルにアップロードすることです。どちらもデータを移動させます。csvql は第 3 の選択肢です。データのそばにある自分のマシンで実行し、エージェントがその場でデータをクエリできるようにします。以下の内容はすべて、ソースコードで確認できます。

• 設計上、読み取り専用です。 パーサーに INSERT、UPDATE、DELETE、DROP はありません。入力ファイルに書き込むことはありません。
• ネットワークを使用しません。 コードベースに std.net、std.http、ソケット呼び出しはありません。テレメトリーも更新チェックもありません。strace -f -e trace=network で空のトレースが確認できます。
• フラグでサンドボックス化できます。 --root /data を指定すると、プロセスが開けるすべてのファイルをその範囲内に制限します。/etc/passwd や ../ によるパス遡りは PathOutsideAllowedRoot エラーになります。
• 出力に上限があります。 MCP の結果は、1 回の呼び出しにつき約 100 行／12 KB に制限されています。不用意な SELECT * でコンテキストを埋め尽くしたり、1 回ずつテーブル全体を取得したりすることはできません。
• メモリ使用量は一定です。 集計ではデータセット全体ではなく、実行中のアキュムレーターを保持します。0.7 GB のファイルでも 8 GB のファイルでも 74 MB です。データのそばにある小規模な VM で動作します。
• 監査できます。 --audit <file> を指定すると、クエリごとに JSONL レコードを 1 件追記します。SSH 経由では、既存の鍵、踏み台サーバー、ログをそのまま利用できます。

macOS と Windows に関する既知の制約 2 件を含む、セキュリティ対策の全容はこちらです：SECURITY.md。

対応していないこと

• データベースではありません。 UNION、ウィンドウ関数、LEFT／RIGHT／FULL／CROSS JOIN（対応するのは内部ハッシュ結合のみ）はありません。サブクエリで利用できる形式は col IN (SELECT ...) のみです。これらは誤ったデータを返すのではなく、エラーになります。完全な SQL が必要な場合は DuckDB を使用してください。
• WHERE で使えるスカラー関数は DATEDIFF、DATEADD、EXTRACT に限られます。その他（UPPER、ROUND など）は SELECT でのみ使用でき、現在は WHERE で使うと誤解を招く ColumnNotFound エラーになります。
• 引用符付き CSV は約 3 倍遅くなります。 引用符があると、スキャナーが利用する 16 バイトのスキップ処理が無効になります。
• MEDIAN はグループ内のすべての値をバッファーします。 そのため、2,000 万行では DuckDB より 5 倍遅くなります（#205）。カーディナリティの高い GROUP BY（数百万グループ）も遅くなります。
• 入力形式は CSV のみです。 JSON と JSONL は出力形式であり、入力形式ではありません。

追跡中の課題を含む一覧はこちらです：SQL_REFERENCE.md#known-limitations。

クイックスタート

# SQL mode
csvql "SELECT name, salary FROM 'data.csv' WHERE age > 30 ORDER BY salary DESC LIMIT 10"

# Simple mode: same query, positional
csvql data.csv "name,salary" "age>30" 10 "salary:desc"

# Pipes
cat data.csv | csvql "SELECT name, age FROM '-' WHERE age > 25"
csvql "SELECT * FROM 'data.csv' WHERE status = 'active'" > output.csv

# Other formats
csvql "SELECT name, age FROM 'data.tsv'" -d $'\t'
csvql "SELECT name, age FROM 'data.csv' LIMIT 3" --json      # or --jsonl, --markdown

# What is in this file?
csvql --schema data.csv

フラグ：-d/--delimiter、--json、--jsonl、--markdown、--no-header、--no-input-header（ヘッダーのないファイルでは c1..cN を使用）、-o/--output、--threads、--strict、--schema、--root、--audit、--mcp。詳しくは csvql --help を参照してください。シンプルモードについては SIMPLE_QUERY_LANGUAGE.md を参照してください。

エージェント向け（MCP）

セットアップ

csvql install          # registers csvql in Claude Code and Claude Desktop; --print to dry-run

Claude Code CLI が存在する場合は claude mcp add を実行し、Claude Desktop の設定に mcpServers.csvql のエントリを追加します。他のサーバー設定は保持されます。その後、Claude を再起動してください。

別の方法として、Releases ページから Claude Desktop 用のワンクリック csvql-<platform>.mcpb バンドルを取得して（設定 → 拡張機能）、または手動で次のエントリを追加できます。

{ "mcpServers": { "csvql": { "command": "/usr/local/bin/csvql", "args": ["--mcp", "--root", "/data"] } } }

VS Code（Copilot）では、.vscode/mcp.json の servers に、同じ command／args を "type": "stdio" とともに設定します。

ツール

ツール	戻り値
csv_query(sql)	JSON 形式の結果。上限は約 100 行／12 KB です
csv_schema(file)	列名とサンプル行を数行返します
csv_list(directory?)	ディレクトリ内の CSV ファイル

エージェントは、シングルクォートで囲んだパスを使って通常の SQL を記述します。

SELECT customer, SUM(revenue) AS total FROM 'sales.csv' GROUP BY customer ORDER BY total DESC LIMIT 10
SELECT STRFTIME('%Y-%m', order_date) AS month, COUNT(*) FROM 'orders.csv' GROUP BY month ORDER BY 1
SELECT o.id, c.name FROM 'orders.csv' o JOIN 'customers.csv' c ON o.customer_id = c.id WHERE c.region = 'West'

リモートおよびオンプレミス

データのそばにあるサーバー上で csvql を実行し、SSH 経由で接続します。ネットワークを介して送信されるのは SQL と小さな結果だけです。ポートの開放、リバースプロキシ、新しい認証情報は不要です。

// client MCP config; csvql runs on the remote server
{ "command": "ssh", "args": ["analyst@dataserver", "csvql", "--mcp", "--root", "/data"] }

エージェントや他のユーザーが csvql にアクセスできる場合は、必ず --root を設定してください。権限のない OS ユーザーと読み取り専用マウントを組み合わせてください。チェックリスト：SECURITY.md#hardening-for-on-prem-and-remote-access。

トークンコスト

タクシーのデータセットについて 5 つの質問をした場合、ツールスキーマ込みで MCP 経由のコストは約 640 トークンで、ファイルサイズによって変わりません。417 MB のファイルを貼り付けると約 2 億 3,000 万トークンになります。これは実現可能性を示すものであり、節約量ではありません。すでにシェルを使えて duckdb -csv を実行するエージェントなら、MCP が JSON を返すため、csvql を MCP 経由で使う場合よりわずかに少ないトークンで済みます。エージェントで csvql を使う利点はトークン数ではなく、--root、読み取り専用の実行、出力上限、メモリです。実測してください：bench/bench_tokens.py。

インストール

Homebrew（macOS／Linux）：

brew install melihbirim/csvql/csvql

GitHub Releases のビルド済みバイナリ：

# macOS (Apple Silicon)
curl -L https://github.com/melihbirim/csvql/releases/latest/download/csvql-macos-aarch64.tar.gz | tar xz
sudo mv csvql-macos-aarch64 /usr/local/bin/csvql

# macOS (Intel)
curl -L https://github.com/melihbirim/csvql/releases/latest/download/csvql-macos-x86_64.tar.gz | tar xz
sudo mv csvql-macos-x86_64 /usr/local/bin/csvql

# Linux (x86_64)
curl -L https://github.com/melihbirim/csvql/releases/latest/download/csvql-linux-x86_64.tar.gz | tar xz
sudo mv csvql-linux-x86_64 /usr/local/bin/csvql

Windows（x86_64）：同じページから csvql-windows-x86_64.zip をダウンロードし、csvql-windows-x86_64.exe を PATH に追加してください。

ライブラリ：同じエンジンを使用し、サブプロセスは不要です。

pip install csvql-query      # Python: csvql.query(), .query_df(), .query_csv()   → docs/PYTHON.md
npm install csvql-query      # Node.js: require('csvql-query'), plus a `csvql-query` CLI → docs/NODE.md

ソースからビルドする場合は、Zig 0.15.2 を使用します。

git clone https://github.com/melihbirim/csvql.git && cd csvql
zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/csvql /usr/local/bin/

bash と zsh 用のシェル補完は completions/ にあります。csvql --help のフラグ、install サブコマンド、ファイルパスを補完します。

# bash: add to ~/.bashrc (on macOS, Terminal opens login shells, so use ~/.bash_profile)
source /path/to/csvql/completions/csvql.bash

# zsh: put _csvql in a directory on your fpath
mkdir -p ~/.zsh/completions
cp completions/_csvql ~/.zsh/completions/_csvql
# then in ~/.zshrc, before compinit runs:
#   fpath=(~/.zsh/completions $fpath)
#   autoload -Uz compinit && compinit

パフォーマンス

生の CSV に対して同じ GROUP BY department を実行しました。エンジンごとに 1 プロセスを使い、Apple M2 Pro（メモリ 16 GB）で測定しています。ピークメモリと実行時間：

ファイル	csvql	DuckDB	polars 2.0
0.69 GB	74 MB / 0.2s	254 MB / 0.8s	1151 MB / 0.6s
1.89 GB	74 MB / 0.4s	253 MB / 1.2s	2107 MB / 1.1s
3.80 GB	75 MB / 0.7s	275 MB / 2.1s	2666 MB / 9.8s
8.14 GB	74 MB / 2.4s	367 MB / 5.5s	1754 MB / 26.7s

集計ではデータセットではなくアキュムレーターを保持するため、メモリ使用量は一定です。ただし、これは集計処理に当てはまるもので、行を保持する必要がある ORDER BY には当てはまりません。速度は他の 2 つと同程度です。スキャン、フィルター、小さなファイルでは csvql が 2〜5 倍速く、生の CSV に対する結合では大きく上回ります。COUNT(*) と top-N では polars と同等ですが、MEDIAN と数百万のグループを使う GROUP BY では DuckDB に劣ります。エージェントの処理時間で考えれば、いずれも問題にはなりません。重要なのはメモリ使用量です。csvql をどのマシンで実行できるかを左右するためです。

すべての数値には再現用スクリプトがあります。引用符付き CSV、幅の広いファイル、結合、サブクエリ、性能で劣るケースを含む完全な表は、BENCHMARKS.md を参照してください。

SQL

SELECT / FROM / WHERE / GROUP BY / HAVING / ORDER BY / LIMIT / OFFSET、内部 JOIN（連結）、col IN (SELECT ...)、LIKE / ILIKE / BETWEEN / IS NULL / AND / OR / NOT、DISTINCT、CASE WHEN。集計関数：COUNT、SUM、AVG、MIN、MAX、VARIANCE、STDDEV、MEDIAN、QUANTILE、MODE、GROUP_CONCAT、COUNT(DISTINCT)。SELECT 内のスカラー関数：文字列（UPPER、LOWER、TRIM、LENGTH、REVERSE、CONCAT、LTRIM、RTRIM、LEFT、RIGHT、REPEAT、POSITION、INSTR、SUBSTR、REPLACE、SPLIT_PART、LPAD、RPAD）、数学（ABS、SIGN、CEIL、FLOOR、MOD、ROUND、TRUNC、SQRT、POWER、LN、LOG、EXP、GREATEST、LEAST）、CAST、COALESCE、NULLIF、IFNULL、日付（STRFTIME、DATE_PART、EXTRACT、DATEDIFF、DATEADD、CURRENT_DATE、NOW()、CURRENT_TIMESTAMP）。

csvql "SELECT department, COUNT(*), AVG(salary) FROM 'data.csv' WHERE salary > 50000 GROUP BY department HAVING COUNT(*) > 10 ORDER BY department"
csvql "SELECT e.name, d.dept_name FROM 'employees.csv' e JOIN 'departments.csv' d ON e.dept_id = d.id WHERE d.dept_name = 'Engineering'"
csvql "SELECT id FROM 'orders.csv' WHERE customer_id IN (SELECT id FROM 'customers.csv' WHERE region = 'EU')"

完全な構文と制限については、SQL_REFERENCE.md をご覧ください。DuckDB と差分テストを行っている内容については、CORRECTNESS.md をご覧ください。

ドキュメント

ドキュメント	説明
SQL_REFERENCE.md	SQL 構文の全容、実行可能な例、DuckDB との違い、制限事項
SECURITY.md	セキュリティ対策、ネットワークとディスク書き込みに関する保証、強化策
CORRECTNESS.md	DuckDB とのテスト内容と方法、既知の不足点、エラーの動作
BENCHMARKS.md	DuckDB、polars、pandas、DataFusion との詳細なパフォーマンス分析
ARCHITECTURE.md	エンジンの設計、最適化手法
SIMPLE_QUERY_LANGUAGE.md	シンプルモードの構文リファレンス
docs/PYTHON.md · docs/NODE.md · docs/LIBRARY.md	Python、Node.js、Zig のライブラリ API
CONTRIBUTING.md	貢献ガイドライン

今後の予定

• HTTP/SSE MCP トランスポートを追加し、1 つの csvql をチームで共有サービスとして利用できるようにします（#60）。
• MEDIAN のメモリ使用量を O(groups) に抑えます（#205）。

リリース済みの機能については、リリースノートをご覧ください。初めての貢献に適した課題には、対象ファイルと完了条件が明記されています。

ライセンス

MIT。詳細は LICENSE.md をご覧ください。