Cortex Analyst セマンティックモデル仕様¶
なぜセマンティックモデルを使用する理由¶
Cortex Analyst では、ユーザーが自然言語を使用してSnowflakeデータについて質問することができます。通常、ビジネスユーザーがデータに関する質問をする際に使用する語彙と、データベーススキーマで使用される語彙にはギャップがあります。これらのユーザーは通常、ビジネス用語やドメイン固有の用語を使用しますが、データベーススキーマでは、 ETL パイプラインでよく使用される略語や用語を使用することがあります。データベースのスキーマもまた、データセットに不慣れな人がデータを理解するのに役立つようなセマンティックな詳細が欠けていることがよくあります。この語彙の違いは、 Cortex Analyst がデータに関する質問に高い精度で答えることを困難にしています。
セマンティックモデルとは、データセットに関する追加のセマンティックな詳細を指定できるようにすることで、これらの問題に対処する軽量なメカニズムです。より説明的な名前や同義語のような、このような追加的なセマンティックな詳細によって、 Cortex Analyst は、データに関する質問に対してより確実に回答できるようになります。
注釈
セマンティックモデルは メタデータ と考えられています。
主な概念¶
注釈
このトピックでは、ベースとなるデータベース関連の成果物を「物理的」成果物、セマンティックモデル関連の成果物を「論理的」成果物と呼びます。
セマンティックモデルの構造と概念はデータベーススキーマと似ていますが、セマンティックモデルによってデータに関するより多くのセマンティック情報を提供することができます。
Snowflakeのセマンティックモデルの中核となる概念は、 論理テーブル です。論理テーブルは、物理的なデータベーステーブルやビューに対する単純なビューと考えることができます。各論理テーブルは論理列のコレクションで、 dimensions、 time_dimensions、 measures に分類されます。
論理列は、基礎となる物理列への参照、または1つ以上の物理列を含む式のいずれかになります。式は、文字列の連結や数学演算のような単純なものから、集計式を含むものまであります。例えば、 SUM(click)/SUM(spend) のような式を使って、クリック単価（CPC）を計算することができます。
セマンティックモデルはまた、 検証済みクエリリポジトリ （VQR）を含むことができます。これは、質問とそれに答える SQL クエリのコレクションを提供することによって、結果の正確さと信頼性を向上させるのに役立ちます。
Cortex Analyst 仕様のセマンティックモデルは YAML にあります。自然言語による質問に高い精度で答えるために必要なセマンティック情報を提供します。
一般的な構文は次のとおりです。
# Name and description of the semantic model.
name: <name>
description: <string>
# A semantic model can contain one or more logical tables.
tables:
# A logical table on top of a base table.
- name: <name>
description: <string>
# The fully qualified name of the base table.
base_table:
database: <database>
schema: <schema>
table: <base table name>
# Dimension columns in the logical table.
dimensions:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
data_type: <data type>
unique: <boolean>
cortex_search_service_name: <string>
# Time dimension columns in the logical table.
time_dimensions:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
data_type: <data type>
unique: <boolean>
# Measure columns in the logical table.
measures:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
data_type: <data type>
default_aggregation: <aggregate function>
# Commonly used filters over the logical table.
filters:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
# Example questions and queries that answer them
verified_queries:
# Verified Query (1 of n)
- 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.
セマンティックモデルジェネレーター¶
セマンティックモデルジェネレーター ツールを使って、 Cortex Analyst で使用するセマンティックモデルを生成することができます。このツールでは、セマンティックモデルを生成する方法として、Streamlitアプリ、コマンドライン、またはPythonコードで直接行うという複数のオプションを提供します。Streamlitアプリは特に便利で、ゼロからセマンティックモデルを作成したり、Snowflakeステージにアップロードされた既存のモデルを反復したりすることができます。
セマンティックモデル作成のヒント¶
YAML ファイルをビジネスドメインまたはトピックごとに整理する。
YAML ファイルを特定のビジネスドメインやトピックに合わせて構成し、スコープを絞る。例えば、セールス分析とマーケティング分析のために別々のセマンティックモデルを作成する。
ターゲットオーディエンス、予想される質問、 KPIs、必要なデータに基づいてユースケースを調整する。よく定義されたユースケースは、より豊かなセマンティックモデルとより効果的なデータ検索につながる。
エンドユーザーの視点から考える。
トピックについてユーザーが尋ねそうな主な質問を特定し、その質問に答えるために必要なテーブルと列のみを含める。
エンドユーザーが使用する語彙に近い名称や同義語を使用する。
DATETIME 列のタイムゾーンなど、初めてこのデータセットでクエリを書く人に役立つ重要な詳細を説明フィールドに含める。
複雑な計算をキャプチャする。
より難しい、またはビジネス特有のクエリを表現に組み込む。
長いテーブルの代わりに幅の広いテーブルを使う。
「metric」や「value」のような列を持つテーブルがある場合、各メトリックが列になるようにテーブルをフラット化する。このアプローチは、各メトリックに関するより多くのセマンティック情報をモデルに提供します。
自動生成された説明の確認
セマンティックモデルジェネレーター を使用している場合、テーブルと列の記述を自動的に生成しようとします。これらの記述が妥当かつ適切であることを常に確認し、必要に応じて修正します。
シンプルに開始し、徐々に拡大する
十分にスコープされたセマンティックファイルは、より高い精度と正確な結果を保証します。少数のテーブルと列から開始し、より多くの種類の質問をカバーするためにセマンティックモデル YAML を徐々に拡張していきます。YAML 構築は継続的なプロセスであることを忘れてはなりません。
検証済みのクエリを含める
検証済みクエリリポジトリ （VQR）は、平易な英語の質問とそれに答えるクエリのコレクションであり、結果の正確性と信頼性を向上させるのに役立ちます。
既知の制限¶
Cortex Analyst は、セマンティックモデルファイルに API の入力サイズ制限を設けており、 1MB に入力サイズを制限しています。
Cortex Analyst は、セマンティック YAML に追加されたサンプル値と検証済みクエリのインメモリ検索を実行します。すべてのサンプル値と検証済みクエリを削除した後、セマンティックモデルは32Kトークン（およそ4×32K文字、またはおよそ128 KB）を超えることはできません。セマンティックモデルジェネレーターの検証コマンドを使うことで、ファイルがこれらの制限内に収まるようにすることができます。より大きなコンテキストウィンドウを持つモデルのサポートが追加されるにつれて、制限は増えるかもしれません。
仕様¶
セマンティックモデル¶
セマンティックモデルはテーブルの集まりを表します。モデルにはテーブルの説明が含まれており、各テーブルにはテーブルの特定の側面に関する説明が含まれています。モデルに記述された各テーブルは、Snowflakeの物理的なベーステーブルにマッピングされます。
以下のフィールドがあります。
必須
nameこのセマンティックモデルの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
オプション（推奨）
descriptionどのような分析に役立つかの詳細を含む、このセマンティックモデルについての説明。
tablesこのセマンティックモデルの論理テーブルのリスト。
テーブル¶
論理テーブルは、物理データベーステーブルまたはビューに対するビューと考えることができます。以下のフィールドがあります。
必須
nameこのテーブルの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
base_tableデータベース内の基本ベーステーブルの完全修飾名。
オプション（推奨）
synonymsこのテーブルを参照するために使用される他の用語/フレーズのリスト。論理テーブル内の同義語間で一意でなければなりません。
descriptionこのテーブルの説明。
dimensionsこのテーブルのディメンション列のリスト。
time_dimensionsこのテーブルの時間ディメンション列のリスト。
measuresこのテーブルに含まれる測定のリスト。
filtersこのテーブルの定義済みフィルター（ある場合）。
ディメンション¶
ディメンションには、ステータス、user_type、プラットフォームなどのカテゴリ値が記述されます。以下のフィールドがあります。
必須
nameこのディメンションの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
exprこのディメンションの SQL 式。これは物理列への参照、またはベーステーブルの1つ以上の列を持つ SQL である可能性があります。
data_typeこのディメンションのデータ型。Snowflakeの全データ型の概要については、 SQL データ型リファレンス をご参照ください。なお、
VARIANT、OBJECT、GEOGRAPHY、ARRAYは現在サポートされていません。
オプション（推奨）
synonymsこのディメンションを参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。
descriptionどのようなデータを持っているかなど、このディメンションの簡単な説明。
uniqueこのディメンションに一意の値があることを示すブール値。
sample_valuesこの列のサンプル値（ある場合）。ユーザーからの質問で参照される可能性のある値を追加します。
cortex_search_service_name列のリテラル値を検索するCortex Search Serviceの名前。サービス名と
sample_valuesの両方が指定されている場合、sample_valuesフィールドの値は無視されます。
時間ディメンション¶
時間ディメンションは、sale_date、created_at、yearなどの時間値を記述します。以下のフィールドがあります。
必須
nameこの時間ディメンションの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
exprこの列の SQL 式。これは物理列への参照、またはベーステーブルの1つ以上の列を持つ SQL である可能性があります。
data_typeこの時間ディメンションのデータ型。Snowflakeの全データ型の概要については、 SQL データ型リファレンス をご参照ください。なお、
VARIANT、OBJECT、GEOGRAPHY、ARRAYは現在サポートされていません。
オプション（推奨）
synonymsこの時間ディメンションを参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。
descriptionどのようなデータを持っているかなど、このディメンションの簡単な説明。このテーブルを使用してクエリを作成する際に役立つ情報を提供します。例えば、 DATETIME 列の場合、データのタイムゾーンを指定します。
unique:この列が一意な値を持つことを示すブール値。
sample_values:この列のサンプル値（ある場合）。ユーザーの質問で参照される可能性のある値を追加します。このフィールドはオプションです。
測定¶
測定とは、収益、印象、給与などの数値を表すものです。以下のフィールドがあります。
必須
nameこの測定の説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
exprこの列の SQL 式。これは物理列への参照、またはベーステーブルの1つ以上の列を持つ SQL である可能性があります。
data_typeこの測定のデータ型。Snowflakeの全データ型の概要については、 SQL データ型リファレンス をご参照ください。なお、
VARIANT、OBJECT、GEOGRAPHY、ARRAYは現在サポートされていません。
オプション（推奨）
synonymsこの測定を参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。
descriptionこの列がどのようなデータを持っているかなど、この測定に関する簡単な説明。
uniqueこの列が一意な値を持つことを示すブール値。
default_aggregationグループ化のコンテキストでこの列に適用されるデフォルトの集計。値の例としては、sum、avg、min、max、median、count、count_distinctなどがあります。
sample_valuesこの列のサンプル値（ある場合）。ユーザーの質問で参照される可能性のある値を追加します。
フィルター¶
フィルターは、フィルタリングに使われる SQL 式を表します。以下のフィールドがあります。
必須
nameこのフィルターの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
expr論理列を参照する、このフィルターの SQL 式。
オプション（推奨）
synonymsこのフィルターを参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。
descriptionこのフィルターが通常どのような用途に使われるかの詳細を含む、このフィルターに関する簡単な説明。
ベーステーブル¶
ベーステーブルは、完全修飾されたテーブル名を表すために使用されます。これは、論理テーブルがマッピングされる物理テーブルです。以下のフィールドがあります。
必須
databaseデータベースの名前。
schemaスキーマの名前。
tableテーブルの名前。
検証済みクエリ¶
YAML ファイルのこのセクションの目的と構造については、 Cortex Analyst 検証済みクエリリポジトリ をご参照ください。
YAML の例¶
このセクションでは、セマンティックモデル YAML の例を示します。
この例では、スキーマに以下のテーブルがあることを想定しています。
CREATE TABLE sales.public.sd_data (
id INT PRIMARY KEY,
dt DATETIME,
cat VARCHAR(255),
loc VARCHAR(255),
cntry VARCHAR(255),
chn VARCHAR(50),
amt DECIMAL(10, 2),
unts INT,
cst DECIMAL(10, 2)
);
このテーブルには暗号化された列名があり、列に関するセマンティック情報はあまりありません。以下は、このテーブルに関するセマンティック情報を提供するセマンティックモデル YAML です。
# Name and description of the semantic model.
name: Sales Data
description: This semantic model can be used for asking questions over the sales data.
# A semantic model can contain one or more tables.
tables:
# A logical table on top of the 'sd_data' base table.
- name: sales_data
description: A logical table capturing daily sales information across different store locations and product categories.
# The fully qualified name of the base table.
base_table:
database: sales
schema: public
table: sd_data
# Dimension columns in the logical table.
dimensions:
- name: product_category
synonyms:
- "item_category"
- "product_type"
description: The category of the product sold.
expr: cat
data_type: NUMBER
unique: false
sample_values:
- "501"
- "544"
- name: store_country
description: The country where the sale took place.
expr: cntry
data_type: TEXT
unique: false
sample_values:
- "USA"
- "GBR"
- name: sales_channel
synonyms:
- "channel"
- "distribution_channel"
description: The channel through which the sale was made.
expr: chn
data_type: TEXT
unique: false
sample_values:
- "FB"
- "GOOGLE"
# 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: sales_amount
synonyms:
- "revenue"
- "total_sales"
description: The total amount of money generated from the sale.
expr: amt
data_type: NUMBER
default_aggregation: sum
- name: sales_tax
description: The sales tax paid for this sale.
expr: amt * 0.0975
data_type: NUMBER
default_aggregation: sum
- name: units_sold
synonyms:
- "quantity_sold"
- "number_of_units"
description: The number of units sold in the transaction.
expr: unts
data_type: NUMBER
default_aggregation: sum
- name: cost
description: The cost of the product sold.
expr: cst
data_type: NUMBER
default_aggregation: sum
- name: profit
synonyms:
- "earnings"
- "net income"
description: The profit generated from a sale.
expr: amt - cst
data_type: NUMBER
default_aggregation: sum
# A table can define commonly used filters over it. These filters can then be referenced in user questions directly.
filters:
- name: north_america
synonyms:
- "North America"
- "N.A."
- "NA"
description: "A filter to restrict only to north american countries"
expr: cntry IN ('canada', 'mexico', 'usa')