Cortex Analyst におけるメタデータ露出の制御とAPI駆動によるText-to-SQL精度評価の確立

背景

Snowflake の Cortex Analyst は、自然言語の質問を SQL に変換する Text-to-SQL サービスである。ビジネスユーザが SQL を書かずにデータ分析を行えるため、多くの企業で導入が進んでいる。

しかし、実際の運用において、生成される SQL の精度が想定より低いケースも指摘されている。特に、Cortex Analyst のロールから見えている物理テーブルのメタデータが、LLM の推論プロセスにどう影響するかについて、他の Snowflake ユーザとの間で議論になった。

本記事では、Snowflake サポートへの確認を通じて明らかになった、Snowflake Intelligence、Cortex Agents / Analyst 各サービスの仕様と、エージェントを開発・テストする際の注意点をまとめる。

Snowflake Intelligence のアーキテクチャ理解

本記事で扱う問題を理解するには、Snowflake Intelligence でユーザが質問した際の各サービスの連携を把握する必要がある。以下、各コンポーネントの役割と連携フローを説明する。

各コンポーネントの役割

• Snowflake Intelligence（UIレイヤー）: ユーザから質問を受け取るインターフェース。エージェントがアクセスできるセマンティックモデルを制限する機能を持つ。
• Cortex Agents（オーケストレーション層）: ユーザからの質問からタスクを決定し、どのサービスにタスクをアサインするかを決める。Text to SQL タスクの場合は、アサイン先が Cortex Analyst である。ユーザとの会話履歴を管理し、タスクアサイン先のサービスに渡す会話履歴の要約を決めるのも Cortex Agents である。
• Cortex Analyst（Text-to-SQL実行層）: Text to SQL を担当するサービス。以下に挙げる情報をプロンプトにまとめ、LLM にSQL 生成を依頼し、Snowflake の SQL クエリエンジンに SQL を送信する。
  • ユーザとの会話履歴の要約
  • セマンティックモデル（ビジネス用語と物理テーブルの関係を定義した YAML ファイル）
  • 付与されたロールから見える物理テーブルのスキーマ（テーブルやカラムの定義など）
• LLM（推論エンジン）: サードパーティもしくは Snowflake 自身の LLM がホストされており、Cortex Analyst から受けとったプロンプトを基に推論を行い、実行すべき SQL を生成する。
• Snowflake DB（クエリエンジン）: 実際の SQL クエリ実行を行う。

連携フロー

1. ユーザが Snowflake Intelligence に質問を入力
2. Cortex Agents がタスクを判断し、Cortex Analyst に Text-to-SQL タスクをアサイン
3. Cortex Analyst がコンテキスト（会話履歴、YAML、物理メタデータ）を LLM に送信
4. LLM が SQL を生成
5. Snowflake DB がクエリを実行
6. 実行結果が Cortex Agents → Snowflake Intelligence を経由してユーザに提示

以下の図は、この連携フローを視覚化したものである。

本調査の目的

前述のアーキテクチャを踏まえ、Text-to-SQL の精度を向上させるため、Snowflake サポートに以下の3点を確認した。

• メタデータの影響範囲: Cortex Analyst のロールから見えるメタデータが、生成される SQL の精度にどう影響するか。UI上の制限とバックエンド API の挙動の違いも含む。
• テスト戦略の最適化: 精度評価（ゴールデンテスト）を行う際、どのレイヤー（UI vs API）を対象にするのが最適か。
• デバッグの可能性: 精度が低い原因を特定するために、LLM の内部プロセス（プロンプトの内容など）をどこまで追跡できるか。

サポートとの議論詳細

A. インターフェースとメタデータの関係

Q. UI（Snowflake Intelligence）でエージェントがアクセスできるビューを制限しても、Cortex Agents / Analyst APIを直接叩けば制限外のビューにもアクセスできるか？
A. API経由であれば、UIレイヤーの制約を受けずにアクセスが可能

