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

ファクトは、 access_modifier フィールドを private_access に設定することで、プライベート（セマンティックモデルではアクセスできるが、エンドユーザーからはアクセス不可）にすることができます。デフォルトでは、ファクトはパブリック（ユーザーがアクセス可能）です。

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

- 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

メトリック は、 SQL 式で表される、ビジネスパフォーマンスの定量化可能な尺度です。メトリックは、レポートやダッシュボードで主要業績評価指標（KPIs）として使用できます。2種類のメトリックを計算できます。

• 通常のメトリック は、ファクト列について値を集約します（SUM や AVG などの関数を使用）。

• 派生メトリック は、加算や除算などの算術演算を使用して、既存のメトリックから計算されます。

より高いレベルで集約できるように、最も細かいレベルでメトリックを定義します。たとえば、 total_revenue を品目レベルで定義し、顧客別、サプライヤー別、地域別に集約できるようにします。

次の例は、2つの通常のメトリック計算を示しています。1つは単純で、もう1つはより複雑です。これらは table 定義の内部で定義されているため、その論理テーブルにスコープされます。

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

Tip

メトリックは、 access_modifier フィールドを private_access に設定することで、プライベート（セマンティックモデルではアクセスできるが、エンドユーザーからはアクセス不可）にすることができます。デフォルトでは、メトリックはパブリック（ユーザーがアクセス可能）です。

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

Expressions for dimensions, facts, filters, or regular table-scoped metrics can reference:

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

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

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

モデルスコープの派生メトリックは、セマンティックモデル内の任意の論理テーブルで定義されたメトリックや、他の派生メトリックを参照することができます。

注釈

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

モデル・レベルの概念¶

リレーションシップは、共有キーの結合によって論理テーブルを接続します。例えば、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>
        access_modifier: < public_access | private_access >  # Default is public_access

        expr: <SQL expression>
        data_type: <data type>


    # Regular metrics scoped to the logical table.
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: < public_access | private_access >  # Default is public_access

        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 >

# Derived metrics scoped to the semantic model
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    access_modifier: < public_access | private_access >  # Default is public_access

    expr: <SQL expression>


# Additional context concepts

#  Verified queries with example questions and queries that answer them
verified_queries:
  - 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 replaces the cortex_search_service_name field, which could only specify the name. cortex_search_service_name has been deprecated.

時間ディメンション¶

時間ディメンションは、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:

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

ファクト¶

A fact describes numerical values, such as revenue, impressions, and salary. Facts used to be called measures in earlier releases of Cortex Analyst. Facts are backward compatible with measures. Facts have the following fields:

必須

name

この事実を説明する名前。

一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。

expr

この SQL 式は、同じ論理テーブルのベース物理テーブルの物理列、またはその論理テーブル内の論理列 (ファクト、 ディメンション、または時間ディメンション) のいずれかを参照できます。

data_type

このファクトのデータ・タイプ。Snowflakeの全データ型の概要については、 SQL データ型リファレンス をご参照ください。なお、 VARIANT、 OBJECT、 GEOGRAPHY、 ARRAY は現在サポートされていません。

オプション

The following fields are not required, but should be included whenever possible.

synonyms

この測定を参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。

description

この列がどのようなデータを持っているかなど、この測定に関する簡単な説明。

unique

この列が一意な値を持つことを示すブール値。

sample_values

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

以下のフィールドはオプションです。これが含まれていない場合、デフォルトで public_access となります。

access_modifier

public_access または private_access のいずれか。private_access の場合、ファクトはセマンティックモデルではアクセスできますが、エンドユーザーからはアクセスできません。

フィルター¶

フィルターは、フィルタリングに使われる SQL 式を表します。以下のフィールドがあります。

必須

name

このフィルターの説明的な名前。

expr

論理列を参照する、このフィルターの SQL 式。

オプション

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

synonyms

このフィルターを参照するために使用されるその他の用語/フレーズのリスト。このセマンティックモデル内のすべての同義語で一意でなければなりません。

description

このフィルターが通常どのような用途に使われるかの詳細を含む、このフィルターに関する簡単な説明。

メトリック¶

A metric describes quantifiable measures of business performance, such as total revenue, average order value, or customer count. Metrics can be regular metrics or derived metrics.

• 通常のメトリック は、論理テーブルにスコープされ、同じ論理テーブル内の論理列（ファクト、ディメンション、 または時間ディメンション）、またはセマンティックモデル内の他の論理テーブルの論理列を参照できます。セマンティックモデルでは、 metric 要素は table 要素の中にあります。 通常のメトリックは、集約関数とウィンドウ関数を使用してテーブル全体の値を計算します。

• 派生メトリック は、セマンティックモデルにスコープされ、他のメトリックを組み合わせる方法を提供します。セマンティックモデルでは、 metric 要素は semantic_model 要素の中にあります。メトリックの式では、他のメトリック（他の派生メトリックを含む）のみを参照できます。

Metrics have the following fields.

必須

name

A descriptive name for this metric. This name deterines whether it is a regular metric.

一意でなければならず、 非引用識別子要件 に従わなければなりません。また、 Snowflakeの予約済みキーワード と競合することはありません。

expr

この列の SQL 式。式の形式は、メトリックが通常のメトリックか派生メトリックかによって異なります。

• Regular metrics, which are scoped to a table, reference a logical column (fact, dimension, or time dimension) in the same logical table or a logical column from another logical table in the semantic model and use aggregate or window functions to calculate overall values.

• 派生メトリックは、通常のメトリックや他の派生メトリックを参照できるスカラー式です。

オプション

The following fields are not required, but should be included whenever possible.

synonyms

A list of other terms/phrases used to refer to this metric. Each synonym must be unique across all synonyms in the semantic model.

description

この列がどのようなデータを持っているかなど、このメトリックの簡単な説明。

sample_values

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

以下のフィールドはオプションです。これが含まれていない場合、デフォルトで public_access となります。

access_modifier

public_access または private_access のいずれか。private_access の場合、メトリックはセマンティックモデルではアクセスできますが、エンドユーザーからはアクセスできません。

ベーステーブル¶

ベーステーブルは、完全修飾されたテーブル名を表すために使用されます。これは、論理テーブルがマッピングされる物理テーブルです。以下のフィールドがあります。

必須

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 検証済みクエリリポジトリ をご参照ください。

カスタムの手順¶

For information about custom instructions, see Cortex Analyst のカスタム手順.