Snowflake Cortex Analystで自然言語から分析へ｜セマンティックモデル設計

Snowflake Cortex Analystは、ビジネスユーザーが自然言語で質問を投げるだけで、構造化データに対するSQLクエリを自動生成・実行できるサービスです。 セマンティックモデル（YAML定義）をもとにテーブル構造とビジネスロジックを理解し、正確なSQLを生成します。 本記事では、セマンティックモデルの設計方法、変換フローの仕組み、権限設計を解説します。

Cortex Analystとは

Cortex Analystは、自然言語の質問を受け取り、セマンティックモデルの定義に基づいてSQLクエリを生成するSnowflakeのマネージドサービスです。 従来のBIツールではダッシュボード設計者がクエリを事前定義する必要がありましたが、Cortex Analystではエンドユーザーが自由形式の質問を投げるだけで回答を得られます。

生成されるSQLはSELECT文のみに限定されるため、データの変更リスクはありません。 またSnowflakeのRBACが適用されるため、ユーザーのロールでアクセスできないデータは結果に含まれません。

自然言語→SQL変換フロー

[ビジネスユーザー]
       │ 「先月の商品カテゴリ別売上は？」
       ▼
[Cortex Analyst API]
       │
       ├─ 1. セマンティックモデル（YAML）を読み込み
       │     └─ テーブル構造・カラムの意味・計算式を把握
       │
       ├─ 2. LLMが自然言語を解析
       │     └─ 意図を理解し、該当するテーブル・カラムをマッピング
       │
       ├─ 3. SQLクエリを生成（SELECT文のみ）
       │     └─ セマンティックモデルの定義に従ったJOIN・集計を構築
       │
       └─ 4. SQLを返却（自動実行 or ユーザー確認後実行）
              └─ 結果はJSON形式でAPIレスポンスに含まれる

セマンティックモデルの構造

セマンティックモデルはYAML形式で記述し、Snowflakeステージ上に配置します。 モデルには論理テーブル・ディメンション・メジャー・時間ディメンション・リレーションシップを定義します。

# semantic_model.yaml
name: sales_analytics
description: "EC売上分析用セマンティックモデル"

tables:
  - name: orders
    base_table:
      database: ANALYTICS_DB
      schema: PUBLIC
      table: FACT_ORDERS
    description: "注文トランザクションテーブル"

    dimensions:
      - name: order_id
        expr: ORDER_ID
        description: "注文の一意識別子"
        data_type: VARCHAR

      - name: product_category
        expr: PRODUCT_CATEGORY
        description: "商品カテゴリ（家電、食品、衣料品など）"
        data_type: VARCHAR

    time_dimensions:
      - name: order_date
        expr: ORDER_DATE
        description: "注文日"
        data_type: DATE

    measures:
      - name: total_revenue
        expr: SUM(ORDER_AMOUNT)
        description: "合計売上金額"
        data_type: NUMBER

      - name: order_count
        expr: COUNT(DISTINCT ORDER_ID)
        description: "注文件数"
        data_type: NUMBER

      - name: avg_order_value
        expr: AVG(ORDER_AMOUNT)
        description: "平均注文単価"
        data_type: NUMBER

  - name: customers
    base_table:
      database: ANALYTICS_DB
      schema: PUBLIC
      table: DIM_CUSTOMERS
    description: "顧客マスタ"

    dimensions:
      - name: customer_id
        expr: CUSTOMER_ID
        description: "顧客ID"
        data_type: VARCHAR

      - name: region
        expr: REGION
        description: "顧客の所在地域"
        data_type: VARCHAR

relationships:
  - name: order_customer
    left_table: orders
    right_table: customers
    join_type: LEFT
    relationship_columns:
      - left_column: CUSTOMER_ID
        right_column: CUSTOMER_ID

verified_queries:
  - name: "月次カテゴリ別売上"
    question: "商品カテゴリ別の月次売上を教えて"
    sql: |
      SELECT
        DATE_TRUNC('MONTH', o.ORDER_DATE) AS month,
        o.PRODUCT_CATEGORY,
        SUM(o.ORDER_AMOUNT) AS total_revenue
      FROM ANALYTICS_DB.PUBLIC.FACT_ORDERS o
      GROUP BY 1, 2
      ORDER BY 1, 3 DESC

YAML定義の重要要素

APIからの呼び出し

Cortex AnalystはREST APIおよびPython SDKから呼び出します。Snowsight上のStreamlitアプリに組み込むことも可能です。

# Python SDKでの呼び出し例
import json
from snowflake.core import Root

root = Root(session)

analyst = root.databases["ANALYTICS_DB"].schemas["PUBLIC"].cortex_analyst

response = analyst.send_message(
    semantic_model_file="@my_stage/semantic_model.yaml",
    messages=[
        {"role": "user", "content": "先月の地域別売上トップ5を教えて"}
    ]
)

# レスポンスからSQLと結果を取得
for item in response.message.content:
    if item.type == "sql":
        print("Generated SQL:", item.statement)
    elif item.type == "text":
        print("Explanation:", item.text)

権限設計

Cortex Analystの権限はSnowflakeの標準RBACモデルに従います。

-- Cortex Analyst利用ユーザーへの権限付与例
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE analyst_role;
GRANT USAGE ON DATABASE analytics_db TO ROLE analyst_role;
GRANT USAGE ON SCHEMA analytics_db.public TO ROLE analyst_role;
GRANT SELECT ON ALL TABLES IN SCHEMA analytics_db.public TO ROLE analyst_role;
GRANT READ ON STAGE analytics_db.public.my_stage TO ROLE analyst_role;
GRANT USAGE ON WAREHOUSE analyst_wh TO ROLE analyst_role;

Verified Queries（検証済みクエリ）

セマンティックモデルのverified_queriesセクションに質問とSQLのペアを登録することで、 類似した質問が投げられた際のSQL生成精度が向上します。 これはfew-shot promptingのアプローチで、特にビジネス固有の用語やロジックがある場合に効果的です。

• 質問文は実際のビジネスユーザーが使う自然な言い回しで記述する
• SQLはセマンティックモデルで定義したテーブル・カラムを参照する
• 10〜20個のverified queriesを登録するとSQL生成精度が大幅に向上する

制限事項と注意点

• 生成されるSQLはSELECT文のみ（DMLやDDLは生成されない）
• セマンティックモデルで未定義のテーブルやカラムには言及できない
• 非常に複雑なJOIN（5テーブル以上）では精度が低下する場合がある
• セマンティックモデルのdescriptionが不十分だと誤ったカラムマッピングが発生する
• 現時点ではCortex Analystの実行はサーバーレスクレジットで課金される

試験対策のポイント

• セマンティックモデルはYAML形式でステージ上に配置する
• 生成SQLはSELECT文に限定され、RBACが適用される
• verified_queriesはSQL生成精度を向上させるfew-shotの仕組み
• Cortex AnalystとCortex Searchの違いを明確に区別する
• SNOWFLAKE.CORTEX_USERデータベースロールの付与が必要

サンプル問題

よくある質問