Q. セマンティックモデル（YAML）やエージェントへの指示以外に、物理テーブルのスキーマ情報も推論に使われるか？
A. セマンティックモデル作成時に格納されるメタデータがあるため、物理名やカラム名がコンテキストに含まれる可能性がある

Q. YAMLや物理メタデータに優先度はあるか？
A. Snowflake としては特定のルールや優先順位はない。LLM側が判断して使用する 。

Q. ユースケースとは無関係なテーブルがコンテキストにあると精度は落ちるか？枝刈り機能はあるか？
A. 枝刈り機能はない。アクセスできないテーブル名が含まれる等の誤生成（悪影響）は起こりうる。

B. テストと評価のベストプラクティス

Q. 推奨されるテスト対象: ゴールデンデータ（事前に人間が用意した質問と答えのペア）を使って自動テストを行う際、UIとAPIのどちらを対象にすべきか？
A. APIに対して行う方が適切。UIの制約を排除し、モデルそのものの実力（YAMLと権限設定）を純粋に測定できるため。

Q. 自動化の観点: CI/CDでの自動テストにはどちらが向いているか？
A. APIの方がCI/CDでの自動化や正解率（Accuracy）のスコアリングが容易。

C. オブザーバビリティ（可観測性）

Q. プロンプトの可視化: LLMのコンテキストに何が載り、何が推論に影響したか詳細を知ることはできるか？
A. ユーザー側でそのレベルの情報（内部動作）にアクセスすることはできない。

Q. 確認可能なログの範囲: 生成SQL、YAMLの断片、エラーメッセージは見れると考えてよいか？
A. その通り、これらは確認可能。

Q. 確認不可能な範囲: 過去の会話履歴の要約プロセスや、プロンプトの結合順序は見えないか？
A. LLMの内部動作や結合プロセスは監視できない。

サポートとの議論から得られたベストプラクティス

Snowflake サポートとの議論を通じて、以下の重要な知見が得られた：

1. メタデータは推論に影響する: Cortex Analyst は、セマンティックモデル（YAML）だけでなく、物理テーブルのメタデータもコンテキストとして使用する
2. API テストが推奨される: UI レイヤーの制約を排除し、純粋なモデルの実力を測定するには、API 経由のテストが適切
3. 内部プロセスは不可視: プロンプトの結合プロセスや LLM の思考過程は、ユーザー側から確認できない

これらの知見を基に、高精度な Text-to-SQL エージェントの設計・開発・運用に関するベストプラクティスを以下にまとめる。

1. エージェント設計：セマンティックモデルと権限の最適化

信頼できるエージェント構築の鍵は、LLMに渡す「コンテキスト」をいかに制御し、純度を高めるかにある。

最小権限の原則

• 不要なメタデータの排除: ユースケースに無関係なテーブルやカラムのメタデータがコンテキストに含まれると、LLMが誤ってそれらを参照したSQLを生成するリスクがある。そのエージェントのユースケースに無関係な物理テーブルがそもそも見えないようにする（アクセス可否ではなく）。
• 適切な粒度にエージェントを分割：まとまったユースケースの単位でエージェントを分け、セマンティックモデルのスコープを制限することで、無関係なセマンティックモデルがコンテキストに入ることを防止する。
• 専用ロールの設定: Cortex Analystが使用するロールで見える範囲（物理テーブル・セマンティックビュー）を必要最小限に絞り、LLMが「迷う」材料を物理的に断つことが推奨される。

物理スキーマとセマンティック層の乖離に注意

• Cortex Analystは、セマンティックモデル（YAML）の定義だけでなく、基盤となる物理テーブルやカラム名もコンテキストとして読み取る。論理的な定義と物理的な名称が矛盾しないよう、整備されたマート層（整理されたテーブル群）をソースにすることが望ましい。

優先順位の理解

• Snowflake 側から見たコンテキスト内の情報（YAML、指示、物理メタデータ）に厳密な優先順位はなく、LLMがその都度判断して使用する。そのため、特定のルールで制御しようとするのではなく、提供する情報自体を正確に保つことが重要。

2. 開発・評価：自動テストとCI/CDの導入

