Cortex Analyst セマンティックモデル仕様¶
なぜセマンティックモデルを使用する理由¶
Cortex Analyst では、ユーザーは自然言語を使用して Snowflake データをクエリできます。しかし、ビジネスユーザーはスキーマと互換性のない言語を使うことがよくあります。ユーザーは質問の中でドメイン固有のビジネス用語を指定しますが、基になるデータは技術的な略語を使って保存されることがよくあります。例えば、 "CUST" は顧客に対してよく使われます。この断絶は、スキーマのセマンティック的文脈の欠如と相まって、 Cortex Analyst に正確な回答を提供することを困難にしています。
セマンティックモデルは、ビジネス用語をデータベーススキーマにマッピングし、文脈上の意味を追加します。例えば、ユーザーが「先月の総収入」について質問した場合、セマンティックモデルは「収入」を純収入と定義し、「先月」を前の暦月と定義することができます。このマッピングは、 Cortex Analyst にとって、ユーザーの意図を理解し、正確な回答を提供するのに役立ちます。
注釈
セマンティックモデルは メタデータ と考えられています。
主な概念¶
注釈
このトピックでは、データベースの成果物は「物理的」オブジェクトと呼ばれ、セマンティックモデルの成果物は「論理的」オブジェクトと呼ばれます。
セマンティックモデルの構造と概念はデータベーススキーマと似ていますが、セマンティックモデルによってデータに関するより多くのセマンティック情報を提供することができます。
セマンティック層の概念¶
論理的セマンティック層を定義する構造と概念は、物理的データベース層を定義する構造と類似しています。セマンティック層のコンセプトタイプは以下の通りです。
論理テーブルレベル
モデル・レベル
追加コンテキスト

論理テーブルレベルの概念¶
論理テーブル は、Snowflake のセマンティックモデルの基本概念です。物理データベーステーブルまたはビューを表します。これは通常、ビジネスエンティティ(顧客、注文、サプライヤーなど)やディメンション(場所や時間など)に対応します。論理テーブルの各行は、通常、顧客 ID のようなエンティティの一意なインスタンスを表します。
論理テーブルには以下のような列があります。
ファクト(ビジネスイベントに関する定量データ)
ディメンション(誰が、何を、どこで、どのように)
時間(イベントが発生した時間)
論理テーブルに関連付けられたフィルターにより、クエリ結果を特定のデータ・サブセットに制限することができます。
集約や他の論理オブジェクトの組み合わせを使用して、メトリックを定義できます。
以下の例では、 LINEITEM ファクト・テーブルを含む TPC-H スキーマ を使用しています。YAML の完全な実装については、 snow_tpch
ファイルをダウンロードしてください。

