Cortex Analyst（コーテックス アナリスト）は、Snowflake に保存した構造化データに対し、自然言語の質問から SQL を生成する REST API です。テーブル定義だけでなく、指標やテーブル間の関係を記述した「セマンティックビュー」を読んで SQL を組み立てるため、列名が業務用語とかけ離れたデータでも正しい集計式を選びやすくなります。ただし 2026年8月28日、Snowflake は Cortex Agents への移行を推奨しました。この記事では、Cortex Analyst の仕組み、セマンティックビューの作り方、API の呼び出し方、権限、料金とリージョンを、2026年10月2日時点の公式ドキュメントに沿って説明します。単体 API を新規に採用すべきかどうかの判断材料もまとめます。
まとめ：Cortex Analystの要点と2026年時点の使い分け
- 役割：自然言語の質問を SQL に変換する API です。返るのは SQL 文と解釈の説明で、実行は呼び出し側が行います。
- 精度の源泉：論理テーブル・ディメンション・ファクト・メトリクス・リレーションシップを定義したセマンティックビューを使います。ステージに置く YAML のセマンティックモデルは後方互換のために残されている扱いです。
- 移行推奨：2026年8月28日から Cortex Agents 経由の利用が推奨です。セマンティックビューはそのまま引き継げ、REST API も残ります。
- 権限：
SNOWFLAKE.CORTEX_USERは既定で PUBLIC ロールに付与されています。Cortex Analyst だけを許可したい場合は CORTEX_USER を取り消し、CORTEX_ANALYST_USERを付けます。 - 料金：単体 API は 1,000 メッセージあたり 67 クレジットです。SQL を実行するウェアハウス代は別で、Agents 経由ではトークン課金に変わります。
- リージョン：AWS 東京（ap-northeast-1）でネイティブに提供されています。モデルは指定できません。
Cortex Analystの役割：自然言語の質問をSQLへ変換するAPI
公式ドキュメントは Cortex Analyst を、構造化データに基づくビジネス上の質問に答えるアプリを作るための、LLM ベースのフルマネージド機能と位置づけています。利用者は REST API に質問を送り、Cortex Analyst は質問の解釈文と SQL 文を返します。SQL はその場で実行されず、アプリ側がユーザーのロールで Snowflake に投げます。そのため、生成された SQL も通常のクエリと同じくロールベースのアクセス制御（RBAC）に従います。
推論時にモデルへ渡るのはテーブル名・列名・説明文などのメタデータで、顧客データはモデルの学習に使われません。
汎用のText-to-SQLとの違い：業務定義に基づくSQL生成
LLM にテーブル定義だけを渡して SQL を書かせる一般的な Text-to-SQL では、列 amt_ttl_pre_dsc が「割引前の売上総額」だという知識や、「純売上＝割引後の総売上の合計」という社内の計算ルールをモデルが知りません。公式ドキュメントはこの例を挙げ、セマンティックビューに SUM(gross_revenue * (1 - discount)) のような集計式を一度だけ定義しておけば、ツールごとに計算式がばらつくのを防げると説明しています。Cortex Analyst の精度を改善するには、セマンティックビューの説明・同義語・集計式を整備し、想定質問で生成 SQL を評価してください。
答えられない質問：SQLで解けない問いと前回結果の参照
公式ドキュメントは既知の制限として次の3点を挙げています。
- 「どんな傾向が見える？」のように SQL で解けない質問には答えません。
- 前回の SQL の実行結果にはアクセスできません。「製品一覧を出して」の後に「2番目の製品の売上は？」と聞いても、一覧の2番目を特定できません。
- 会話のターンが長くなったり、意図が頻繁に変わったりすると、追加質問の解釈が崩れることがあります。その場合は会話をリセットするよう案内されています。
質問が曖昧で SQL を作れないときは、SQL の代わりに「このモデルで答えられる質問」の候補（suggestions）が返ります。
2026年8月の移行推奨：単体APIとCortex Agentsの使い分け
2026年8月28日のリリースノートで、Snowflake は Cortex Analyst から Cortex Agents への移行を推奨しました。理由は、Cortex Agents が Cortex Analyst の全機能をより高い回答品質で提供するためです。Cortex Agents は構造化データの問い合わせに Cortex Analyst をツール（cortex_analyst_text_to_sql）として使うので、移行は作り直しではなく「呼び出し方の変更」です。セマンティックビューも、そこに保存した検証済みクエリもそのまま使えます。既存アプリは動き続け、Cortex Analyst REST API も引き続き提供されます。
| 比較項目 | 単体のCortex Analyst API | Cortex Agents経由 |
|---|---|---|
| エンドポイント | /api/v2/cortex/analyst/message |
エージェントの :run |
| 返るもの | 解釈文とSQL文 | SQLの実行結果と回答文 |
| SQLの実行 | 呼び出し側 | エージェントが指定ウェアハウスで実行 |
| 会話履歴 | 毎回 messages で全履歴を送る |
スレッドで保持 |
| 非構造データ | 扱えない | Cortex Searchと組み合わせ可 |
| 課金 | メッセージ単位 | トークン単位 |
新規に作るなら Cortex Agents を選ぶのが既定です。単体 API を選ぶ理由が残るのは、次のように「SQL 文そのもの」が欲しい場面に限られます。
- 生成された SQL を人がレビューしてから実行したい、あるいは実行前に自前の検査（対象テーブルの制限・LIMIT の付与など）を挟みたい。
- 既存の BI ツールや社内ポータルに、SQL 生成部分だけを組み込みたい。
- 質問1件あたりのコストをメッセージ単位で固定的に見積もりたい（Agents 経由は会話の長さに応じてトークン課金が増えます）。
エージェントの作成手順と REST API は Snowflake Cortex Agentsとは？CREATE AGENT・REST API・権限設定の実装手順 で詳しく扱っています。
セマンティックビューの構成要素と作り方
セマンティックビューは、業務上の概念をデータベース内に保存するスキーマレベルのオブジェクトです。通常のビューと同じく権限管理や共有の対象になり、Cortex Analyst と Cortex Agents の両方がこれを読んで SQL を生成します。
論理テーブル・ディメンション・ファクト・メトリクスの役割
| 要素 | 役割 | 例 |
|---|---|---|
| 論理テーブル | 業務上のエンティティ | 顧客、注文、明細 |
| リレーションシップ | 論理テーブル間の結合キー | 注文.顧客キー → 顧客 |
| ファクト | 行単位の数値 | 割引後の明細金額 |
| ディメンション | 集計の切り口 | 顧客名、注文年 |
| メトリクス | 集計済みのKPI | 平均注文額、顧客数 |
ファクトはメトリクスを組み立てる部品で、質問で触れるのは主にメトリクスとディメンションです。結合経路をリレーションシップで先に決めておくので、複数テーブルにまたがる質問でも誤った JOIN が起きにくくなります。
CREATE SEMANTIC VIEWの最小構成
作成には、対象スキーマの CREATE SEMANTIC VIEW 権限、作成先データベースとスキーマの USAGE 権限、参照するテーブルの SELECT 権限が要ります。次の例は、公式ドキュメントの TPC-H サンプルデータを使った定義を、2テーブルに絞ったものです。MY_DB.MY_SCH は、権限のある既存のデータベースとスキーマに置き換えてください。
CREATE SEMANTIC VIEW MY_DB.MY_SCH.tpch_rev_analysis
TABLES (
orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
PRIMARY KEY (o_orderkey)
WITH SYNONYMS ('sales orders')
COMMENT = 'All orders table for the sales domain',
customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
PRIMARY KEY (c_custkey)
COMMENT = 'Main table for customer data'
)
RELATIONSHIPS (
orders_to_customers AS
orders (o_custkey) REFERENCES customers
)
DIMENSIONS (
customers.customer_name AS customers.c_name
WITH SYNONYMS = ('customer name')
COMMENT = 'Name of the customer',
orders.order_year AS YEAR(o_orderdate)
COMMENT = 'Year when the order was placed'
)
METRICS (
customers.customer_count AS COUNT(c_custkey)
COMMENT = 'Count of number of customers',
orders.order_average_value AS AVG(orders.o_totalprice)
COMMENT = 'Average order value across all orders'
)
COMMENT = 'Semantic view for revenue analysis';WITH SYNONYMS と COMMENT は、モデルが質問の語と列を対応づけるための手がかりです。日本語で質問する前提なら、同義語に「顧客名」「得意先」のような社内で実際に使う呼び方も入れておきます。YAML で定義を書きたい場合は、ストアドプロシージャ SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML でセマンティックビューに変換できます。
Autopilot・Semantic Studio・旧YAMLモデルの位置づけ
SQL を書かずに作る手段として、Snowsight の Semantic View Autopilot（AI が下書きを作るウィザード）と、Workspaces 上の Semantic Studio があります。Autopilot は YAML のほか、Tableau や Power BI のファイルの取り込みにも対応しています。ステージに置く YAML のセマンティックモデルは引き続き使えますが、公式ドキュメントでは後方互換のための扱いで、新規の実装にはセマンティックビューが推奨されています。権限管理・共有・派生メトリクス・ファクトとメトリクスの公開範囲の指定はセマンティックビュー側にしかないので、ステージの YAML から始める理由はありません。
検証済みクエリとカスタム指示による精度の底上げ
ここでは、定義の整備に加えて使える2つの改善手段を紹介します。1つ目は Verified Query Repository（VQR）で、「質問」と「その正解 SQL」の組を登録しておくと、似た質問が来たときに Cortex Analyst がその SQL を参考にします。正解 SQL には物理テーブル名ではなく、セマンティックビュー上の論理名を使う必要があります。応答の confidence.verified_query_used を見れば、どの検証済みクエリが使われたかを確認できます。
2つ目はカスタム指示です。CREATE SEMANTIC VIEW の AI_SQL_GENERATION 句に「数値列は小数第2位で丸める」のような SQL 生成の指示を、AI_QUESTION_CATEGORIZATION 句に「ユーザー個人に関する質問は拒否する」のような質問分類の指示を書けます。精度の改善は、よく聞かれる質問を VQR に登録し、外れる質問の傾向をカスタム指示と同義語で直す、という順に進めるのが近道です。
REST APIの呼び出し方とレスポンスの読み方
質問は POST /api/v2/cortex/analyst/message に送ります（仕様は公式の Cortex Analyst REST API リファレンス）。認証には OAuth・キーペア JWT・プログラマティックアクセストークン（PAT）のいずれかを Authorization: Bearer ヘッダーで渡します。
リクエストの組み立て：messagesとsemantic_view
curl -X POST "https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/analyst/message" \
--header "Authorization: Bearer $PAT" \
--header "X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "注文年ごとの平均注文額を教えて" }
]
}
],
"semantic_view": "MY_DB.MY_SCH.TPCH_REV_ANALYSIS"
}'どのデータを使うかは、次の4つのフィールドのいずれかで指定します。
semantic_view：セマンティックビューの完全修飾名（推奨）semantic_model_file：ステージ上の YAML のパス（例@my_db.my_schema.my_stage/model.yaml）semantic_model：YAML 文字列をリクエストに直接埋め込むsemantic_models：上記のビューやファイルを配列で複数渡し、質問ごとに最適なものを Cortex Analyst に選ばせる
semantic_models を使うと、応答の semantic_model_selection にどれが選ばれたかが入ります。データソースが1つでも semantic_models の形で書いておけば、後から増やしたときにクライアントのコードを変えずに済みます。
レスポンスの型：text・sql・suggestionsとwarnings
応答の message.content[] には、型の違うブロックが並びます。
| type | 中身 | 返る条件 |
|---|---|---|
text |
質問の解釈文 | 常に |
sql |
SQL文と confidence |
SQLを生成できたとき |
suggestions |
答えられる質問の候補 | 質問が曖昧なとき |
sql と suggestions は同時には返りません。ほかに、処理は止めないが注意すべき点を伝える warnings、実際に使われたモデル名（response_metadata.model_names）、質問の分類（response_metadata.question_category）が付きます。公式ドキュメントは、将来ほかの型が追加されても壊れないよう、type で分岐する実装を求めています。
マルチターン会話：履歴を毎回送る仕様とコスト
追加質問をするには、過去の質問（role: "user"）と回答（role: "analyst"）を時系列順に messages へ並べて送ります。たとえば「2021年のアジアの前月比売上成長率は？」の後に「北米は？」と聞くと、Cortex Analyst は後者を「2021年の北米の前月比売上成長率は？」と言い換えて SQL を作ります。API 側は状態を持たないので、ターンが進むたびに全履歴を送り直す必要があり、公式ドキュメントも、履歴の増加に伴って計算処理のコストが増えると注記しています。ただし、単体 API のメッセージ単価が履歴の長さに応じて上がるという意味ではありません。
ストリーミング応答とフィードバックAPI
"stream": true を付けると、応答が Server-Sent Events で逐次返ります。途中で status イベントとして interpreting_question・generating_sql・validating_sql・done などが届くので、チャット UI に進捗を出せます。ただし、この並びは公式の応答例で、イベントの順序や内容は保証されていません。質問が曖昧な場合は generating_suggestions が届く例もあります。また POST /api/v2/cortex/analyst/feedback で利用者の良い・悪いの評価とコメントを送ると、Snowsight の Cortex Analyst 画面の Monitoring タブで確認できます。外れた質問を VQR に登録する材料として使えます。
権限設計：CORTEX_USERのPUBLIC既定付与とCORTEX_ANALYST_USER
Cortex Analyst を呼ぶロールには、データベースロール SNOWFLAKE.CORTEX_USER か SNOWFLAKE.CORTEX_ANALYST_USER のどちらかが必要です。前者は対象となる AI 機能すべて、後者は Cortex Analyst だけを使える権限です。見落としやすいのは、CORTEX_USER が既定で PUBLIC ロールに付与されている点です。何もしなければ全ユーザーが Cortex Analyst を呼べる状態なので、利用者を絞りたいなら ACCOUNTADMIN で次のように切り替えます。
USE ROLE ACCOUNTADMIN;
-- PUBLIC からの既定付与を外す
REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;
-- Cortex Analyst だけを許可するロールを作る
CREATE ROLE cortex_analyst_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_ANALYST_USER TO ROLE cortex_analyst_user_role;
GRANT ROLE cortex_analyst_user_role TO USER example_user;
-- セマンティックビューの利用権限
GRANT USAGE ON DATABASE my_db TO ROLE cortex_analyst_user_role;
GRANT USAGE ON SCHEMA my_db.my_sch TO ROLE cortex_analyst_user_role;
GRANT SELECT ON SEMANTIC VIEW my_db.my_sch.tpch_rev_analysis TO ROLE cortex_analyst_user_role;データベースロールはユーザーに直接付与できないため、カスタムロールを経由します。PUBLIC から CORTEX_USER を外すと、AI 関数など Cortex Analyst 以外の機能も使えなくなる点に注意してください。必要なロールには改めて付与します。
ステージ上の YAML を使う場合は、ステージの READ 権限が実質的なアクセス制御になります。公式ドキュメントは、ステージにアクセスできるロールなら、元テーブルの権限がなくてもそのステージ上のセマンティックモデルにアクセスできると警告しています。ステージの READ を付けるロールには、そのステージにある全モデルの参照テーブルへの SELECT もそろえておく必要があります。アカウント全体で機能を止めたいときは、ALTER ACCOUNT SET ENABLE_CORTEX_ANALYST = FALSE;（既定は TRUE）を実行します。
料金とリージョン：メッセージ課金・東京リージョン・使用モデル
メッセージ単位の課金と利用履歴の確認
Snowflake Service Consumption Table（2026年9月30日発効版）では、Cortex Analyst は 1,000 メッセージあたり 67 クレジットです。AI 関数や Cortex Agents が使う AI クレジットではなく、通常のウェアハウスと同じ Platform クレジットで計算されます。この単価は Cortex Analyst API を直接呼んだときだけに適用されます。Cortex Agents や Snowflake CoWork 経由で使った場合は、同じ表の別枠でモデルごとのトークン単価で課金されます。
公式ドキュメントによると、課金対象は HTTP 200 で返った応答だけで、単体 API ではメッセージのトークン数は料金に影響しません。生成された SQL を実行するウェアハウスの料金は別に発生します。単価の考え方と AI クレジットとの違いは Snowflake Cortex AIとは？機能一覧・料金・日本リージョンの制約と読み方 にまとめています。実績は次のビューで確認できます。
SELECT DATE_TRUNC('day', start_time) AS day,
username,
SUM(request_count) AS messages,
SUM(credits) AS credits
FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_ANALYST_USAGE_HISTORY
WHERE start_time >= DATEADD('day', -30, CURRENT_TIMESTAMP())
GROUP BY 1, 2
ORDER BY 1, 2;CORTEX_ANALYST_USAGE_HISTORY は1時間単位に集計され、過去365日分を保持します。METERING_HISTORY にもサービス種別 AI_SERVICES として計上されます。
東京リージョンでの提供とクロスリージョン推論
Cortex Analyst がネイティブに提供されているリージョンは、AWS では東京（ap-northeast-1）・シドニー・バージニア・オレゴン・フランクフルト・アイルランド・US East（Commercial Gov）、Azure では East US 2 と West Europe です。それ以外のリージョンでも、アカウントでクロスリージョン推論を有効にすれば利用できます。その場合、公式ドキュメントは性能の面から AWS の米国リージョンへの振り分けを推奨しています。中国本土では提供されていません。Azure の日本リージョン（Japan East など）はネイティブ提供の一覧に含まれないので、クロスリージョン推論の設定が前提になります。
選ばれるモデルの優先順位と固定できない点
Cortex Analyst では使うモデルを直接指定できません。公式ドキュメントによると、リージョンで使えるモデル、クロスリージョン推論の設定、モデル単位の RBAC 制限から、次の優先順位で、ロールがアクセスできる最上位のモデルが選ばれます。
- Anthropic Claude Sonnet 4.6
- Anthropic Claude Sonnet 4.5
- OpenAI GPT 4.1
- Arctic Text2SQL R1.5（thinking 有効）
- Mistral Large 2 と Llama 3.1 70b の組み合わせ
どれにもアクセスできないとリクエストは失敗します。モデルが変わると生成される SQL も変わるため、公式ドキュメントは、結果をそろえたいならリージョン・クロスリージョン設定・RBAC 制限をすべてのリクエストで同じにするよう求めています。同じ概要ページの別の箇所には「既定では Mistral と Meta のモデルで動く」という記述もありますが、選択順の節では Claude Sonnet 4.6 が最優先です。実際にどのモデルで生成されたかは、推測せず応答の response_metadata.model_names で確かめてください。
採用を見送るべき場面と失敗パターン
Cortex Analyst は、定義済みのメトリクスとディメンションの組み合わせで答えられる質問に強い一方、次の条件では期待どおりに働きません。
- テーブルの意味が社内で合意されていない：部署ごとに異なる「売上」の定義を区別せずにセマンティックビューへ登録すると、質問者が意図しない定義で集計されるおそれがあります。先に指標の定義をそろえるのが前提です。
- 答えの根拠が文書にある：規程・契約書・議事録の内容は SQL では引けません。非構造データを含むなら、Cortex Search と組み合わせられる Cortex Agents を選びます。
- 考察や示唆まで自動で欲しい：「なぜ売上が落ちたのか」のような問いには答えません。返るのは集計の SQL までです。
- 同義語を入れずに日本語で質問させる：列名もコメントも英語のまま日本語の質問を受けると、業務用語と列の対応づけが外れやすくなります。運用前に、想定質問を VQR とセマンティックビューの評価機能（Cortex Analyst evaluations）で検証してください。
社内向けのチャット画面を試作する手段として、公式のサンプルコードを Streamlit in Snowflake に載せる方法が用意されています。ほかのクラウドの同種機能と比べたい場合は、BigQuery Conversational Analytics も参考になります。
よくある質問
Cortex Analystは廃止されるのですか？
廃止は発表されていません。2026年8月28日に Cortex Agents への移行が推奨されましたが、既存のアプリは動き続け、Cortex Analyst REST API も引き続き提供されるとリリースノートに明記されています。新規の実装は Cortex Agents 経由で作るのが推奨です。
Cortex Analystの料金はいくらですか？
単体の API は 1,000 メッセージあたり 67 クレジット（Platform クレジット）で、HTTP 200 の応答だけが課金対象です。SQL を実行するウェアハウスの料金は別にかかり、Cortex Agents 経由ではトークン課金になります。
セマンティックモデルとセマンティックビューの違いは何ですか？
セマンティックモデルはステージに置く YAML ファイル、セマンティックビューはデータベース内のスキーマレベルのオブジェクトです。定義する内容はほぼ同じですが、権限管理・共有・派生メトリクスはセマンティックビューにしかありません。公式ドキュメントでは新規の実装にセマンティックビューが推奨され、YAML のモデルは後方互換のために残されています。
Cortex Analystは日本の東京リージョンで使えますか？
使えます。AWS の ap-northeast-1（東京）はネイティブ提供リージョンに含まれています。Azure の日本リージョンは一覧にないため、クロスリージョン推論を有効にして使います。
Cortex Analystは生成したSQLを自動で実行しますか？
単体の REST API は SQL 文を返すだけで、実行は呼び出し側が行います。Cortex Agents 経由では、エージェントに指定したウェアハウスで SQL が実行され、結果をもとに回答文が作られます。
