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

Copy

ディメンション は、製品、顧客、または場所情報など、ファクトにコンテキストを提供するカテゴリ データを表します。ディメンションには通常、製品名や顧客の住所など、説明的なテキスト値が含まれます。これらは、分析やレポートでファクトをフィルター、グループ化、ラベル付けするために使用されます。

時間ディメンション は、異なる期間にわたる事実を分析するための時間的コンテクストを提供します。特定の時間間隔（日付、月、年）でメトリックを追跡し、トレンドの特定や期間比較などの分析をサポートします。

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

Copy

ファクト は、分析の背景となる測定可能で定量的なデータです。ファクトは、売上、コスト、数量など、ビジネスプロセスに関連する数値を表します。ファクトは、集約されていない行レベルの概念です。

# 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

Copy

フィルター は、期間、場所、カテゴリなどの条件に基づいて、クエリ結果を特定のデータサブセットに制限する条件です。

- 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')

Copy

メトリック は、ビジネスパフォーマンスの定量的な指標で、通常、複数の行にまたがる事実を集計して算出されます。メトリックは、 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)

Copy

許可されたリファレンス¶

ディメンション、ファクト、メトリック、またはフィルターの式はリファレンスできます。

• 自身のベーステーブルからの物理列

• 同じ論理テーブル内の論理列

• セマンティックモデル内の他の論理テーブルからの論理列

注釈

式は他の物理テーブルの物理列をリファレンスできません。

モデル・レベルの概念¶

リレーションシップは、共有キーの結合によって論理テーブルを接続します。例えば、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 ファイルをご参照ください。

セマンティックモデル¶

セマンティックモデルはテーブルの集まりを表します。モデルにはテーブルの説明が含まれており、各テーブルにはテーブルの特定の側面に関する説明が含まれています。モデルに記述された各テーブルは、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

この列のサンプル値（ある場合）。ユーザーの質問で参照される可能性のある値を追加します。

is_enum

ブール値。True の場合、 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 は廃止されました。

時間ディメンション¶

時間ディメンションは、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 式。これは、同じ論理テーブルの論理列 (ファクト、ディメンション、または時間ディメンション)、またはセマンティック・モデル内の別の論理テーブルの論理列を参照できます。

オプション

これらのフィールドは必須ではありませんが、可能な限り含めるようにしてください。

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 のカスタム手順 を参照してください。