エージェントの品質を「主観」ではなく「スコア」で管理するための体制を構築する。

APIレイヤーでの自動テスト（推奨）

• UIレイヤー（Snowflake Intelligence）はリクエストの仲介に過ぎず、またUI独自の制約によりバックエンドの純粋な実力を測りづらい。
  ゴールデンテストセット（人間が作成した「質問」と「正解SQL/回答」のペア）を用い、直接 Cortex Agents /Analyst API を叩いて精度（Accuracy）を測定する体制を推奨する。

CI/CDパイプラインへの組み込み

• セマンティックモデル（YAML）の変更が精度に与える影響を定量化するため、CI/CD上で自動テストを走らせ、正解率のスコアリングを自動化する。

3. 運用・改善：Observabilityの活用と限界の理解

運用フェーズでは、システムが見せてくれる情報と見せてくれない情報を明確に区別し、トラブルシューティングの戦略を立てる。

Snowflake 側で確認可能なこと (System View / Trace)

• 生成された最終SQL: LLMが最終的に導き出した「答え」。
• YAMLの断片: 推論時に参照されたセマンティックモデルの特定箇所。
• エラーメッセージ: 推論失敗時の内部スタックトレース。

Snowflake 側で確認できないこと（ブラックボックス領域）

• プロンプトの結合プロセス: YAML、指示、物理メタデータがどのような順序や優先順位でLLMに渡されたか。
• コンテキストの要約過程: 会話履歴がどのように要約されて推論に渡されたか。
• LLMの内部思考: なぜその情報が選ばれたかという「思考のプロセス」。

実践への第一歩

上記のベストプラクティスを踏まえ、まず着手すべき具体的なアクションを以下に示す。これらは、Text-to-SQL エージェントの精度向上に直結する重要なステップである。

1. マート層の再定義

現在のロールで見えているテーブルに、ユースケース外のものが含まれている場合、まずは Cortex 専用のクリーンなスキーマを作成することをお勧めする。

具体的な手順:

• 現在のロールでアクセス可能なテーブルをリストアップ
• ユースケースに必要なテーブルのみを選定
• Cortex Analyst 専用のビューまたはスキーマを作成

2. ゴールデンテストの作成

過去にユーザーが尋ねた質問から、代表的な 20-50 問を選んで「正解」を定義し、API 経由でテストを回せるスクリプトを準備する。

ゴールデンテストの例:

• 質問: 「先月の売上トップ10の商品は？」
• 正解SQL: SELECT product_name, SUM(sales) ...
• 期待される回答: 商品名と売上のリスト

3. カスタム指示の追加

汎用的な SQL 生成に不満がある場合、特定の計算ロジックやドメイン知識を「指示（Instructions）」として明文化し、YAML に組み込むことで精度を微調整できる。

例:

instructions:
  - "売上の集計は必ず税抜き金額（price_before_tax）を使用すること"
  - "顧客セグメントは customer_segment カラムの値を使用すること"

まとめ

本記事では、Snowflake Cortex Analyst を用いた Text-to-SQL エージェントの精度向上について、サポートとの議論を通じて得られた知見をまとめた。

重要なポイント

1. コンテキストの純度が精度を左右する: Cortex Analyst は YAML だけでなく物理メタデータも参照するため、不要なテーブルを見せないことが重要
2. API テストで真の実力を測定: UI の制約を排除し、API 経由でゴールデンテストを実施することで、モデルの純粋な精度を評価できる
3. 内部プロセスは不可視: プロンプトの結合過程や LLM の思考は確認できないため、入力（コンテキスト）の品質を高めることに注力すべき

次のステップ

まずは以下の3つのアクションから始めることをお勧めする：

1. マート層の整理: Cortex Analyst 専用のクリーンなスキーマを作成
2. ゴールデンテストの準備: 20-50問の質問と正解のペアを定義
3. CI/CD への組み込み: API 経由の自動テストで精度を継続的に監視

これらの施策により、Text-to-SQL エージェントの精度を体系的に向上させることができる。