以下の論理テーブルレベルの例はすべて、 order_lineitems
論理テーブルに属します。
tables:
- name: order_lineitems
description: >
The order line items table contains detailed information about each item within an
order, including quantities, pricing, and dates.
base_table:
database: SNOWFLAKE_SAMPLE_DATA
schema: TPCH_SF1
table: LINEITEM
primary_key:
columns:
- order_key
- order_lineitem_number
ディメンション は、製品、顧客、または場所情報など、ファクトにコンテキストを提供するカテゴリ データを表します。ディメンションには通常、製品名や顧客の住所など、説明的なテキスト値が含まれます。これらは、分析やレポートでファクトをフィルター、グループ化、ラベル付けするために使用されます。
時間ディメンション は、異なる期間にわたる事実を分析するための時間的コンテクストを提供します。特定の時間間隔(日付、月、年)でメトリックを追跡し、トレンドの特定や期間比較などの分析をサポートします。
time_dimensions:
- name: shipment_duration
synonyms:
- "shipping time"
- "shipment time"
description: The time it takes for items to be shipped.
expr: DATEDIFF(day, lineitem.L_SHIPDATE, lineitem.L_RECEIPTDATE)
data_type: NUMBER
unique: false
ファクト は、分析の背景となる測定可能で定量的なデータです。ファクトは、売上、コスト、数量など、ビジネスプロセスに関連する数値を表します。ファクトは、集約されていない行レベルの概念です。
# Fact columns in the logical table.
facts:
- name: net_revenue
synonyms:
- "revenue after discount"
- "net sales"
description: Net revenue after applying discounts.
expr: lineitem.L_EXTENDEDPRICE * (1 - lineitem.L_DISCOUNT)
data_type: NUMBER
フィルター は、期間、場所、カテゴリなどの条件に基づいて、クエリ結果を特定のデータサブセットに制限する条件です。
- name: north_america
synonyms:
- "NA"
- "North America region"
description: >
Filter to restrict data to orders from North America.
comments: Used for analysis focusing on North American customers.
expr: nation.N_NAME IN ('Canada', 'Mexico', 'United States')
メトリック は、ビジネスパフォーマンスの定量的な指標で、通常、複数の行にまたがる事実を集計して算出されます。メトリックは、 SUM() や AVG() のように、複数の論理オブジェクトと集約関数を組み合わせることができる SQL 式として表現します。メトリックは、レポートやダッシュボードでキー・パフォーマンス・インジケータ (KPIs) として使用できます。より高いレベルで集計するために、最も細かいレベルでメトリックを定義します。例えば、顧客、サプライヤー、リージョンごとに集計できるように、行項目レベルでtotal_revenueを定義します。
metrics:
# Simple metric referencing objects from the same logical table
- name: total_revenue
expr: SUM(lineitem.l_extendedprice * (1 - lineitem.l_discount))
# Complex metric referencing objects from multiple logical tables.
# The relationships between tables have been defined below.
- name: total_profit_margin
description: >
The profit margin from orders. This metric is not additive
and should always be calculated directly from the base tables.
expr: (SUM(order_lineitems.net_revenue) -
SUM(part_suppliers.part_supplier_cost * order_lineitems.lineitem_quantity))
/ SUM(order_lineitems.net_revenue)
許可されたリファレンス¶
ディメンション、ファクト、メトリック、またはフィルターの式はリファレンスできます。
自身のベーステーブルからの物理列
同じ論理テーブル内の論理列
セマンティックモデル内の他の論理テーブルからの論理列
注釈
式は他の物理テーブルの物理列をリファレンスできません。
モデル・レベルの概念¶
リレーションシップは、共有キーの結合によって論理テーブルを接続します。例えば、customerテーブルとordersテーブルの間に、customer_id列のjoinによるリレーションシップがあるとします。結合を使用して、顧客属性を持つ注文データを分析することができます。
relationships:
# Relationship between orders and lineitems
- name: order_lineitems_to_orders
left_table: order_lineitems
right_table: orders
relationship_columns:
- left_column: order_key
right_column: order_key
join_type: left_outer
relationship_type: many_to_one
# Relationship between lineitems and partsuppliers
- name: order_lineitems_to_part_suppliers
left_table: order_lineitems
right_table: part_suppliers
# The relationship requires equality of multiple columns from each table
relationship_columns:
- left_column: part_key
right_column: part_key
- left_column: supplier_key
right_column: supplier_key
join_type: left_outer
relationship_type: many_to_one
検証済みクエリ リポジトリ (VQR) は、正しいことが検証された質問と対応する SQL クエリのコレクションです。クエリを使用して、 Cortex Analyst の結果の精度を向上させることができます。
Cortex Analyst のカスタム手順 を使用すると、 Cortex Analyst の SQL のクエリ生成をより細かく制御することができます。カスタム指示の中で、 LLM にあなたのビジネスのユニークなコンテキストを提供します。
Cortex Analyst セマンティックモデルは YAML で指定されています。このモデルは、自然言語の質問に高い精度で答えるために必要なセマンティック情報を提供します。
YAML 形式¶
YAML は、人間にとっての読みやすさと正確さのバランスが取れています。ビジネスユーザーはそれを理解し、データエンジニアやアナリストは技術的な概念を明確に定義することができます。
Cortex Analyst セマンティックモデルの一般的な構文は次のとおりです。
# Name and description of the semantic model.
name: <name>
description: <string>
comments: <string>
# Logical table-level concepts
# 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:
service: <string>
literal_column: <string>
database: <string>
schema: <string>
is_enum: <boolean>
# 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>
# Fact columns in the logical table.
facts:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
data_type: <data type>
# Business metrics across logical objects
metrics:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
# Commonly used filters over the logical table.
filters:
- name: <name>
synonyms: <array of strings>
description: <string>
expr: <SQL expression>
# Model-level concepts
# Relationships between logical tables
relationships:
- name: <string>
left_table: <table>
right_table: <table>
relationship_columns:
- left_column: <column>
right_column: <column>
- left_column: <column>
right_column: <column>
join_type: <left_outer | inner>
relationship_type: < one_to_one | many_to_one>
# Additional context concepts
# Verified queries with 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
指定例については、 snow_tpch.yaml
ファイルをご参照ください。
モデルジェネレーターを使用してセマンティックモデルを作成する¶
テーブルからセマンティックモデルを作成するには、セマンティックモデルジェネレーターを使います。独自の YAML 仕様でセマンティックモデルを手動で作成する代わりに、 Snowsight 内のモデルジェネレーターを使用すると時間を節約できます。セマンティックモデルを作成するプロセスでは、以下を実行します。
モデルの基本情報を含む説明を提供します。
モデルの作成に使用するデータソースを提供します。少なくとも1つのテーブルまたはビューを提供する必要があります。
モデルを作成するために使用する列を選択します。
モデルの作成を開始するには、 Let's Create a Semantic Model ページに移動します。
Snowsight で、 AI & ML を選択します。
Cortex Analyst の横で Try を選択します。
Create new を選択します。
セマンティックモデルジェネレーターの説明ページが開きました。セマンティックモデルを作成するには、以下を実行します。
Description には、セマンティックモデルに関する情報を指定します。ファイル名、ファイルの場所、モデル名を入力する必要があります。データに関するコンテキストを含む説明を入力することもできます。
(オプション) User Questions には、ユーザーがデータについて質問できるタイプを指定します。モデルジェネレーターは、フィールドに入力された情報を使って、モデルを作成するために使用できるテーブル、ビュー、列を提案します。
Select Data (Table/View) には、セマンティックモデルの作成に使用するデータソースを入力します。少なくとも1つのテーブルまたはビューを提供する必要があります。指定できるテーブルやビューに制限はありませんが、セマンティックモデルに10個以上は使用しないことをお勧めします。
Select Columns には、セマンティックモデルの作成に使用する列を選択します。すべての列または特定の列を選択することができます。パフォーマンス上の理由から、50列以上は使用しないことをお勧めします。
モデルを作成したら、ステージに保存します。保存するには、画面右上の Save を選択します。さらに修正を加える必要がある場合は、 Snowsight を使用するか、 YAML ファイルを直接編集してモデルを編集することができます。
既存のセマンティックモデルを開く¶
セマンティックモデルを作成したら、 Snowsight で開くことができます。セマンティックモデルを開くには、以下を実行します。
Open semantic model を選択します。
Open を選択します。
Select from stage を選択します。
データベースとスキーマを選択します。
ダイアログボックスの外側をクリックします。
ファイルを保存したステージを選択します。
開く
を選択します。
注釈
ステージ内にセマンティックモデルが表示されない場合は、ページではなくモデルのリストを更新してみてください。
セマンティックモデル作成のヒント¶
YAML ファイルをビジネスドメインまたはトピックごとに整理する
YAML ファイルを特定のビジネスドメインやトピックに合わせて構成し、スコープを絞る。例えば、セールス分析とマーケティング分析のために別々のセマンティックモデルを作成する。
ターゲットオーディエンス、予想される質問、 KPIs、必要なデータに基づいてユースケースを調整する。よく定義されたユースケースは、より豊かなセマンティックモデルとより効果的なデータ検索につながる。
エンドユーザーの視点から考える
トピックについてユーザーが尋ねそうな主な質問を特定し、その質問に答えるために必要なテーブルと列のみを含める。
エンドユーザーが使用する語彙に近い名称や同義語を使用する。
DATETIME 列のタイムゾーンなど、初めてこのデータセットでクエリを書く人に役立つ重要な詳細を説明フィールドに含める。
複雑な計算をキャプチャする
より難しい、またはビジネス特有のクエリを表現に組み込む。
長いテーブルの代わりに幅の広いテーブルを使う
「metric」や「value」のような列を持つテーブルがある場合、各メトリックが列になるようにテーブルをフラット化する。このアプローチは、各メトリックに関するより多くのセマンティック情報をモデルに提供します。
自動生成された説明の確認
セマンティックモデルジェネレーター を使用している場合、テーブルと列の記述を自動的に生成しようとします。これらの記述が妥当かつ適切であることを常に確認し、必要に応じて修正します。
シンプルに開始して徐々に拡大する
十分にスコープされたセマンティックファイルは、より高い精度と正確な結果を保証します。少数のテーブルと列から開始し、より多くの種類の質問をカバーするためにセマンティックモデル YAML を徐々に拡張していきます。YAML 構築は継続的なプロセスであることを忘れてはなりません。
検証済みのクエリを含める
検証済みクエリリポジトリ (VQR)は、平易な英語の質問とそれに答えるクエリのコレクションであり、結果の正確性と信頼性を向上させるのに役立ちます。
既知の制限¶
Cortex Analyst は、 API の入力サイズを制限するために、セマンティックモデルファイルに1 MB のサイズ制限を課しています。
Cortex Analyst は、セマンティック YAML に追加されたサンプル値と検証済みクエリのインメモリ検索を実行します。すべてのサンプル値と検証済みクエリを削除した後、セマンティックモデルは32Kトークン(およそ4×32K文字、またはおよそ128 KB)を超えることはできません。セマンティックモデルジェネレーターの検証コマンドを使うことで、ファイルがこれらの制限内に収まるようにすることができます。より大きなコンテキストウィンドウを持つモデルのサポートが追加されるにつれて、制限は増えるかもしれません。
仕様¶
このセクションでは、前のセクションで説明したキーコンセプトの詳細な仕様を説明します。
セマンティックモデル¶
セマンティックモデルはテーブルの集まりを表します。モデルにはテーブルの説明が含まれており、各テーブルにはテーブルの特定の側面に関する説明が含まれています。モデルに記述された各テーブルは、Snowflakeの物理的なベーステーブルにマッピングされます。
以下のフィールドがあります。
必須
name
このセマンティックモデルの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
オプション
これらのフィールドは必須ではありませんが、可能な限り含めるようにしてください。
description
どのような分析に役立つかの詳細を含む、このセマンティックモデルについての説明。
tables
このセマンティックモデルの論理テーブルのリスト。
relationships
論理テーブル間の結合リスト。
論理テーブル¶
論理テーブルは、物理データベースのテーブルやビューに対する表示と考えることができます。以下のフィールドがあります。
必須
name
このテーブルの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
base_table
データベース内の基本ベーステーブルの完全修飾名。
オプション
これらのフィールドは必須ではありませんが、可能な限り含めるようにしてください。
synonyms
このテーブルを参照するために使用される他の用語/フレーズのリスト。論理テーブル内の同義語間で一意でなければなりません。
description
このテーブルの説明。
primary_key
このテーブルのプライマリキー列。リレーションシップを定義している場合は必須。
dimensions
このテーブルのディメンション列のリスト。
time_dimensions
このテーブルの時間ディメンション列のリスト。
facts
このテーブルのファクト列のリスト。
metrics
このテーブルのメトリックのリスト。
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
このディメンションに使用するCortex Search Serviceを指定します。以下のフィールドがあります。
service
: Cortex Search Serviceの名前。literal_column
: (オプション)リテラル値を含むCortex Search Serviceの列。database
: (オプション)Cortex Search Serviceがあるデータベース。デフォルトはbase_table
のデータベースです。schema
: (オプション)Cortex Search Serviceがあるスキーマ。デフォルトはbase_table
のスキーマです。
このフィールドは、名前しか指定できなかった
cortex_search_service_name
フィールドに取って代わるものです。cortex_search_service_name
は廃止されました。is_enum
ブール値。
True
の場合、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
:この列のサンプル値(ある場合)。ユーザーの質問で参照される可能性のある値を追加します。このフィールドはオプションです。
ファクト¶
ファクトは、収益、インプレッション、給与などの数値を表します。 Cortex Analyst の以前のリリースでは、ファクトはメジャーと呼ばれていました。ファクトは対策と下位互換です。以下のフィールドがあります。
必須
name
この事実を説明する名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
expr
この SQL 式は、同じ論理テーブルのベース物理テーブルの物理列、またはその論理テーブル内の論理列 (ファクト、 ディメンション、または時間ディメンション) のいずれかを参照できます。
data_type
このファクトのデータ・タイプ。Snowflakeの全データ型の概要については、 SQL データ型リファレンス をご参照ください。なお、
VARIANT
、OBJECT
、GEOGRAPHY
、ARRAY
は現在サポートされていません。
オプション)
これらのフィールドは必須ではありませんが、可能な限り含めるようにしてください。
synonyms
この測定を参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。
description
この列がどのようなデータを持っているかなど、この測定に関する簡単な説明。
unique
この列が一意な値を持つことを示すブール値。
sample_values
この列のサンプル値(ある場合)。ユーザーの質問で参照される可能性のある値を追加します。
フィルター¶
フィルターは、フィルタリングに使われる SQL 式を表します。以下のフィールドがあります。
必須
name
このフィルターの説明的な名前。
expr
論理列を参照する、このフィルターの SQL 式。
オプション
これらのフィールドは必須ではありませんが、可能な限り含めるようにしてください。
synonyms
このフィルターを参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。
description
このフィルターが通常どのような用途に使われるかの詳細を含む、このフィルターに関する簡単な説明。
メトリック¶
メトリックとは、総売上高、平均注文値、顧客数など、ビジネスのパフォーマンスを定量化できる尺度のことです。以下のフィールドがあります。
必須
name
このメトリックの説明的な名前。
一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。
expr
この列の SQL 式。これは、同じ論理テーブルの論理列 (ファクト、ディメンション、または時間ディメンション)、またはセマンティック・モデル内の別の論理テーブルの論理列を参照できます。
data_type
このメトリックのデータタイプ。Snowflakeのすべてのデータタイプの概要については、 SQL データタイプのリファレンスを参照してください。なお、
VARIANT
、OBJECT
、GEOGRAPHY
、ARRAY
は現在サポートされていません。
オプション
これらのフィールドは必須ではありませんが、可能な限り含めるようにしてください。
synonyms
このメトリックを参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべてのシノニムで一意でなければなりません。
description
この列がどのようなデータを持っているかなど、このメトリックの簡単な説明。
sample_values
この列のサンプル値(ある場合)。ユーザーの質問で参照される可能性のある値を追加します。
ベーステーブル¶
ベーステーブルは、完全修飾されたテーブル名を表すために使用されます。これは、論理テーブルがマッピングされる物理テーブルです。以下のフィールドがあります。
必須
database
データベースの名前。
schema
スキーマの名前。
table
テーブルの名前。
プライマリキー¶
プライマリキーは、テーブルの各行を一意に表す列を表します。テーブルがリレーションシップで使用される場合、プライマリキーは必須です。以下のフィールドがあります。
必須
columns
テーブルを一意に表すディメンション列のリスト。
リレーションシップ¶
論理テーブル間の結合関係を定義します。適切な結合関数を確保するためには、関係に関するテーブルに主キーを定義する必要があります。以下のフィールドがあります。
必須
name
関係の一意の識別子。
left_table
YAML ファイルで定義されている論理テーブル名。多対1のリレーションシップの場合、最適なパフォーマンスを得るためには、左側のテーブルをリレーションシップの多側にする必要があります。
right_table
YAML ファイルで定義されている論理テーブル名。多対1のリレーションシップの場合、最適なパフォーマンスを得るためには、右側のテーブルがリレーションシップの片側でなければなりません。
relationship_columns
結合パスを表す、左テーブルと右テーブルの列の等しいリスト。
join_type
left_outer
またはinner
のいずれか。relationship_type
many_to_one
またはone_to_one
のいずれか。
検証済みクエリ¶
YAML ファイルのこのセクションの目的と構造については、 Cortex Analyst 検証済みクエリリポジトリ をご参照ください。
カスタムの手順¶
カスタム命令については、 Cortex Analyst のカスタム手順 を参照してください。