Cortex Analyst 検証済みクエリリポジトリ¶

Cortex Analyst 検証済みクエリリポジトリ（VQR）は、質問とそれに答える SQL クエリのコレクションを提供することで、結果の精度と信頼性を向上させるのに役立ちます。Cortex Analyst は、類似した質問に答える際に、リポジトリから関連する SQL クエリを活用します。セマンティックモデル YAML ファイルで検証クエリを指定することができます。

重要

検証済み SQL クエリは、セマンティックモデルで定義された論理テーブルと列の名前を使用しなければなりません。詳しくは、クエリ例とそのディスカッションをご参照ください。

検証済みクエリは、ここに示すように、セマンティックモデルの verified_queries セクションで指定されます。

verified_queries:

# Verified Query 1
- name:                         # A descriptive name of the query.
  question:                     # The natural language question that this query answers.
  verified_at:                  # Optional: Time (in seconds since the UNIX epoch, January 1, 1970) when the query was verified.
  verified_by:                  # Optional: Name of the person who verified the query.
  use_as_onboarding_question:   # Optional: Marks this question as an onboarding question for the end user.
  sql:                          # The SQL query for answering the question.

# Verified Query 2
- name:
  question:
  verified_at:
  verified_by:
  use_as_onboarding_question:
  sql:

以下は検証済みクエリを含むセマンティックモデルのサンプルです。

name: Sales Data
tables:
- name: sales_data
  base_table:
    database: sales
    schema: public
    table: sd_data

  dimensions:
    - name: state
      description: The state where the sale took place.
      expr: d_state
      data_type: TEXT
        unique: false
        sample_values:
          - "CA"
          - "IL"

    # Time dimension columns in the logical table.
    time_dimensions:
      - name: sale_timestamp
        synonyms:
          - "time_of_sale"
          - "transaction_time"
        description: The time when the sale occurred. In UTC.
        expr: dt
        data_type: TIMESTAMP
        unique: false

    # Measure columns in the logical table.
    measures:
      - name: profit
        synonyms:
          - "earnings"
          - "net income"
        description: The profit generated from a sale.
        expr: amt - cst
        data_type: NUMBER
        default_aggregation: sum

verified_queries:
  - name: "California profit"
    question: "What was the profit from California last month?"
    verified_at: 1714497970
    verified_by: Jane Doe
    use_as_onboarding_question: true
    sql: "
SELECT sum(profit)
FROM __sales_data
WHERE state = 'CA'
    AND sale_timestamp >= DATE_TRUNC('month', DATEADD('month', -1, CURRENT_DATE))
    AND sale_timestamp < DATE_TRUNC('month', CURRENT_DATE)
"

上記の例では、 __sales_data がモデルで定義された sales_data テーブルに対応します。名前の衝突を避けるため、論理テーブル名の先頭にはアンダースコアを2つ付けます。クエリで使用される列（state、 sale_timestamp、 profit）は、モデルの sale_data テーブルで定義された論理列です。基礎となる列の名前（d_state、 dt、 amt、 cst）は、クエリでは直接使用されません。

例で示したように、質問は完全な文章である必要はなく、また実際に質問の形式である必要もありませんが、ユーザーが質問しそうな内容を反映したものでなければなりません。SQL クエリが構文的に正しく、提起された質問に実際に答えていることを確認します。これが「検証済みクエリ」の本質です。無効または不正確なクエリは、 Cortex Analyst のパフォーマンスと精度に悪影響を及ぼす可能性があります。

Tip

次のセクションで説明するオープンソースのセマンティックモデル生成アプリを使えば、 SQL や YAML の構文を気にすることなく、検証済みクエリをセマンティックモデルに追加することができます。

セマンティックモデルジェネレーターを使った検証済みクエリの追加¶

SnowflakeはオープンソースのStreamlitアプリを提供しており、検証済みクエリをモデルに追加するのに役立ちます。このアプリをインストールして使用するには、以下の手順に従います。

リポジトリのクローン semantic-model-generator リポジトリのクローンから始めます。
認証情報を構成し、アプリをインストールします。 リポジトリの README の設定手順に従って、Snowflakeの認証情報を提供し、Snowflake上またはローカルでアプリを実行します。
アプリを構成します。 アプリを起動したら、提供されたフィールドにデータベース、スキーマ、セマンティックモデル YAML ファイルのステージの場所を入力します。YAML ファイルはウィンドウの左側にある対話型エディターに表示されます。
クエリを生成します。 ウィンドウの右側で、チャットインターフェイスを使って、 SQL クエリを生成する質問をします。
クエリを検証して保存します。

生成されたクエリとその結果を確認します。期待通りに動作した場合は、アシスタントの回答の下にある Save as verified query ボタンを選択し、クエリをセマンティックモデルに追加します。

生成されたクエリが正しくない場合は、 Edit ボタンを選択してクエリを修正します。変更したクエリを実行し、意図した結果が得られるかどうかを確認します。クエリが思い通りに動作するまで、編集とテストを続けます。次に、 Save as verified query を選択して、セマンティックモデルに追加します。

セマンティックモデルを更新します。 ウィンドウの左下にある Save ボタンを選択し、セマンティックモデルを更新します。さらにクエリを追加するには、このプロセスを繰り返します。
新しい YAML ファイルをアップロードします。 追加したクエリに満足したら、 Upload ボタンを選択し、新しい YAML ファイルのファイル名を入力し、 Submit Upload を選択します。

Snowsightのステージに戻ると、新しいセマンティックモデル YAML ファイルと検証済みクエリが表示されます。

提案された Cortex Analyst 確認済みクエリエントリの追加¶

Cortex Analyst は、 Snowsight で確認済みクエリの提案インターフェースも提供します。これは、ユーザーの行動に基づいて、新しい確認済みクエリの候補を提示します。確認済みクエリ候補の追加については、セマンティックモデルとビューの提案を参照してください。

Cortex Analyst 応答で使用された検証済みクエリの表示¶

ユーザーの質問が検証済みクエリリポジトリ（VQR）のクエリと類似している場合、 Cortex Analyst はそのクエリを使用して、応答で SQL クエリを生成します。どの検証済みクエリが使用されたかは、 API 応答の信頼度フィールドをご参照ください。