このシリーズで作るもの（ゴール）
Slackで /sql 今月の売上を日次で、7日移動平均も表示 と投げると、
LangGraph が BigQuery のスキーマ文脈から SQL を生成→検証→実行し、
数秒で表やCSV/画像を返信する社内向けSQLボットを実装します。
Text-to-SQLはAIエージェントで実現します。
- 自然文 → SQL → 実行 → 整形 → Slack返信の一連の流れを本番運用前提で解説
- 署名検証（5分以内）や多ワークスペース（team_id）対応など運用の落とし穴を回避
- LangGraphの チェックポイント（Postgres） で失敗時の再試行や追跡を可能に
- BigQueryは最小権限（dataset単位）＆既定データセット固定で安全に
- 定期レポート（毎朝9時のKPI配信）や監視もセットで提供
なぜこれを作るのか（目的）
- ビジネス意思決定の即時性：Slack から数秒でメトリクス確認、”待ち時間ゼロ”の意思決定を実現
- エンジニア工数の削減：自然文→SQL の自動化で、アドホック分析の依頼/受託を低減
- ガバナンスの担保：BigQuery権限の最小化、危険なSQLの静的検証、ログ/監査の整備で安全運用
- 拡張性：LangGraph×チェックポイントにより、失敗時の再試行やフロー拡張が容易
誰のための仕組みか（役割）
- CS/営業/事業担当：Slackから自然文でKPIや明細を瞬時に取得（表/CSV/画像でそのまま共有）
- 分析担当：テンプレ化 & スナップショット（Golden）テストで期待SQLを固定
- データチーム：BigQuery権限境界、既定DS固定、危険クエリ抑止で安心して開放
- SRE/プラットフォーム：Cloud Run + 最小権限、LangGraphの状態（Postgres）で監査・再実行を容易に
全体アーキテクチャ
データフロー（概要）
- SlackがSlashコマンドをPOST（タイムスタンプ付き）
- FastAPIが署名検証→team_idからテナント解決→（必要に応じて非同期処理へ）
- LangGraphがスキーマ文脈を収集→SQL生成→静的検証（危険DDL/DML抑止）
- BigQueryで実行→結果を表/CSV/画像などに整形
- Slackへ応答（長時間処理はACK→遅延返信）／失敗はログに記録し、再試行・調査を容易に
セキュリティと権限の基本方針
- 鍵レスADC（Application Default Credentials）を優先し、サービスアカウントは最小権限のみ
- BigQueryはデータセット単位で付与（例：roles/bigquery.dataViewer）
- 既定データセット固定で非修飾テーブル参照を所定DSに向ける（誤爆防止）
- Slackの署名検証（5分以内）、リプレイ攻撃対策、team_idでのマルチテナント分離
- ログに個人情報や秘密情報を残さない（マスキング／ハッシュ化）
連載の目次（予定）
- Part 0：全体像と目次（本記事）
- Part 1：アーキテクチャとMVPを一気通貫で — /sql が1クエリ通る到達点
- Part 2：Slack署名検証と team_id ルーティング（多テナント設計）
- Part 3：LangGraphで組む NL→SQL フローとチェックポイント運用
- Part 4：Cloud Run × BigQuery 最小権限とコスト設計
※ 本記事では構想の共有に留め、.env や実装詳細は Part 1 以降で解説します。
本記事のスクリーンショットやログは、トークン・team_id・社名・実スキーマ名をすべてダミーに置き換えています。
ランディングページのご案内
プロダクト概要・導入メリット・デモイメージは、こちらのLPにまとめています。
👉 ランディングページ
次回：Part 1 へ
Part 1：アーキテクチャとMVPを一気通貫で — /sql が1クエリ通る到達点