今年、すべてのBIベンダーがNL-to-SQLを出荷しました。数週間ごとに新しい本番ガイドが公開されています。自前で構築するための猶予期間は縮まりつつあります——そして、デモと本番デプロイの差を測ることがこれまで以上に簡単になっており、本ガイドはまさにそれを扱います。
本ガイドはデモと本番デプロイを分ける4つのこと——これらのエージェントが実際にできること、あなたのスキーマでの精度の測り方、クエリを生成して検証するアーキテクチャ、そして「安全」を期待ではなくデフォルトにするガードレール——を扱います。
Text-to-SQLエージェントが現在できること
要点：現代のtext-to-SQLは実行ベースで採点され、スキーマを認識し、ますますエージェント化しています——そして、シングルショットとエージェント型の間のギャップこそ、ほとんどのチームがつまずく場所です。
2026年には2つの形態が存在します：
- シングルショット生成——モデルはスキーマと質問を見て、1つのSQLステートメントを出力します。単純な質問に対して高速で安価、そして正確です。
- エージェント型パイプライン——モデルは計画し、生成し、実行し、結果を検査してリトライします：多段階の分析、確認質問、フォローアップクエリです。低速で高価ですが、曖昧な質問や複数テーブルのJOINに耐えられる唯一の形態です。
実用的な使い分け：ダッシュボードとレポートにはシングルショット、ユーザーが反復する分析セッションにはエージェント型です。すべてを1つの形態に押し込むチームは、間違った方のコストを支払うことになります。
ベンチマークの現実を正直に述べると：標準的なSpiderベンチマークでは、現在のシステムは曖昧性のないサブセットで実行精度が80%台後半から90%台前半に達します——2026年のシステムに関するIEEEの研究はその範囲をおよそ87〜91%としています。そして、数字と同じくらい重要な注意点があります：2026年の分析は、公開ベンチマーク自体に広範なアノテーションエラーがあることを発見しました。だからこそ「SpiderがXと言っている」は、あなたのデータベースについての結論ではなく、自前の評価の出発点なのです。
SQLエージェントが失敗する理由——そして猶予期間は縮まっている
要点：本番の成否を分ける3つの失敗クラス——スキーマ理解、幻覚のカラム、ダイアレクトのズレ——があり、市場は今まさに解決策に収束しつつあります。
- スキーマ理解。 モデルはあなたのチームと同じようにはスキーマを理解しません：カラム名は難解で、リレーションは暗黙的で、カタログはコンテキストウィンドウより大きいのです。スキーマリンキング——正しいテーブルとリレーションを注入すること——は最大の精度レバーでありながら、最もスキップされています。
- 幻覚のカラム。 モデルが存在しないカラムを出力したり、関係のないテーブル同士をJOINしたりします。生成時のバリデーションがなければ、クエリは明示的に失敗する（unknown column）か——さらに悪いことに——微妙に間違ったJOINで成功します。
- ダイアレクトのズレ。 Postgres、Snowflake、BigQueryは現実に異なります：クォーティング、関数、LIMITのセマンティクス、日付処理などです。開発用Postgresでは完璧に動くクエリが、顧客のウェアハウスでは壊れる——あるいはさらに悪いことに、意味が静かに変わってしまう——ことがあります。
緊急性は本物です：2026年には本番向けtext-to-SQLツールが爆発的に増えました——データベースネイティブのエージェント、ガードレールフレームワーク、プラットフォーム統合が毎月リリースされています。本ガイドが説明するパターンが当たり前（table stakes）になりつつあるため、猶予期間は毎月狭まっています。
測定された精度：同じスキーマ、同じ質問、5つのモデル
要点：自分のスキーマで、実行ベースの採点でベンチマークしましょう——テキストマッチングは決して使わず、他人のスキーマも決して使わないことです。
あなたの問いに答えるテストは半日で完了します：
- 100問のセットを構築します。実際のユーザーリクエストから、単純なルックアップ、複数テーブルのJOIN、曖昧な言い回しをカバーします。
- 同じセットを候補モデルに通します——GPT、Claude、Gemini、DeepSeek、そしてSQL特化のオープンモデル——同一のスキーマ注入で。
- 実行で採点します：クエリは実行され、期待した結果を返すでしょうか？テキストマッチによる採点は「似たSQL」を評価し、「正しいが異なるSQL」を罰します——あなたが望むものの正反対です。
- 精度と並行してクエリあたりのコストを記録します。コスト10倍で精度が3ポイント高いモデルは、勝者ではなくルーティング判断の対象です。
目指す結果テーブル：あなたのスキーマ、あなたのダイアレクトでの、モデルごとの精度とクエリあたりコストです。それがルーティングレイヤーが消費するデータセットです——本シリーズがすべてのLLM出力に適用している実行ベースの方法論を、SQLに特化して適用したものです。
エージェントのアーキテクチャ：Schema → Generate → Validate → Execute
要点：4つのステージ——本番とデモを分けるのはバリデーションです。
統合チャットエンドポイント上のコアループ：
import sqlite3
from openai import OpenAI
client = OpenAI() # unified endpoint
def build_prompt(schema_snippet: str, question: str) -> list[dict]:
return [
{"role": "system", "content":
"You write SQL for this schema. Use ONLY tables and columns shown. "
"Never invent columns. Dialect: PostgreSQL.\n\n" + schema_snippet},
{"role": "user", "content": question},
]
def validate_sql(sql: str, valid_columns: set[str]) -> str | None:
# Static validation: reject unknown columns and non-SELECT statements
if not sql.strip().upper().startswith("SELECT"):
return None
# Column whitelist check (simplified — production uses a real parser)
return sql if any(c in sql for c in valid_columns) else None
def run(question: str, schema_snippet: str, valid_columns: set[str], conn: sqlite3.Connection):
sql = client.chat.completions.create(
model="gpt-4o-mini",
messages=build_prompt(schema_snippet, question),
).choices[0].message.content
sql = validate_sql(sql, valid_columns)
if sql is None:
return {"error": "query rejected by guard"}
return conn.execute(sql).fetchall() # read-only connection only本番グレードにするためのルール：
- スキーマダンプではなくスキーマリンキング。 カタログ全体ではなく、関連するテーブルとリレーションを注入します——コンテキスト予算は現実の制約であり、無関係なテーブルこそ幻覚の始まりです。function-callingパターンがツール面に適用されます。
- 実行前に静的にバリデーション。 カラムのホワイトリスト、ステートメントタイプのチェック、本番版には本物のSQLパーサーを使います。バリデーションこそデモと本番デプロイの違いです。
- 読み取り専用で実行。 接続は構造的に読み取り専用にします——これは譲れない項目なので、下のガードレールセクションを参照してください。
- 必要なときだけエージェント型に。 シングルショットから始め、評価セットが実際の質問でシングルショットの失敗を示した場合にのみ、多段階のプランニング（本シリーズのエージェントアーキテクチャ）を追加します。
ガードレールの強制方法：デフォルトで読み取り専用
要点：独立した4つのレイヤー——それぞれ単独でも十分です。なぜなら、失敗のケースには想定外のユーザーが関わるからです。
| レイヤー | ブロックするもの | 配置場所 |
|---|---|---|
| 読み取り専用データベースアカウント | すべての書き込みを構造的に | データベース設定 |
| クエリインターセプション | モデルに関係なく非SELECTステートメント | アプリケーションのミドルウェア |
| 行数・時間・コスト制限 | 暴走するクエリとJOIN | アプリケーションのミドルウェア＋レート制限 |
| 権限スコーピング | クロステナントと権限昇格のクエリ | スキーマビュー＋アクセスガード |
最初のレイヤーはチームがスキップしがちでありながら最も重要なものです：読み取り専用のデータベースアカウントがあれば、「モデルがDELETEを生成した」はインシデントではなく何でもない出来事になります。2026年のツールは追いついています——本番フレームワークは、生成されたクエリに対して各ユーザーの実際のデータアクセスルールを強制する決定論的アクセスガードを今や出荷しており、プロンプトレベルの指示では塞げなかったクロステナントの穴を閉じます。信頼度の高い順のパターン：データベースアカウント→ミドルウェアのパーサー→ユーザー別アクセスガード→モデルへの指示。最後のレイヤーは制御ではなく親切心です。
危険なSQLを出荷してしまうよくある失敗
要点：4つの失敗クラス——3つは安全性、1つはコストに関するもの——すべて回避可能です。
- 読み取り専用の強制がない。 アカウントが書き込めなければ、モデルも書き込めません。他はすべて多層防御（defense in depth）ですが、これこそがその核心です。
- カラムのバリデーションがない。 幻覚のカラムは明示的に失敗しますが、幻覚のJOINは静かに成功します。本物のパーサーによる静的バリデーションは両方を捕捉します。
- 単一ダイアレクトでのデプロイ。 PostgresでテストしてSnowflakeに出荷する：ダイアレクトのズレが、動くクエリを壊れたクエリや微妙に間違ったクエリに変えます。評価セットはサポートするすべてのダイアレクトで実行しましょう。
- すべてのクエリにフロンティアモデル。 評価セットのコスト列には理由があります：単純なルックアップはコストの数分の一の予算重視モデルで、フロンティアモデルは曖昧な10%のために取っておきます。custom routingがこれを機械的にし、モデルカタログが利用可能なモデルを示します。
FAQ
2026年のtext-to-SQLエージェントの精度はどのくらいですか？
公開ベンチマークの曖昧性のないサブセットでは、およそ87〜91%の実行精度です——ただし、ベンチマーク自体に文書化されたアノテーションエラーがあるため、あなたのスキーマでの評価だけが意味のある数字です。複雑な複数テーブルスキーマでの実世界の精度はさらに低く、それが評価セットの存在理由です。
エージェントが幻覚のカラムを生成するのを防ぐには？
3つのレイヤー：関連テーブルのみを注入するスキーマ注入、本物のパーサーによるカラムホワイトリストへの静的バリデーション、そして失敗をリトライにフィードバックする実行時エラーハンドリングです。プロンプトへの指示だけでは制御になりません。
読み取り専用の強制で本当に十分ですか？
主要な制御としては、はい——読み取り専用のデータベースアカウントは、モデルが何をしようと、生成された書き込みをすべて不可能にします。残りを処理するレイヤーとして、クエリインターセプション、行数・コスト制限、ユーザー別アクセスガードを追加しましょう。
シングルショットかエージェント型か——どちらを構築すべきですか？
シングルショットから始めて、評価セットに判断させましょう。実際の質問がJOINや曖昧さで失敗するなら、エージェント型のプランニングを段階的に追加します。最初からエージェント型で始めるチームは、プランニングが不要だったクエリに対してコストを払うことになります。
複数のSQLダイアレクトをサポートするには？
スキーマ注入にダイアレクト固有のガイダンスを含め、評価セットをすべてのダイアレクトで実行し、ダイアレクトの違い（クォーティング、関数、LIMITのセマンティクス）をプロンプト契約に文書化します。出荷前にすべてのダイアレクトでテストしましょう。
Text-to-SQLクエリのコストはいくらですか？
単純なルックアップの予算重視モデルでは1セント未満から、エージェント型分析のフロンティアモデルでは相当な倍率のコストまで幅があります。評価セットでクエリあたりコストを記録し、複雑度でルーティングすれば、平均は低く保たれます——クイックスタートが、ルーティングを設定にする統合エンドポイントのパターンを示しています。
まとめ
Text-to-SQLエージェントは2026年に本番対応が整い、注意点も織り込み済みです：実行ベースの採点で自分のスキーマをベンチマークし、スキーマをダンプせずリンキングし、実行前に静的にバリデーションし、データベースレイヤーで読み取り専用を強制します。ツールが成熟するにつれて猶予期間は縮まっています——しかし、今のうちに評価セットとガードレールを構築したチームこそ、エージェントを出荷できるチームであり、デモだけのバージョンはデモのまま残ります。
猶予期間は縮まっています——切り抜ける鍵はあなたの評価セットです。TokSpan APIキーを取得して、100問のセットを複数のモデルで実行しましょう——$5分の無料クレジットで最初の評価が賄えます——そして、ドルあたりの精度（accuracy-per-dollar）でスタックを選ばせてください。