SQL コマンドを使用したセマンティックビューの作成と管理

このトピックでは、次の SQL コマンドを使用して :doc:` セマンティックビュー <overview>` を作成、管理する方法について説明します。

また、次のストアドプロシージャと関数を呼び出して、:doc:`YAML仕様<semantic-view-yaml-spec>`からセマンティックビューを作成し、セマンティックビューの仕様を取得する方法についても説明します。

セマンティックビューの作成または置換に必要な権限

セマンティックビューを作成または置換するには、次の権限を持つロールを使用する必要があります。

  • CREATE SEMANTIC VIEW をセマンティックビューを作成するスキーマに追加します。

  • USAGE セマンティックビューを作成するデータベースとスキーマで、次のように設定します。

  • セマンティックビューで使用されるテーブルとビューに対する SELECT。

セマンティックビューのクエリに必要な権限については、 セマンティックビューのクエリに必要な権限 を参照してください。

CREATE SEMANTIC VIEWコマンドを使用したセマンティックビューの作成

セマンティックビューを作成するには、:doc:`/sql-reference/sql/create-semantic-view`コマンドを使用します。

注釈

YAML仕様<semantic-view-yaml-spec>`からセマンティックビューを作成するには、:doc:/sql-reference/stored-procedures/system_create_semantic_view_from_yaml`ストアドプロシージャを呼び出します。

セマンティックビューは有効でなければなりません。Snowflakeによるセマンティックビューの検証方法 をご参照ください。

次の例は、Snowflakeで利用可能な:doc:`TPC-Hサンプルデータ</user-guide/sample-data-tpch>`を使用しています。このデータセットには、顧客、注文、明細で個別のビジネスシナリオを表すテーブルが含まれています。

TPC-H サンプルデータで使用されているテーブルのデータモデリング。

この例では、 TPC-H データセットのテーブルを使用して、 tpch_rev_analysis という名前のセマンティックビューを作成しています。セマンティックビューは定義します。

  • 3つの論理テーブル(orders, customers, line_items)。

  • orders と customers テーブルのリレーションシップ。

  • line_items と orders テーブルのリレーションシップ。

  • メトリクスの計算に使用されるファクト。

  • 顧客名、注文日、注文年のディメンション。

  • 注文の平均値および注文の平均品目数に関するメトリクス。

CREATE SEMANTIC VIEW tpch_rev_analysis

  TABLES (
    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
      PRIMARY KEY (o_orderkey)
      WITH SYNONYMS ('sales orders')
      COMMENT = 'All orders table for the sales domain',
    customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
      PRIMARY KEY (c_custkey)
      COMMENT = 'Main table for customer data',
    line_items AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM
      PRIMARY KEY (l_orderkey, l_linenumber)
      COMMENT = 'Line items in orders'
  )

  RELATIONSHIPS (
    orders_to_customers AS
      orders (o_custkey) REFERENCES customers,
    line_item_to_orders AS
      line_items (l_orderkey) REFERENCES orders
  )

  FACTS (
    line_items.line_item_id AS CONCAT(l_orderkey, '-', l_linenumber),
    orders.count_line_items AS COUNT(line_items.line_item_id),
    line_items.discounted_price AS l_extendedprice * (1 - l_discount)
      COMMENT = 'Extended price after discount'
  )

  DIMENSIONS (
    customers.customer_name AS customers.c_name
      WITH SYNONYMS = ('customer name')
      COMMENT = 'Name of the customer',
    orders.order_date AS o_orderdate
      COMMENT = 'Date when the order was placed',
    orders.order_year AS YEAR(o_orderdate)
      COMMENT = 'Year when the order was placed'
  )

  METRICS (
    customers.customer_count AS COUNT(c_custkey)
      COMMENT = 'Count of number of customers',
    orders.order_average_value AS AVG(orders.o_totalprice)
      COMMENT = 'Average order value across all orders',
    orders.average_line_items_per_order AS AVG(orders.count_line_items)
      COMMENT = 'Average number of line items per order'
  )

  COMMENT = 'Semantic view for revenue analysis';

次のセクションでは、この例について詳しく説明します。

注釈

完全な例については、 SQL を使用してセマンティック表示を作成する例 をご参照ください。

論理テーブルの定義

CREATE SEMANTIC VIEW コマンドで、 TABLES 句を使用して、ビュー内の論理テーブルを定義します。この句では、次のことができます。

  • 物理テーブル名とオプションのエイリアスを指定します。

  • 論理テーブルの以下の列の識別子。

    • 主キーとなる列。

    • 一意な値を含む列（主キー列以外）。

    これらの列を使用して、このセマンティックビューでリレーションシップを定義することができます。

  • テーブルの同義語を追加します（発見性を高めるため）。

  • 説明的なコメントを添えてください。

先に示した の例では、、 TABLES 句は3つの論理テーブルを定義します。

  • TPC-H orders テーブルからのオーダー情報を含む orders テーブル。

  • TPC-H customers テーブルの顧客情報を含む customers テーブル。

  • TPC-H ``lineitem``テーブルの注文の明細を含む``line_items``テーブル。

この例では、 PRIMARYKEY 句を使用して、各論理テーブルの主キーとして使用される列を識別します。主キーと一意の値は、テーブル間の 関係 の種類（例: 多対1または1対1）を決定するのに役立ちます。

この例では、論理テーブルを説明する同義語やコメントもプロバイダーとして提供し、データを発見しやすくしています。

TABLES (
  orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
    PRIMARY KEY (o_orderkey)
    WITH SYNONYMS ('sales orders')
    COMMENT = 'All orders table for the sales domain',
  customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
    PRIMARY KEY (c_custkey)
    COMMENT = 'Main table for customer data',
  line_items AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM
    PRIMARY KEY (l_orderkey, l_linenumber)
    COMMENT = 'Line items in orders'
)

論理テーブル間のリレーションシップの識別子

:doc:`/sql-reference/sql/create-semantic-view`コマンドで、RELATIONSHIPS句を使用してビュー内のテーブル間の関係を識別します。関係ごとに、次を指定します。

  • リレーションシップのオプション名。

  • 外部キーを含む論理テーブルの名前。

  • 外部キーを定義するテーブルの列。

  • 一意な値を持つプライマリキーまたは列を含む論理テーブルの名前。

  • プライマリキーを定義する、あるいは一意な値を含むテーブルの列。

    • TABLES 句ですでに論理テーブルに PRIMARY KEY を指定している場合は、リレーションシップのプライマリキー列を指定する必要はありません。

    • TABLES 句に論理テーブルの UNIQUE キーワードが 1 つある場合、リレーションシップで対応する列を指定する必要はありません。

    また、 範囲で列を結合 したい場合は、日付、時間、タイムスタンプ、または数値列を指定することもできます。

先に紹介した 例 では、 RELATIONSHIPS 句で2つのリレーションシップを指定しています。

  • orders と customers テーブルのリレーションシップ。orders テーブルの o_custkey は、 customers テーブル (c_custkey) のプライマリキーを参照する外部キーです。

  • line_items と orders テーブルのリレーションシップ。line_items テーブルの l_orderkey は、 orders テーブル (o_orderkey) のプライマリキーを参照する外部キーです。

RELATIONSHIPS (
  orders_to_customers AS
    orders (o_custkey) REFERENCES customers (c_custkey),
  line_item_to_orders AS
    line_items (l_orderkey) REFERENCES orders (o_orderkey)
)

日付、時刻、タイムスタンプ、数値範囲を使用した論理テーブルの結合

デフォルトでは、2つの論理テーブル間の関係を指定すると、テーブルは等価条件で結合されます。

2つの論理テーブルを日付、時間、タイムスタンプ、数値範囲（一方のテーブルの列の値が他方のテーブルの列の値と同じ範囲にある必要がある）で結合する必要がある場合、 REFERENCES 句で列名と ASOF キーワードを指定できます。

RELATIONSHIPS(
  my_relationship AS
    logical_table_1(
      col_table_1
    )
    REFERENCES
    logical_table_2(
      ASOF col_table_2
    )
)

上記で定義されたセマンティックビューのクエリは、 MATCH_CONDITION 句で >= 比較演算子を使用する ASOF JOIN を作ります。これは、 col_table_1 の値が col_table_2 の値以上となるように、2つのテーブルを結合します。

...
FROM logical_table_1 ASOF JOIN logical_table_2
  MATCH_CONDITION(
    logical_table_1.col_table_1 >= logical_table_2.col_table_2
  )
...

注釈

MATCH_CONDITION 句では他の比較演算子はサポートされていません。

:ref:`ASOFJOIN<label-asof_join_data_types> で使用するのと同じ型 ` の列について、 ASOF キーワードを使用できます。

注釈

指定した関係の定義で指定できる ASOF キーワードは1つまでです。このキーワードは、リストのどの列の前でも指定できます。

例えば、顧客、顧客住所、注文データを含むテーブルがあるとします。

CREATE OR REPLACE TABLE customer(
  c_cust_id VARCHAR,
  c_first_name VARCHAR,
  c_last_name VARCHAR);

INSERT INTO customer VALUES
  ('cust001', 'Mary', 'Smith'),
  ('cust002', 'Bill', 'Wilson');

CREATE OR REPLACE TABLE customer_address(
  ca_cust_id VARCHAR,
  ca_zipcode VARCHAR,
  ca_street_addr VARCHAR,
  ca_start_date DATE,
  ca_end_date DATE
);

INSERT INTO customer_address VALUES
  ('cust001', '94025', '100 Main Street', '2024-01-01', '2024-03-31'),
  ('cust001', '94026', '200 Main Street', '2024-04-01', '2024-06-30'),
  ('cust001', '94027', '300 Main Street', '2024-07-01', NULL),
  ('cust002', '94028', '400 Main Street', '2024-01-01', '2024-04-30'),
  ('cust002', '94029', '500 Main Street', '2024-05-01', '2024-07-31'),
  ('cust002', '94030', '600 Main Street', '2024-08-01', NULL);

CREATE OR REPLACE TABLE orders(
  o_ord_id VARCHAR,
  o_cust_id VARCHAR,
  o_ord_date DATE,
  o_amount NUMBER
);

INSERT INTO orders VALUES
  ('ord100', 'cust001', '2024-02-01', 100),
  ('ord101', 'cust001', '2024-02-02', 200),
  ('ord102', 'cust001', '2024-05-01', 300),
  ('ord103', 'cust001', '2024-05-02', 400),
  ('ord104', 'cust001', '2024-08-01', 500),
  ('ord105', 'cust001', '2024-08-02', 600),
  ('ord106', 'cust002', '2024-03-01', 100),
  ('ord107', 'cust002', '2024-03-02', 200),
  ('ord108', 'cust002', '2024-06-01', 300),
  ('ord109', 'cust002', '2024-06-02', 400),
  ('ord110', 'cust002', '2024-09-01', 500),
  ('ord111', 'cust002', '2024-09-02', 600);

この例では、 customer_address テーブルの ca_start_date 列が、顧客が特定の住所に住み始めた時期を示しています。orders テーブルの o_ord_date 列は、注文の日付です。

顧客の注文に関する情報をクエリし、注文時に顧客が住んでいた場所に対応する郵便番号を取得できるようにしたいとします。

ca_start_date 列と o_ord_date 列の間の ASOF 結合を指定するセマンティックビューを定義できます。

CREATE OR REPLACE SEMANTIC VIEW customer_orders_view
  TABLES (
    customer_address UNIQUE (ca_cust_id, ca_start_date),
    customer UNIQUE (c_cust_id),
    orders UNIQUE (o_ord_id)
  )
  RELATIONSHIPS (
    customer_address(ca_cust_id) REFERENCES customer,
    -- Defines an ASOF JOIN on the date columns.
    orders(o_cust_id, o_ord_date)
      REFERENCES
        customer_address(ca_cust_id, ASOF ca_start_date)
  )
  FACTS (
    customer_address.f_zipcode AS ca_zipcode
  )
  DIMENSIONS (
    -- Relies on the ASOF join to retrieve the zip code
    -- where the order date is greater than or equal to
    -- the address starting date.
    orders.f_cust_zipcode AS customer_address.f_zipcode,
    orders.dim_year_month AS DATE_TRUNC('month', o_ord_date)
  )
  METRICS (
    orders.m_order_amount AS SUM(o_amount)
  );

郵便番号ごとの月あたりの注文金額合計を返すように、 このセマンティックビューにクエリ するとします。

SELECT * FROM SEMANTIC_VIEW(
  customer_orders_view
  DIMENSIONS orders.dim_year_month, orders.f_cust_zipcode
  METRICS orders.m_order_amount
);

+----------------+----------------+----------------+
| DIM_YEAR_MONTH | F_CUST_ZIPCODE | M_ORDER_AMOUNT |
|----------------+----------------+----------------|
| 2024-02-01     | 94025          |            300 |
| 2024-05-01     | 94026          |            700 |
| 2024-08-01     | 94027          |           1100 |
| 2024-03-01     | 94028          |            300 |
| 2024-09-01     | 94030          |           1100 |
| 2024-06-01     | 94029          |            700 |
+----------------+----------------+----------------+

このクエリでは、効果的に ASOF JOIN を使用して、注文日が居住開始日以降である日付列でテーブルを結合しています。

...
FROM orders ASOF JOIN customer_address
  MATCH_CONDITION(
    orders.o_ord_date >= customer_address.ca_start_date
  )
  ON
    orders.o_cust_id = customer_address.ca_cust_id
...

値の範囲を含む論理テーブルの結合

テーブルを、そのテーブルの可能な値の範囲を定義する別のテーブルと結合する場合、*範囲結合*を使用できます。たとえば、あるテーブルが販売注文を表し、注文が行われたタイムスタンプの列があるとします。別のテーブルが会計四半期を表し、それらの四半期を表す個別の時間範囲が含まれているとします。この2つのテーブルを結合するセマンティックビューを作成すると、注文の行にその注文が行われた会計四半期を含めることができます。

範囲を含むテーブルでは、各範囲が一意である必要があります。2つの範囲が重複してはいけません。

テーブルデータで、範囲の最小値または範囲の最大値を指定する場合は、NULLを使用します。

例えば、次のテーブルでは、重複しない時間範囲のセットを定義しています。

  • 最初の行は、2024年1月1日（同日は含まない）までのすべてを含む範囲をカバーします。

  • 最後の行は、2024年3月20日以降のすべてを含む範囲をカバーしています。

+----------------+------------------+-------------------------+-------------------------+
| TIME_PERIOD_ID | TIME_PERIOD_NAME | START_TIME              | END_TIME                |
|----------------+------------------+-------------------------+-------------------------|
|              1 | Before_January   | NULL                    | 2024-01-01 00:00:00.000 |
|              2 | Early_January    | 2024-01-01 00:00:00.000 | 2024-01-15 00:00:00.000 |
|              3 | Late_January     | 2024-01-15 00:00:00.000 | 2024-02-01 00:00:00.000 |
|              4 | Early_February   | 2024-02-01 00:00:00.000 | 2024-02-15 00:00:00.000 |
|              5 | Late_February    | 2024-02-15 00:00:00.000 | 2024-03-01 00:00:00.000 |
|              6 | Early_March      | 2024-03-01 00:00:00.000 | 2024-03-20 00:00:00.000 |
|              7 | After_March20    | 2024-03-20 00:00:00.000 | NULL                    |
+----------------+------------------+-------------------------+-------------------------+

注釈

2つの行の開始列にNULLを含めることはできず、2つの行の終了列にNULLを含めることはできません。

このような場合は、範囲結合クエリをサポートする:doc:`セマンティックビュー</user-guide/views-semantic/overview>`を設定できます。セマンティックビューを作成する際は、以下を実行する必要があります。

  1. 一定期間の開始時刻と終了時刻を含む論理テーブルの場合は、2つの範囲が重複しないことを指定する制約を定義します。

    :doc:`/sql-reference/sql/create-semantic-view`コマンドのTABLE句で、論理テーブル定義にCONSTRAINT句を指定します。構文について詳しくは、:ref:`CREATE SEMANTIC VIEWトピック<label-create_semantic_view_tables_constraint>のCONSTRAINTのドキュメント`を参照してください。

  2. あるテーブルのタイムスタンプを含む列と、もう1つのテーブルの開始時間列と終了時間列の関係を定義します。

    CREATE SEMANTIC VIEWコマンドのRELATIONSHIPS句で、BETWEEN句を使用して開始時刻と終了時刻を含む列を指定します。構文について詳しくは、:ref:`RELATIONSHIP CREATE SEMANTICトピックVIEWの<label-create_semantic_view_relationships>のドキュメント`を参照してください。

たとえば、``my_time_periods``テーブルが個別の期間を定義するとします。

CREATE OR REPLACE TABLE my_time_periods (
  time_period_id INT PRIMARY KEY,
  time_period_name VARCHAR(50),
  start_time TIMESTAMP,
  end_time TIMESTAMP
);

INSERT INTO my_time_periods (
    time_period_id, time_period_name, start_time, end_time
  ) VALUES
    (1, 'Before_January', NULL, '2024-01-01 00:00:00'::TIMESTAMP),
    (2, 'Early_January', '2024-01-01 00:00:00'::TIMESTAMP, '2024-01-15 00:00:00'::TIMESTAMP),
    (3, 'Late_January', '2024-01-15 00:00:00'::TIMESTAMP, '2024-02-01 00:00:00'::TIMESTAMP),
    (4, 'Early_February', '2024-02-01 00:00:00'::TIMESTAMP, '2024-02-15 00:00:00'::TIMESTAMP),
    (5, 'Late_February', '2024-02-15 00:00:00'::TIMESTAMP, '2024-03-01 00:00:00'::TIMESTAMP),
    (6, 'Early_March', '2024-03-01 00:00:00'::TIMESTAMP, '2024-03-20 00:00:00'::TIMESTAMP),
    (7, 'After_March20', '2024-03-20 00:00:00'::TIMESTAMP, NULL);

``my_events``テーブルが、これらの期間内に発生したイベントをキャプチャするとします。

CREATE OR REPLACE TABLE my_events (
  event_id INTEGER PRIMARY KEY,
  event_timestamp TIMESTAMP,
  event_name VARCHAR
);

INSERT INTO my_events (event_id, event_name, event_timestamp) VALUES
  (1, 'Login', '2024-01-15 10:00:00'::TIMESTAMP),
  (2, 'Purchase', '2024-01-15 14:30:00'::TIMESTAMP),
  (3, 'Logout', '2024-01-15 18:45:00'::TIMESTAMP),
  (4, 'Review', '2024-02-10 12:00:00'::TIMESTAMP),
  (5, 'Support', '2024-02-20 09:30:00'::TIMESTAMP),
  (6, 'Upgrade', '2024-03-05 16:00:00'::TIMESTAMP),
  (7, 'Feedback', '2024-03-25 11:00:00'::TIMESTAMP);

テーブルを結合するセマンティックビューを定義できます。``my_events``の行は``my_time_periods``の行と結合されます。ここでは、``my_events``の``event_timestamp``列の値が、``my_time_periods``の``start_time``および``end_time``列で指定された範囲内にあります。

CREATE OR REPLACE SEMANTIC VIEW my_semantic_view_range_join
  TABLES (
    my_events PRIMARY KEY (event_id),
    my_time_periods UNIQUE (start_time, end_time)
      CONSTRAINT my_time_period_range DISTINCT RANGE BETWEEN start_time AND end_time EXCLUSIVE
  )
  RELATIONSHIPS (
    my_time_periods_for_events AS
      my_events(event_timestamp) REFERENCES
        my_time_periods(BETWEEN start_time AND end_time EXCLUSIVE)
  )
  DIMENSIONS (
    my_events.dim_event_name AS event_name,
    my_events.dim_event_timestamp AS event_timestamp,
    my_time_periods.dim_time_period_name AS time_period_name
  )
  METRICS (
    my_events.m_event_count AS COUNT(*)
  );

次のクエリは、行がどのように結合されているかを示しています。

SELECT
    sv.dim_event_name,
    sv.dim_event_timestamp,
    sv.dim_time_period_name,
    sv.m_event_count
  FROM SEMANTIC_VIEW(
    my_semantic_view_range_join
    METRICS my_events.m_event_count
    DIMENSIONS
      my_events.dim_event_name,
      my_events.dim_event_timestamp,
      my_time_periods.dim_time_period_name
  ) AS sv
  ORDER BY
    sv.dim_event_timestamp,
    sv.dim_time_period_name;

+----------------+-------------------------+----------------------+---------------+
| DIM_EVENT_NAME | DIM_EVENT_TIMESTAMP     | DIM_TIME_PERIOD_NAME | M_EVENT_COUNT |
|----------------+-------------------------+----------------------+---------------|
| Login          | 2024-01-15 10:00:00.000 | Late_January         |             1 |
| Purchase       | 2024-01-15 14:30:00.000 | Late_January         |             1 |
| Logout         | 2024-01-15 18:45:00.000 | Late_January         |             1 |
| Review         | 2024-02-10 12:00:00.000 | Early_February       |             1 |
| Support        | 2024-02-20 09:30:00.000 | Late_February        |             1 |
| Upgrade        | 2024-03-05 16:00:00.000 | Early_March          |             1 |
| Feedback       | 2024-03-25 11:00:00.000 | After_March20        |             1 |
+----------------+-------------------------+----------------------+---------------+

例に示すように、結果の各行の``dim_time_period_name``ディメンションは、``dim_event_timestamp``ディメンションが該当する期間の名前です。

ファクト、ディメンション、メトリクスの定義

CREATE SEMANTIC VIEW コマンドでは、 FACTS、 DIMENSIONS、 METRICS 句を使用して、セマンティック・ビューのファクト、ディメンション、およびメトリクスを定義します。

セマンティックビューに、少なくとも 1 つのディメンションまたはメトリクスを定義する必要があります。

ファクト、ディメンション、またはメトリクスごとに指定します。

  • 所属する論理テーブル。

    注釈

    派生メトリック（1つの論理テーブルに固有ではないメトリック）を定義する場合は、論理テーブル名を省略する必要があります。派生メトリックの定義 をご参照ください。

  • ファクト、寸法、またはメトリクスの名前。

  • SQL 式で計算します。

    注釈

    ディメンションの場合、ディメンションに使用する Cortex Search Service を指定できます。詳細については、 Cortex Search Serviceを使用するディメンションの定義 をご参照ください。

  • 任意の同義語とコメント。

注釈

メトリックを特定のディメンションにまたがって集計しない場合は、それらのディメンションが*非加算*であることを指定する必要があります。

詳細については、 メトリックに対して非加算にすべきディメンションの特定 をご参照ください。

先に示した 例 では、いくつかのファクト、ディメンション、メトリクスを定義しています。

FACTS (
  line_items.line_item_id AS CONCAT(l_orderkey, '-', l_linenumber),
  orders.count_line_items AS COUNT(line_items.line_item_id),
  line_items.discounted_price AS l_extendedprice * (1 - l_discount)
    COMMENT = 'Extended price after discount'
)

DIMENSIONS (
  customers.customer_name AS customers.c_name
    WITH SYNONYMS = ('customer name')
    COMMENT = 'Name of the customer',
  orders.order_date AS o_orderdate
    COMMENT = 'Date when the order was placed',
  orders.order_year AS YEAR(o_orderdate)
    COMMENT = 'Year when the order was placed'
)

METRICS (
  customers.customer_count AS COUNT(c_custkey)
    COMMENT = 'Count of number of customers',
  orders.order_average_value AS AVG(orders.o_totalprice)
    COMMENT = 'Average order value across all orders',
  orders.average_line_items_per_order AS AVG(orders.count_line_items)
    COMMENT = 'Average number of line items per order'
)

注釈

ウィンドウ関数を使用するメトリックの定義に関する追加のガイドラインについては、 ウィンドウ関数メトリックの定義とクエリ をご覧ください。

Cortex Search Serviceを使用するディメンションの定義

Cortex Search Service を使用するディメンションを定義するには、Cortex Search Service の名前に WITH CORTEX SEARCH SERVICE 句を設定します。サービスが別のデータベースまたはスキーマにある場合、サービスの名前を修飾します。例:

DIMENSIONS (
  my_table.my_dimension AS my_dimension_expression
    WITH CORTEX SEARCH SERVICE my_db.my_schema.my_dimension_search_service
)

派生メトリックの定義

メトリックを定義するときは、メトリックが属する論理テーブルの名前を指定します。これは、メトリックが集約される論理テーブルです。

異なる論理テーブルのメトリックに基づいてメトリックを定義したい場合は、派生メトリック を定義できます。派生メトリックは、（特定の論理テーブルではなく）セマンティックビューを対象とするメトリックです。派生メトリックは、複数の論理テーブルのメトリックを組み合わせることができます。

派生メトリックの定義では、論理テーブル名を省略します。

たとえば、メトリック table_1.metric_1 および table_2.metric_2 の合計であるメトリック my_derived_metric_1 を定義したいとします。my_derived_metric_1 を定義するとき、論理テーブル名で名前を修飾しないでください。

CREATE SEMANTIC VIEW sv_with_derived_metrics
  TABLES (
    table_1 PRIMARY KEY (column_1),
    table_2 PRIMARY KEY (column_2)
  )
  ...
  METRICS (
    table_1.metric_1 AS SUM(...),
    table_2.metric_2 AS SUM(...),
    my_derived_metric_1 AS table_1.metric_1 + table_2.metric_2
  )
 ...

式では、他の派生メトリックを使用できます。例:

METRICS (
  ...
  my_derived_metric_1 AS table_1.metric_1 + table_2.metric_2,
  my_view_metric_2 AS my_derived_metric_1 + table_3.metric_3
)

派生メトリックを定義する場合は、以下の制限に注意してください。

  • 派生メトリックと通常のメトリックに同じ名前を使用することはできません。

  • 派生メトリックの式では、次を使用できます。

    • セマンティックビューの任意の論理テーブルで定義されたディメンションとファクトの集約。

    • セマンティックビューの任意の論理テーブルで定義されたメトリックのスカラー式。

    • その他の派生メトリック。

    次の例では、

    • derived_metric_1 は、2つのメトリックを持つスカラー式を使用します。

    • derived_metric_2 は、ディメンションの集約を使用します。

    • derived_metric_3 は、ディメンションの集約を別の派生メトリックに追加します。

    CREATE OR REPLACE SEMANTIC VIEW sv_derived_metrics
  TABLES (t1)
  DIMENSIONS (t1.dim1 AS t1.col1)
  METRICS (
    t1.m1 AS SUM(t1.col1),
    t2.m2 AS SUM(t1.col2),
    derived_metric_1 AS t1.m1 + t2.m2,
    derived_metric_2 AS SUM(t1.dim1),
    derived_metric_3 AS SUM(t1.dim1) + derived_metric_2
  )
  ...

  • 名前があいまいでない場合は、式内のメトリック、ディメンション、ファクトの名前を修飾する必要はありません。例:

    METRICS (
  table_1.metric_1 AS ...,
  table_1.my_unique_metric_name AS ...,
  table_2.metric_1 AS ...,
  my_derived_metric_1 AS table_1.metric_1 + my_unique_metric_name
)

    metric_1 という名前のメトリックが2つあるため、metric_1 は table_1 で修飾する必要がありますが、my_unique_metric_name は名前が一意であるため修飾する必要はありません。

  • 派生メトリックの式では、以下を使用できません。

    • メトリックの集約。

    • ウィンドウ関数。

    • 物理列への参照。

    • 集約されていないファクトまたはディメンションへの参照。

  • 通常のメトリック、ディメンション、またはファクトの式では、派生メトリックを使用することはできません。式で派生メトリックを使用できるのは、別の派生メトリックのみです。

複数の関係パスが存在する場合における、メトリックの関係の指定

場合によっては、セマンティックビューにある2つの特定の論理テーブル間に複数の関係パスが存在することがあります。このような場合、メトリックを定義するときに、使用する関係パスを指定する必要があります。

複数の関係パスの問題

フライトと空港に関する情報を含む2つのテーブルがあるとします。

CREATE OR REPLACE TABLE airports (
  airport_code VARCHAR PRIMARY KEY,
  city_name VARCHAR,
  airport_region_code VARCHAR
);

INSERT INTO airports VALUES
  ('SEA', 'Seattle', 'NA'),
  ('SFO', 'San Fransico', 'NA'),
  ('PVG', 'Shanghai', 'AS');

SELECT * FROM airports;

+--------------+--------------+---------------------+
| AIRPORT_CODE | CITY_NAME    | AIRPORT_REGION_CODE |
|--------------+--------------+---------------------|
| SEA          | Seattle      | NA                  |
| SFO          | San Fransico | NA                  |
| PVG          | Shanghai     | AS                  |
+--------------+--------------+---------------------+

CREATE OR REPLACE TABLE flights (
  flight_id INTEGER PRIMARY KEY,
  departure_airport VARCHAR,
  arrival_airport VARCHAR,
  is_late BOOLEAN,
  aircraft_id INTEGER,
  departure_time DATETIME,
  arrival_time DATETIME
);

INSERT INTO flights VALUES
  (1, 'SFO', 'SEA', true, 1, '2025-01-03 06:00:00', '2025-01-03 11:00:00'),
  (2, 'SEA', 'SFO', false, 2, '2025-01-03 11:00:00', '2025-01-03 16:00:00'),
  (3, 'SEA', 'PVG', false, 3, '2025-01-03 11:00:00', '2025-01-04 11:00:00'),
  (4, 'SFO', 'PVG', true, 1, '2025-01-03 06:00:00', '2025-01-04 11:00:00');

SELECT * FROM flights;

+-----------+-------------------+-----------------+---------+-------------+-------------------------+-------------------------+
| FLIGHT_ID | DEPARTURE_AIRPORT | ARRIVAL_AIRPORT | IS_LATE | AIRCRAFT_ID | DEPARTURE_TIME          | ARRIVAL_TIME            |
|-----------+-------------------+-----------------+---------+-------------+-------------------------+-------------------------|
|         1 | SFO               | SEA             | True    |           1 | 2025-01-03 06:00:00.000 | 2025-01-03 11:00:00.000 |
|         2 | SEA               | SFO             | False   |           2 | 2025-01-03 11:00:00.000 | 2025-01-03 16:00:00.000 |
|         3 | SEA               | PVG             | False   |           3 | 2025-01-03 11:00:00.000 | 2025-01-04 11:00:00.000 |
|         4 | SFO               | PVG             | True    |           1 | 2025-01-03 06:00:00.000 | 2025-01-04 11:00:00.000 |
+-----------+-------------------+-----------------+---------+-------------+-------------------------+-------------------------+

特定の都市から出発し、特定の年に到着する、フライトの総数に関する情報を提供するセマンティックビューを定義するとします。

CREATE OR REPLACE SEMANTIC VIEW flights_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code)
  ) DIMENSIONS (
    airports.city_name AS city_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id)
  );

セマンティックビューは、flights``テーブルと``airports``テーブル間の2つの異なる関係（``flight_departure_airport``と``flight_arrival_airport）を指定します。テーブル間には複数の関係パスがあるため、``m_flight_count``メトリックをクエリして``airports.city_name``ディメンション（または``airports``テーブルの任意のディメンション）を選択しようとすると失敗します。

SELECT * FROM SEMANTIC_VIEW (
  flights_sv
  METRICS flights.m_flight_count
  DIMENSIONS airports.city_name
);

010246 (42601): SQL compilation error:
Invalid dimension specified: Multi-path relationship between the dimension entity 'AIRPORTS'
  and the base metric or dimension entity 'FLIGHTS' is not supported.

``flights``テーブルと``airports``テーブルの間には複数のパスがあるため、クエリは失敗します。クエリが``airports``テーブルからディメンションを選択しなかった場合、クエリは成功していました。

使用する関係の指定

:doc:`/sql-reference/sql/create-semantic-view`コマンドのメトリック定義では、USING句で使用する関係を指定できます。

METRICS (
  <table_alias>.<metric>
    [ USING ( <relationship_name> [ , ... ] )
    AS <sql_expr>
  [ , ... ]
)

注釈

  • 指定する各関係は、メトリックを含む論理テーブルから始まる必要があります。たとえば、次のように指定するとします。

    METRICS (
  table_a.metric_a
    USING ( table_a_to_table_b )
    ...

    関係``table_a_to_table_b``は``table_a``から開始する必要があります。

    RELATIONSHIPS (
  table_a_to_table_b AS table_a(col_1) REFERENCES table_b(col_1)
  ...

  • 関係のシーケンスを指定することはできません（例：table_a_to_table_b``および``table_b_to_table_c）。各関係は、メトリックを含む論理テーブルから始まる必要があります。

  • メトリックを含む論理テーブルから異なるテーブルへの関係を識別する必要がある場合は、USING句で関係を指定できます。たとえば、``table_a``から``table_b``へ、および``table_a``から``table_c``への特定の関係によってメトリックを計算するとします。この場合、USING句で両方の関係を指定します。

    METRICS (
  table_a.metric_a
    USING ( table_a_to_table_b, table_a_to_table_c )
    ...

  • :ref:`派生メトリック<label-semantic_views_create_derived_metrics>`ではUSING句を指定できません。

たとえば、次のステートメントは、特定の関係を使用する2つの追加メトリックを定義します。

  • flight_departure_airport``関係を使用する``m_flight_departure_count。

  • flight_arrival_airport``関係を使用する``m_flight_arrival_count。

CREATE OR REPLACE SEMANTIC VIEW flights_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code)
  ) DIMENSIONS (
    airports.city_name AS city_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport) AS flights.m_flight_count
  );

このビューをクエリする際に、特定の関係を使用する、2つの新しいメトリックを指定できます。

SELECT * FROM SEMANTIC_VIEW (
  flights_sv
  METRICS flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS airports.city_name
);

+------------------------+--------------------------+--------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | CITY_NAME    |
|------------------------+--------------------------+--------------|
|                      1 |                        2 | San Fransico |
|                      1 |                        2 | Seattle      |
|                      2 |                     NULL | Shanghai     |
+------------------------+--------------------------+--------------+

同じ関係に依存するディメンションの追加

前の例のクエリでは、関係の基になる``airports``論理テーブルにある``airports.city_name``ディメンションを使用しました。

別の論理テーブルのディメンションをビューに追加すると、そのディメンションを使用したクエリでも、以前に指定した関係が有効に機能します。

たとえば、``airports``テーブルの``airport_region_code``列で指定された空港の地域に関する追加情報を含む、``regions``という名前のテーブルを作成するとします。

CREATE OR REPLACE TABLE regions (
  region_code VARCHAR PRIMARY KEY,
  region_name VARCHAR
);

INSERT INTO regions VALUES
  ('NA', 'North America'),
  ('AS', 'Asia');

SELECT * FROM regions;

+-------------+---------------+
| REGION_CODE | REGION_NAME   |
|-------------+---------------|
| NA          | North America |
| AS          | Asia          |
+-------------+---------------+

以前に定義したセマンティックビューを拡張して、地域名を返すことができます。

  • ``regions``テーブルの新しい論理テーブルを追加します。

  • ``regions``テーブルと``airports``テーブル間の関係を追加します。

  • 地域名のディメンションを追加します。

``regions``テーブルと``airports``テーブルの間には単一の関係があるため、メトリックのUSING句に追加の変更を加える必要はありません。

CREATE OR REPLACE SEMANTIC VIEW flights_by_regions_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code),
    regions PRIMARY KEY (region_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code),
    airport_region AS airports(airport_region_code) REFERENCES regions(region_code)
  ) DIMENSIONS (
    airports.city_name AS city_name,
    regions.region_name AS region_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport) AS flights.m_flight_count
  );

``region_name``ディメンションを指定してビューをクエリし、どの関係を使用するかについてあいまいな場合、USING句が使用する関係を決定します。

SELECT * FROM SEMANTIC_VIEW (
  flights_by_regions_sv
  METRICS flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS regions.region_name
);

+------------------------+--------------------------+---------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | REGION_NAME   |
|------------------------+--------------------------+---------------|
|                      2 |                        4 | North America |
|                      2 |                     NULL | Asia          |
+------------------------+--------------------------+---------------+

異なるテーブルとの関係の指定

セマンティックビューが複数のテーブルのディメンションを使用し、これらのディメンションに使用する関係を指定する必要がある場合は、USING句で複数の関係を指定できます。

たとえば、``airports``テーブルの空港の気象情報を含む、``weather``という名前のテーブルを作成するとします。

CREATE OR REPLACE TABLE weather (
  airport_code VARCHAR PRIMARY KEY,
  weather_condition VARCHAR,
  start_date DATETIME,
  end_date DATETIME
);

INSERT INTO weather VALUES
  ('SEA', 'rainy', '2025-01-01 10:00:00', '2025-01-01 12:00:00'),
  ('SEA', 'rainy', '2025-01-03 10:00:00', '2025-01-03 12:00:00'),
  ('SFO', 'sunny', '2025-01-03 05:00:00', '2025-01-03 09:00:00'),
  ('SFO', 'sunny', '2025-01-03 10:00:00', '2025-01-03 18:00:00'),
  ('PVG', 'cloudy', '2025-01-04 10:00:00', '2025-01-04 12:00:00');

SELECT * FROM weather;

+--------------+-------------------+-------------------------+-------------------------+
| AIRPORT_CODE | WEATHER_CONDITION | START_DATE              | END_DATE                |
|--------------+-------------------+-------------------------+-------------------------|
| SEA          | rainy             | 2025-01-01 10:00:00.000 | 2025-01-01 12:00:00.000 |
| SEA          | rainy             | 2025-01-03 10:00:00.000 | 2025-01-03 12:00:00.000 |
| SFO          | sunny             | 2025-01-03 05:00:00.000 | 2025-01-03 09:00:00.000 |
| SFO          | sunny             | 2025-01-03 10:00:00.000 | 2025-01-03 18:00:00.000 |
| PVG          | cloudy            | 2025-01-04 10:00:00.000 | 2025-01-04 12:00:00.000 |
+--------------+-------------------+-------------------------+-------------------------+

以前に定義したセマンティックビューを拡張して、気象情報を返すことができます。

  • ``weather``テーブルの新しい論理テーブルを追加します。

  • ``weather``テーブルと``flights``テーブルの間に2つの関係（1つは出発フライト用、もう1つは到着フライト用）を追加します。

  • 気象情報のディメンションを追加します。

  • メトリックが、``weather``テーブルと``flights``テーブル間の2つの新しい関係も使用するように指定します。

CREATE OR REPLACE SEMANTIC VIEW flights_and_weather_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code),
    weather PRIMARY KEY (airport_code, start_date, end_date)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code),
    flight_departure_weather AS flights(departure_airport, departure_time) REFERENCES weather(airport_code, BETWEEN start_date AND end_date EXCLUSIVE),
    flight_arrival_weather AS flights(arrival_airport, arrival_time) REFERENCES weather(airport_code, BETWEEN start_date AND end_date EXCLUSIVE)
  ) DIMENSIONS (
    airports.city_name AS city_name,
    weather.weather_condition AS weather_condition
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport, flight_departure_weather) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport, flight_arrival_weather) AS flights.m_flight_count
  );

ビューをクエリして``weather_condition``ディメンションを指定すると、USING句が使用される関係を決定します。

SELECT * FROM SEMANTIC_VIEW (
  flights_by_regions_sv
  METRICS flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS weather.weather_condition
);

+------------------------+--------------------------+-------------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | WEATHER_CONDITION |
|------------------------+--------------------------+-------------------|
|                      2 |                     NULL | cloudy            |
|                      1 |                        2 | sunny             |
|                      1 |                        2 | rainy             |
+------------------------+--------------------------+-------------------+

特定の関係を使用するメトリックに基づく派生メトリックの定義

:ref:`派生メトリック<label-semantic_views_create_derived_metrics>`ではUSING句を指定できませんが、USING句を指定するメトリックを使用する派生メトリックを定義できます。

例えば、次のセマンティックビューは2つの派生メトリックを定義します。

  • global_m_departure_arrival_ratio

  • global_m_departure_arrival_sum

これらの派生メトリックの定義では、``flights.m_flight_departure_count``および``flights.m_flight_arrival_count``メトリックを使用し、その両方ともUSING句を指定します。

CREATE OR REPLACE SEMANTIC VIEW flights_derived_metrics_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code)
  ) DIMENSIONS (
    airports.city_name AS city_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport) AS flights.m_flight_count,
    global_m_departure_arrival_ratio AS DIV0(flights.m_flight_departure_count, flights.m_flight_arrival_count),
    global_m_departure_arrival_sum AS flights.m_flight_departure_count + flights.m_flight_arrival_count
  );

SELECT * FROM SEMANTIC_VIEW (
  flights_derived_metrics_sv
  METRICS global_m_departure_arrival_ratio,
    flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS airports.city_name
);

+------------------------+--------------------------+----------------------------------+--------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | GLOBAL_M_DEPARTURE_ARRIVAL_RATIO | CITY_NAME    |
|------------------------+--------------------------+----------------------------------+--------------|
|                      1 |                        2 |                         2.000000 | Seattle      |
|                      1 |                        2 |                         2.000000 | San Fransico |
|                      2 |                     NULL |                             NULL | Shanghai     |
+------------------------+--------------------------+----------------------------------+--------------+

メトリックに対して非加算にすべきディメンションの特定

場合によっては、メトリックを特定のディメンションで集計すべきではない場合があります。このような場合は、ディメンションを*非加算*としてマークできます。

一部のディメンションでメトリックを集計する際の問題の理解

ある特定の日における、各顧客の当座預金と普通預金の残高を記載したテーブルがあるとします。

CREATE OR REPLACE TABLE bank_accounts (
  customer_id VARCHAR,
  account_type VARCHAR,
  year NUMBER,
  month NUMBER,
  day NUMBER,
  balance NUMBER
);

INSERT INTO bank_accounts VALUES
  ('cust-001', 'checking', 2024, 01, 01, 100),
  ('cust-001', 'savings', 2024, 01, 01, 110),
  ('cust-001', 'checking', 2024, 02, 10, 140),
  ('cust-001', 'savings', 2024, 02, 10, 150),
  ('cust-001', 'checking', 2024, 03, 15, 200),
  ('cust-001', 'savings', 2024, 03, 30, 210),
  ('cust-001', 'checking', 2025, 02, 15, 280),
  ('cust-001', 'savings', 2025, 02, 15, 290),
  ('cust-001', 'checking', 2025, 03, 20, 300),
  ('cust-001', 'savings', 2025, 03, 20, 310),
  ('cust-002', 'checking', 2025, 03, 30, 200),
  ('cust-002', 'savings', 2025, 03, 30, 310);

SELECT * FROM bank_accounts;

+-------------+--------------+------+-------+-----+---------+
| CUSTOMER_ID | ACCOUNT_TYPE | YEAR | MONTH | DAY | BALANCE |
|-------------+--------------+------+-------+-----+---------|
| cust-001    | checking     | 2024 |     1 |   1 |     100 |
| cust-001    | savings      | 2024 |     1 |   1 |     110 |
| cust-001    | checking     | 2024 |     2 |  10 |     140 |
| cust-001    | savings      | 2024 |     2 |  10 |     150 |
| cust-001    | checking     | 2024 |     3 |  15 |     200 |
| cust-001    | savings      | 2024 |     3 |  30 |     210 |
| cust-001    | checking     | 2025 |     2 |  15 |     280 |
| cust-001    | savings      | 2025 |     2 |  15 |     290 |
| cust-001    | checking     | 2025 |     3 |  20 |     300 |
| cust-001    | savings      | 2025 |     3 |  20 |     310 |
| cust-002    | checking     | 2025 |     3 |  30 |     200 |
| cust-002    | savings      | 2025 |     3 |  30 |     310 |
+-------------+--------------+------+-------+-----+---------+

次を含むセマンティックビューを定義するとします。

  • 次のディメンション。

    • カスタマー ID

    • 口座タイプ

    • Year

    • Month

    • 日

  • 残高合計のメトリック。

次のステートメントは、上記のディメンションとメトリックを含むセマンティックビューを作成します。

CREATE OR REPLACE SEMANTIC VIEW bank_accounts_sv
  TABLES (
    bank_accounts
  )
  DIMENSIONS (
    bank_accounts.customer_id_dim AS bank_accounts.customer_id,
    bank_accounts.account_type_dim AS bank_accounts.account_type,
    bank_accounts.year_dim AS bank_accounts.year,
    bank_accounts.month_dim AS bank_accounts.month,
    bank_accounts.day_dim AS bank_accounts.day
  )
  METRICS (
    bank_accounts.m_account_balance AS SUM(balance)
  );

毎年年末に各顧客の当座預金口座と普通預金口座の合計残高を取得したい場合は、セマンティックビューに``m_account_balance``メトリックをクエリし、``customer_id_dim``および``year_dim``ディメンションを指定できます。

ただし、メトリックは日付ディメンションによって集計されるため、``m_account_balance``メトリックは各顧客の各日の残高の合計になります。

SELECT * FROM SEMANTIC_VIEW(
    bank_accounts_sv
    METRICS bank_accounts.m_account_balance
    DIMENSIONS customer_id_dim, year_dim
  )
  ORDER BY customer_id_dim, year_dim;

+-------------------+-----------------+----------+
| M_ACCOUNT_BALANCE | CUSTOMER_ID_DIM | YEAR_DIM |
|-------------------+-----------------+----------|
|               910 | cust-001        |     2024 |
|              1180 | cust-001        |     2025 |
|               510 | cust-002        |     2025 |
+-------------------+-----------------+----------+

上記の例では、2024年の``cust-001``の場合、910``は各日の残高の合計（``100 + 110 + 140 + 150 + 200 + 210）です。

メトリックが特定のディメンションにまたがって集計されるのを防止する方法

メトリックが日付ディメンションによって集計されないようにするには、セマンティックビューを作成する際にNON ADDITIVE BY句で日付ディメンションを指定します。

CREATE OR REPLACE SEMANTIC VIEW bank_accounts_sv
  TABLES (
    bank_accounts
  )
  DIMENSIONS (
    bank_accounts.customer_id_dim AS bank_accounts.customer_id,
    bank_accounts.account_type_dim AS bank_accounts.account_type,
    bank_accounts.year_dim AS bank_accounts.year,
    bank_accounts.month_dim AS bank_accounts.month,
    bank_accounts.day_dim AS bank_accounts.day
  )
  METRICS (
    bank_accounts.m_account_balance
      NON ADDITIVE BY (year_dim, month_dim, day_dim)
      AS SUM(balance)
  );

注釈

  • メトリックでNON ADDITIVE BY句を指定した場合、派生していないメトリックの定義ではそのメトリックを参照することはできません。派生メトリックのみが、非加算ディメンションを指定するメトリックを参照できます。

NON ADDITIVE BY句を指定すると、メトリックは*半加算*メトリックになります。

このセマンティックビューをクエリすると、``m_account_balance``メトリックは日付ディメンションで集計されなくなります。クエリは、クエリされたディメンションのグループそれぞれで、期間終了時の口座残高を集計します。

SELECT * FROM SEMANTIC_VIEW(
    bank_accounts_sv
    METRICS bank_accounts.m_account_balance
    DIMENSIONS customer_id_dim, year_dim
  )
  ORDER BY customer_id_dim, year_dim;

+-------------------+-----------------+----------+
| M_ACCOUNT_BALANCE | CUSTOMER_ID_DIM | YEAR_DIM |
|-------------------+-----------------+----------|
|               210 | cust-001        |     2024 |
|               610 | cust-001        |     2025 |
|               510 | cust-002        |     2025 |
+-------------------+-----------------+----------+

上記の例では、2024年の``cust-001``の場合、``210``はデータを含むその年の最終日の当座預金口座と普通預金口座の残高の合計です。

  • データを含む2024年の最終日は``2024-03-30``です。

  • 当座預金口座にはその日付の行がないため、結果のメトリックは普通預金口座の残高（210）です。

別の例として、年末にすべての顧客の合計口座残高が必要な場合は、``year_dim``ディメンションを指定できます。

日付ディメンションは非加算としてマークされているため、クエリは各顧客の当座預金口座と普通預金口座の残高の期間終了時（日付ごと）の値を合計します。

SELECT * FROM SEMANTIC_VIEW(
    bank_accounts_sv
    METRICS bank_accounts.m_account_balance
    DIMENSIONS year_dim
  )
  ORDER BY year_dim;

+-------------------+----------+
| M_ACCOUNT_BALANCE | YEAR_DIM |
|-------------------+----------|
|               210 |     2024 |
|               510 |     2025 |
+-------------------+----------+

クエリ処理中に、行は非加算ディメンションでソートされ、最後の行（最新の値のスナップショット）の値がメトリックを計算するために集計されます。

注釈

行は非加算ディメンションでソートされるため、ディメンションを指定する順序が重要です。これは、:doc:`/sql-reference/constructs/order-by`句で列を指定する順序と似ています。

非加算ディメンションのソート順の指定

例で示されているように、メトリックは、期間の終了時に各顧客の当座預金と普通預金の残高の値を集計します。ソート順を変更する場合は、ディメンション名の横にASCまたはDESCキーワードを指定できます。例:

METRICS (
  bank_accounts.m_account_balance
    NON ADDITIVE BY (year_dim DESC, month_dim DESC, day_dim DESC)
    AS SUM(balance)
);

この例では、メトリックは``year_dim``、month_dim、および``day_dim``で指定された最も早い日付に評価されます。

ディメンションにNULL値が含まれる場合は、NULLS FIRSTまたはNULLS LASTキーワードを使用して、結果でNULL値を最初に並べ替えるか最後に並べ替えるかを指定できます。

METRICS (
  bank_accounts.m_account_balance
    NON ADDITIVE BY (
      year_dim DESC NULLS FIRST,
      month_dim DESC NULLS FIRST,
      day_dim DESC NULLS FIRST
    )
    AS SUM(balance)

ファクトやメトリックをプライベートとしてマークする

セマンティックビューの計算でのみ使用するためにファクトまたはメトリックを定義し、クエリでファクトまたはメトリックを返さないようにする場合は、ファクトまたはメトリックをプライベートとしてマークする PRIVATE キーワードを指定できます。例:

FACTS (
  PRIVATE my_private_fact AS ...
)

METRICS (
  PRIVATE my_private_metric AS ...
)

注釈

ディメンションをプライベートとしてマークすることはできません。ディメンションは常にパブリックです。

プライベートなファクトまたはメトリックを含むセマンティックビューをクエリする場合、以下の句でプライベートなファクトまたはメトリックを指定することはできません。

一部のコマンドと関数には、プライベートなファクトとメトリックが含まれます。

  • プライベートなファクトとメトリックは、/sql-reference/sql/desc-semantic-view`コマンドの出力に表示されます。プライベートなファクトとメトリックの行では、 ``access_modifier` 列に PRIVATE があります。

  • プライベートなファクトとメトリックは、label-semantic_views_get_ddl`に記載されているように、:doc:/sql-reference/functions/get_ddl`関数呼び出しの戻り値にリストされます。

一部のコマンドと関数には、特定の条件下でのみプライベートなファクトとメトリックが含まれます。

  • プライベートなファクトとメトリックは、:ref:`セマンティックビューに対してREFERENCESまたはOWNERSHIP権限が付与された<label-semantic_views_privileges>ロールを使用している場合にのみ、INFORMATION_SCHEMAの:doc:`SEMANTIC_FACTS </sql-reference/info-schema/semantic_facts>`ビューと:doc:`SEMANTIC_METRICS </sql-reference/info-schema/semantic_metrics>`ビューにリストされます。

    それ以外の場合、これらのビューにはパブリックなファクトとメトリックのみがリストされます。

その他のコマンドや関数には、プライベートなファクトとメトリックは含まれません。

  • プライベートファクトは、SHOW SEMANTIC FACTS コマンドの出力には表示されません。

  • プライベートメトリックは、SHOW SEMANTIC METRICS コマンドの出力には表示されません。

Cortex Analyst のカスタム指示の提供

セマンティックビューでは、次の方法を説明する Cortex Analystの手順 を提供できます。

  • SQL ステートメントを生成する

  • 質問を分類し、追加情報の提供を促す

これらのカスタム指示を提供するには、以下の句を使用します。

  • SQL ステートメントを生成する方法については、 CREATE SEMANTIC VIEW コマンドの AI_SQL_GENERATION 句を使用してください。

    たとえば、すべての数値列が小数点2位に丸められるような SQL ステートメントを生成するように Cortex Analyst に指示するには、次のように指定します。

    CREATE SEMANTIC VIEW my_semantic_view
  ...
  -- Definitions of logical tables, relationships, dimensions, facts, and metrics
  ...
  AI_SQL_GENERATION 'Ensure that all numeric columns are rounded to 2 decimal points.'
  ...
  -- Additional clauses

  • 質問の分類方法については、 AI_QUESTION_CATEGORIZATION 句を使用します。

    たとえば、 Cortex Analyst にユーザーに関する質問を拒否するように指示するには、次のように指定します。

    CREATE SEMANTIC VIEW my_semantic_view
  ...
  -- Definitions of logical tables, relationships, dimensions, facts, and metrics
  ...
  AI_QUESTION_CATEGORIZATION 'Reject all questions asking about users. Ask users to contact their admin.'
  ...
  -- Additional clauses

    質問が明確でない場合は、詳細を要求する指示を提供することもできます。例:

    AI_QUESTION_CATEGORIZATION 'If the question asks for users without providing a product_type, consider this question UNCLEAR and ask the user to specify product_type.'

YAML仕様からセマンティックビューを作成する

YAML仕様<semantic-view-yaml-spec>`からセマンティックビューを作成するには、:doc:/sql-reference/stored-procedures/system_create_semantic_view_from_yaml`ストアドプロシージャを呼び出すことができます。

まず、YAML仕様からセマンティックビューを作成できることを確認するために、3番目の引数としてTRUEを渡します。

次の例では、YAML の特定のセマンティックモデル仕様を使用して、データベース my_db とスキーマ my_schema に tpch_analysis という名前のセマンティックビューを作成できることを確認します。

CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML(
  'my_db.my_schema',
  $$
  name: TPCH_REV_ANALYSIS
  description: Semantic view for revenue analysis
  tables:
    - name: CUSTOMERS
      description: Main table for customer data
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: CUSTOMER
      primary_key:
        columns:
          - C_CUSTKEY
      dimensions:
        - name: CUSTOMER_NAME
          synonyms:
            - customer name
          description: Name of the customer
          expr: customers.c_name
          data_type: VARCHAR(25)
        - name: C_CUSTKEY
          expr: C_CUSTKEY
          data_type: VARCHAR(134217728)
      metrics:
        - name: CUSTOMER_COUNT
          description: Count of number of customers
          expr: COUNT(c_custkey)
    - name: LINE_ITEMS
      description: Line items in orders
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: LINEITEM
      primary_key:
        columns:
          - L_ORDERKEY
          - L_LINENUMBER
      dimensions:
        - name: L_ORDERKEY
          expr: L_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: L_LINENUMBER
          expr: L_LINENUMBER
          data_type: VARCHAR(134217728)
      facts:
        - name: DISCOUNTED_PRICE
          description: Extended price after discount
          expr: l_extendedprice * (1 - l_discount)
          data_type: "NUMBER(25,4)"
        - name: LINE_ITEM_ID
          expr: "CONCAT(l_orderkey, '-', l_linenumber)"
          data_type: VARCHAR(134217728)
    - name: ORDERS
      synonyms:
        - sales orders
      description: All orders table for the sales domain
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: ORDERS
      primary_key:
        columns:
          - O_ORDERKEY
      dimensions:
        - name: ORDER_DATE
          description: Date when the order was placed
          expr: o_orderdate
          data_type: DATE
        - name: ORDER_YEAR
          description: Year when the order was placed
          expr: YEAR(o_orderdate)
          data_type: "NUMBER(4,0)"
        - name: O_ORDERKEY
          expr: O_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: O_CUSTKEY
          expr: O_CUSTKEY
          data_type: VARCHAR(134217728)
      facts:
        - name: COUNT_LINE_ITEMS
          expr: COUNT(line_items.line_item_id)
          data_type: "NUMBER(18,0)"
      metrics:
        - name: AVERAGE_LINE_ITEMS_PER_ORDER
          description: Average number of line items per order
          expr: AVG(orders.count_line_items)
        - name: ORDER_AVERAGE_VALUE
          description: Average order value across all orders
          expr: AVG(orders.o_totalprice)
  relationships:
    - name: LINE_ITEM_TO_ORDERS
      left_table: LINE_ITEMS
      right_table: ORDERS
      relationship_columns:
        - left_column: L_ORDERKEY
          right_column: O_ORDERKEY
      relationship_type: many_to_one
    - name: ORDERS_TO_CUSTOMERS
      left_table: ORDERS
      right_table: CUSTOMERS
      relationship_columns:
        - left_column: O_CUSTKEY
          right_column: C_CUSTKEY
      relationship_type: many_to_one
  $$,
TRUE);

仕様が有効な場合、ストアドプロシージャは以下のメッセージを返します。

+----------------------------------------------------------------------------------+
| SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML                                            |
|----------------------------------------------------------------------------------|
| YAML file is valid for creating a semantic view. No object has been created yet. |
+----------------------------------------------------------------------------------+

YAML 構文が無効な場合、ストアドプロシージャは例外をスローします。たとえば、コロンがない場合は

relationships
  - name: LINE_ITEM_TO_ORDERS

ストアドプロシージャは例外をスローし、YAML 構文が無効であることを示します。

392400 (22023): Uncaught exception of type 'EXPRESSION_ERROR' on line 3 at position 23 :
  Invalid semantic model YAML: while scanning a simple key
   in 'reader', line 90, column 3:
        relationships
        ^
  could not find expected ':'
   in 'reader', line 91, column 11:
          - name: LINE_ITEM_TO_ORDERS
                ^

仕様が存在しない物理テーブルを参照している場合、ストアドプロシージャは例外をスローします。

base_table:
  database: SNOWFLAKE_SAMPLE_DATA
  schema: TPCH_SF1
  table: NONEXISTENT

002003 (42S02): Uncaught exception of type 'EXPRESSION_ERROR' on line 3 at position 23 :
  SQL compilation error:
  Table 'SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.NONEXISTENT' does not exist or not authorized.

同様に、仕様が存在しない主キー列を参照している場合、ストアドプロシージャは例外をスローします。

primary_key:
  columns:
    - NONEXISTENT

000904 (42000): Uncaught exception of type 'EXPRESSION_ERROR' on line 3 at position 23 :
  SQL compilation error: error line 0 at position -1
  invalid identifier 'NONEXISTENT'

その後、3番目の引数を渡さずにストアドプロシージャを呼び出して、セマンティックビューを作成できます。

次の例では、データベース my_db とスキーマ my_schema に tpch_analysis という名前のセマンティックビューを作成します。

CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML(
  'my_db.my_schema',
  $$
  name: TPCH_REV_ANALYSIS
  description: Semantic view for revenue analysis
  tables:
    - name: CUSTOMERS
      description: Main table for customer data
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: CUSTOMER
      primary_key:
        columns:
          - C_CUSTKEY
      dimensions:
        - name: CUSTOMER_NAME
          synonyms:
            - customer name
          description: Name of the customer
          expr: customers.c_name
          data_type: VARCHAR(25)
        - name: C_CUSTKEY
          expr: C_CUSTKEY
          data_type: VARCHAR(134217728)
      metrics:
        - name: CUSTOMER_COUNT
          description: Count of number of customers
          expr: COUNT(c_custkey)
    - name: LINE_ITEMS
      description: Line items in orders
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: LINEITEM
      primary_key:
        columns:
          - L_ORDERKEY
          - L_LINENUMBER
      dimensions:
        - name: L_ORDERKEY
          expr: L_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: L_LINENUMBER
          expr: L_LINENUMBER
          data_type: VARCHAR(134217728)
      facts:
        - name: DISCOUNTED_PRICE
          description: Extended price after discount
          expr: l_extendedprice * (1 - l_discount)
          data_type: "NUMBER(25,4)"
        - name: LINE_ITEM_ID
          expr: "CONCAT(l_orderkey, '-', l_linenumber)"
          data_type: VARCHAR(134217728)
    - name: ORDERS
      synonyms:
        - sales orders
      description: All orders table for the sales domain
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: ORDERS
      primary_key:
        columns:
          - O_ORDERKEY
      dimensions:
        - name: ORDER_DATE
          description: Date when the order was placed
          expr: o_orderdate
          data_type: DATE
        - name: ORDER_YEAR
          description: Year when the order was placed
          expr: YEAR(o_orderdate)
          data_type: "NUMBER(4,0)"
        - name: O_ORDERKEY
          expr: O_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: O_CUSTKEY
          expr: O_CUSTKEY
          data_type: VARCHAR(134217728)
      facts:
        - name: COUNT_LINE_ITEMS
          expr: COUNT(line_items.line_item_id)
          data_type: "NUMBER(18,0)"
      metrics:
        - name: AVERAGE_LINE_ITEMS_PER_ORDER
          description: Average number of line items per order
          expr: AVG(orders.count_line_items)
        - name: ORDER_AVERAGE_VALUE
          description: Average order value across all orders
          expr: AVG(orders.o_totalprice)
  relationships:
    - name: LINE_ITEM_TO_ORDERS
      left_table: LINE_ITEMS
      right_table: ORDERS
      relationship_columns:
        - left_column: L_ORDERKEY
          right_column: O_ORDERKEY
      relationship_type: many_to_one
    - name: ORDERS_TO_CUSTOMERS
      left_table: ORDERS
      right_table: CUSTOMERS
      relationship_columns:
        - left_column: O_CUSTKEY
          right_column: C_CUSTKEY
      relationship_type: many_to_one
  $$
);

+-----------------------------------------+
| SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML   |
|-----------------------------------------|
| Semantic view was successfully created. |
+-----------------------------------------+

既存のセマンティックビューのコメントを変更する

既存のセマンティックビューのコメントを変更するには、ALTER SEMANTIC VIEW コマンドを実行します。例:

ALTER SEMANTIC VIEW my_semantic_view SET COMMENT = 'my comment';

注釈

コメント以外のプロパティを変更するのに、ALTERSEMANTICVIEW コマンドは使用できません。セマンティックビューの他のプロパティを変更するには、セマンティックビューを置き換えます。既存のセマンティックビューの置き換え をご参照ください。

COMMENT コマンドを使用してセマンティックビューのコメントを設定することもできます。

COMMENT ON SEMANTIC VIEW my_semantic_view IS 'my comment';

既存のセマンティックビューの置き換え

既存のセマンティックビューを置き換える（例えば、ビューの定義を変更する）には、 CREATE SEMANTIC VIEW を実行する際に OR REPLACE を指定します。既存のセマンティックビューで付与された権限を保持したい場合は、 COPY GRANTS を指定してください。例:

CREATE OR REPLACE SEMANTIC VIEW tpch_rev_analysis

  TABLES (
    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
      PRIMARY KEY (o_orderkey)
      WITH SYNONYMS ('sales orders')
      COMMENT = 'All orders table for the sales domain',
    customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
      PRIMARY KEY (c_custkey)
      COMMENT = 'Main table for customer data',
    line_items AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM
      PRIMARY KEY (l_orderkey, l_linenumber)
      COMMENT = 'Line items in orders'
  )

  RELATIONSHIPS (
    orders_to_customers AS
      orders (o_custkey) REFERENCES customers,
    line_item_to_orders AS
      line_items (l_orderkey) REFERENCES orders
  )

  FACTS (
    line_items.line_item_id AS CONCAT(l_orderkey, '-', l_linenumber),
    orders.count_line_items AS COUNT(line_items.line_item_id),
    line_items.discounted_price AS l_extendedprice * (1 - l_discount)
      COMMENT = 'Extended price after discount'
  )

  DIMENSIONS (
    customers.customer_name AS customers.c_name
      WITH SYNONYMS = ('customer name')
      COMMENT = 'Name of the customer',
    orders.order_date AS o_orderdate
      COMMENT = 'Date when the order was placed',
    orders.order_year AS YEAR(o_orderdate)
      COMMENT = 'Year when the order was placed'
  )

  METRICS (
    customers.customer_count AS COUNT(c_custkey)
      COMMENT = 'Count of number of customers',
    orders.order_average_value AS AVG(orders.o_totalprice)
      COMMENT = 'Average order value across all orders',
    orders.average_line_items_per_order AS AVG(orders.count_line_items)
      COMMENT = 'Average number of line items per order'
  )

  COMMENT = 'Semantic view for revenue analysis and different comment'
  COPY GRANTS;

セマンティック・ビューのリスト表示

現在のスキーマまたは指定されたスキーマのセマンティックビューをリストするには、SHOW SEMANTIC VIEWS コマンドを実行します。例:

SHOW SEMANTIC VIEWS;

+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+
| created_on                    | name                  | database_name | schema_name       | comment                                      | owner           | owner_role_type | extension |
|-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------|
| 2025-03-20 15:06:34.039 -0700 | MY_NEW_SEMANTIC_MODEL | MY_DB         | MY_SCHEMA         | A semantic model created through the wizard. | MY_ROLE         | ROLE            | ["CA"]    |
| 2025-02-28 16:16:04.002 -0800 | O_TPCH_SEMANTIC_VIEW  | MY_DB         | MY_SCHEMA         | NULL                                         | MY_ROLE         | ROLE            | NULL      |
| 2025-03-21 07:03:54.120 -0700 | TPCH_REV_ANALYSIS     | MY_DB         | MY_SCHEMA         | Semantic view for revenue analysis           | MY_ROLE         | ROLE            | NULL      |
+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+

SHOW OBJECTS コマンドの出力にはセマンティックビューが含まれます。kind 列には、オブジェクトの型は VIEW としてリストされます。例:

SHOW OBJECTS LIKE '%TPCH_ANALYSIS%' IN SCHEMA;

+-------------------------------+---------------+---------------+-------------+------+---------+------------+------+-------+---------+----------------+-----------------+-----------+------------+------------+
| created_on                    | name          | database_name | schema_name | kind | comment | cluster_by | rows | bytes | owner   | retention_time | owner_role_type | is_hybrid | is_dynamic | is_iceberg |
|-------------------------------+---------------+---------------+-------------+------+---------+------------+------+-------+---------+----------------+-----------------+-----------+------------+------------|
| 2025-10-03 16:28:01.505 -0700 | TPCH_ANALYSIS | MY_DB         | MY_SCHEMA   | VIEW |         |            |    0 |     0 | MY_ROLE | 1              | ROLE            | N         | N          | N          |
+-------------------------------+---------------+---------------+-------------+------+---------+------------+------+-------+---------+----------------+-----------------+-----------+------------+------------+

また、 ACCOUNT_USAGE および INFORMATION_SCHEMA スキーマで、セマンティック・ビューのビューをクエリ できます。

ディメンション、ファクト、メトリックのリスト

ビュー、スキーマ、データベース、またはアカウントで使用可能なディメンション、ファクト、メトリックをリストするには、以下のコマンドを実行します。

デフォルトでは、このコマンドにより、現在のスキーマで定義されたセマンティックビューで使用可能なディメンション、ファクト、メトリックがリストされます。

SHOW SEMANTIC DIMENSIONS;

+---------------+-------------+--------------------+------------+---------------+--------------+-------------------+--------------------------------+
| database_name | schema_name | semantic_view_name | table_name | name          | data_type    | synonyms          | comment                        |
|---------------+-------------+--------------------+------------+---------------+--------------+-------------------+--------------------------------|
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | CUSTOMERS  | CUSTOMER_NAME | VARCHAR(25)  | ["customer name"] | Name of the customer           |
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | CUSTOMERS  | C_CUSTKEY     | NUMBER(38,0) | NULL              | NULL                           |
...

SHOW SEMANTIC FACTS;

+---------------+-------------+--------------------+------------+------------------+--------------------+----------+-------------------------------+
| database_name | schema_name | semantic_view_name | table_name | name             | data_type          | synonyms | comment                       |
|---------------+-------------+--------------------+------------+------------------+--------------------+----------+-------------------------------|
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | LINE_ITEMS | DISCOUNTED_PRICE | NUMBER(25,4)       | NULL     | Extended price after discount |
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | LINE_ITEMS | LINE_ITEM_ID     | VARCHAR(134217728) | NULL     | NULL                          |
...

SHOW SEMANTIC METRICS;

+---------------+-------------+--------------------+------------+------------------------------+--------------+----------+----------------------------------------+
| database_name | schema_name | semantic_view_name | table_name | name                         | data_type    | synonyms | comment                                |
|---------------+-------------+--------------------+------------+------------------------------+--------------+----------+----------------------------------------|
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | CUSTOMERS  | CUSTOMER_COUNT               | NUMBER(18,0) | NULL     | Count of number of customers           |
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | ORDERS     | AVERAGE_LINE_ITEMS_PER_ORDER | NUMBER(36,6) | NULL     | Average number of line items per order |
...

次の例は、異なるスコープ内のセマンティックビューのディメンション、ファクト、およびメトリックをリストする方法を示しています。

  • 現在のデータベースのセマンティックビューのディメンション、ファクト、およびメトリックをリストします。

    SHOW SEMANTIC DIMENSIONS IN DATABASE;

SHOW SEMANTIC FACTS IN DATABASE;

SHOW SEMANTIC METRICS IN DATABASE;

  • 特定のスキーマまたはデータベースのセマンティックビューのディメンション、ファクト、およびメトリックをリストします。

    SHOW SEMANTIC DIMENSIONS IN SCHEMA my_db.my_other_schema;

SHOW SEMANTIC DIMENSIONS IN DATABASE my_db;

SHOW SEMANTIC FACTS IN SCHEMA my_db.my_other_schema;

SHOW SEMANTIC FACTS IN DATABASE my_db;

SHOW SEMANTIC METRICS IN SCHEMA my_db.my_other_schema;

SHOW SEMANTIC METRICS IN DATABASE my_db;

  • アカウントのセマンティックビューのディメンション、ファクト、およびメトリックをリストします。

    SHOW SEMANTIC DIMENSIONS IN ACCOUNT;

SHOW SEMANTIC FACTS IN ACCOUNT;

SHOW SEMANTIC METRICS IN ACCOUNT;

  • 特定のセマンティックビューのディメンション、ファクト、メトリックをリストします。

    SHOW SEMANTIC DIMENSIONS IN my_semantic_view;

SHOW SEMANTIC FACTS IN my_semantic_view;

SHOW SEMANTIC METRICS IN my_semantic_view;

セマンティックビューをクエリする場合、/sql-reference/sql/show-semantic-dimensions-for-metric`コマンドを使用すると、特定のメトリックを指定した際に返せるディメンションを確認できます。詳細については、 :ref:`label-semantic_views_query_dimensions_metrics をご参照ください。

セマンティックビュー用の SHOW COLUMNS コマンドを実行すると、出力にはセマンティックビューのディメンション、ファクト、メトリックが含まれます。kind 列は、行がディメンション、ファクト、またはメトリックを表しているかどうかを示します。

例:

SHOW COLUMNS IN VIEW my_db.my_schema.tpch_analysis;

+---------------+-------------+------------------------------+-----------------------------------------------------------------------------------------+----------+---------+-----------+------------+---------+---------------+---------------+-------------------------+
| table_name    | schema_name | column_name                  | data_type                                                                               | null?    | default | kind      | expression | comment | database_name | autoincrement | schema_evolution_record |
|---------------+-------------+------------------------------+-----------------------------------------------------------------------------------------+----------+---------+-----------+------------+---------+---------------+---------------+-------------------------|
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_COUNT               | {"type":"FIXED","precision":18,"scale":0,"nullable":false}                              | NOT_NULL |         | METRIC    |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_COUNTRY_CODE        | {"type":"TEXT","length":15,"byteLength":60,"nullable":true,"fixed":false}               | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_MARKET_SEGMENT      | {"type":"TEXT","length":10,"byteLength":40,"nullable":true,"fixed":false}               | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_NAME                | {"type":"TEXT","length":25,"byteLength":100,"nullable":true,"fixed":false}              | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_NATION_NAME         | {"type":"TEXT","length":25,"byteLength":100,"nullable":true,"fixed":false}              | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_ORDER_COUNT         | {"type":"FIXED","precision":30,"scale":0,"nullable":true}                               | true     |         | METRIC    |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | CUSTOMER_REGION_NAME         | {"type":"TEXT","length":25,"byteLength":100,"nullable":true,"fixed":false}              | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | C_CUSTOMER_ORDER_COUNT       | {"type":"FIXED","precision":18,"scale":0,"nullable":false}                              | NOT_NULL |         | FACT      |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | LINE_ITEM_ID                 | {"type":"TEXT","length":134217728,"byteLength":134217728,"nullable":true,"fixed":false} | true     |         | FACT      |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | NATION_NAME                  | {"type":"TEXT","length":25,"byteLength":100,"nullable":true,"fixed":false}              | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | N_NAME                       | {"type":"TEXT","length":25,"byteLength":100,"nullable":true,"fixed":false}              | true     |         | FACT      |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | AVERAGE_LINE_ITEMS_PER_ORDER | {"type":"FIXED","precision":36,"scale":6,"nullable":true}                               | true     |         | METRIC    |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | COUNT_LINE_ITEMS             | {"type":"FIXED","precision":18,"scale":0,"nullable":false}                              | NOT_NULL |         | FACT      |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | ORDER_AVERAGE_VALUE          | {"type":"FIXED","precision":30,"scale":8,"nullable":true}                               | true     |         | METRIC    |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | ORDER_COUNT                  | {"type":"FIXED","precision":18,"scale":0,"nullable":false}                              | NOT_NULL |         | METRIC    |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | ORDER_DATE                   | {"type":"DATE","nullable":true}                                                         | true     |         | DIMENSION |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | O_ORDERKEY                   | {"type":"FIXED","precision":38,"scale":0,"nullable":true}                               | true     |         | FACT      |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | R_NAME                       | {"type":"TEXT","length":25,"byteLength":100,"nullable":true,"fixed":false}              | true     |         | FACT      |            |         | MY_DB         |               | NULL                    |
| TPCH_ANALYSIS | MY_SCHEMA   | SUPPLIER_COUNT               | {"type":"FIXED","precision":18,"scale":0,"nullable":false}                              | NOT_NULL |         | METRIC    |            |         | MY_DB         |               | NULL                    |
+---------------+-------------+------------------------------+-----------------------------------------------------------------------------------------+----------+---------+-----------+------------+---------+---------------+---------------+-------------------------+

セマンティックビューの詳細表示

セマンティックビューの詳細を表示するには、DESCRIBE SEMANTIC VIEW コマンドを実行します。例:

DESCRIBE SEMANTIC VIEW tpch_rev_analysis;

+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
| object_kind  | object_name                  | parent_entity | property                 | property_value                         |
|--------------+------------------------------+---------------+--------------------------+----------------------------------------|
| NULL         | NULL                         | NULL          | COMMENT                  | Semantic view for revenue analysis     |
| TABLE        | CUSTOMERS                    | NULL          | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA                  |
| TABLE        | CUSTOMERS                    | NULL          | BASE_TABLE_SCHEMA_NAME   | TPCH_SF1                               |
| TABLE        | CUSTOMERS                    | NULL          | BASE_TABLE_NAME          | CUSTOMER                               |
| TABLE        | CUSTOMERS                    | NULL          | PRIMARY_KEY              | ["C_CUSTKEY"]                          |
| TABLE        | CUSTOMERS                    | NULL          | COMMENT                  | Main table for customer data           |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | TABLE                    | CUSTOMERS                              |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | EXPRESSION               | customers.c_name                       |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | DATA_TYPE                | VARCHAR(25)                            |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | SYNONYMS                 | ["customer name"]                      |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | COMMENT                  | Name of the customer                   |
| TABLE        | LINE_ITEMS                   | NULL          | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA                  |
| TABLE        | LINE_ITEMS                   | NULL          | BASE_TABLE_SCHEMA_NAME   | TPCH_SF1                               |
| TABLE        | LINE_ITEMS                   | NULL          | BASE_TABLE_NAME          | LINEITEM                               |
| TABLE        | LINE_ITEMS                   | NULL          | PRIMARY_KEY              | ["L_ORDERKEY","L_LINENUMBER"]          |
| TABLE        | LINE_ITEMS                   | NULL          | COMMENT                  | Line items in orders                   |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | TABLE                    | LINE_ITEMS                             |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | REF_TABLE                | ORDERS                                 |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | FOREIGN_KEY              | ["L_ORDERKEY"]                         |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | REF_KEY                  | ["O_ORDERKEY"]                         |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | TABLE                    | LINE_ITEMS                             |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | EXPRESSION               | l_extendedprice * (1 - l_discount)     |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | DATA_TYPE                | NUMBER(25,4)                           |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | COMMENT                  | Extended price after discount          |
| FACT         | LINE_ITEM_ID                 | LINE_ITEMS    | TABLE                    | LINE_ITEMS                             |
| FACT         | LINE_ITEM_ID                 | LINE_ITEMS    | EXPRESSION               | CONCAT(l_orderkey, '-', l_linenumber)  |
| FACT         | LINE_ITEM_ID                 | LINE_ITEMS    | DATA_TYPE                | VARCHAR(134217728)                     |
| TABLE        | ORDERS                       | NULL          | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA                  |
| TABLE        | ORDERS                       | NULL          | BASE_TABLE_SCHEMA_NAME   | TPCH_SF1                               |
| TABLE        | ORDERS                       | NULL          | BASE_TABLE_NAME          | ORDERS                                 |
| TABLE        | ORDERS                       | NULL          | SYNONYMS                 | ["sales orders"]                       |
| TABLE        | ORDERS                       | NULL          | PRIMARY_KEY              | ["O_ORDERKEY"]                         |
| TABLE        | ORDERS                       | NULL          | COMMENT                  | All orders table for the sales domain  |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | TABLE                    | ORDERS                                 |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | REF_TABLE                | CUSTOMERS                              |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | FOREIGN_KEY              | ["O_CUSTKEY"]                          |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | REF_KEY                  | ["C_CUSTKEY"]                          |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | TABLE                    | ORDERS                                 |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | EXPRESSION               | AVG(orders.count_line_items)           |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | DATA_TYPE                | NUMBER(36,6)                           |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | COMMENT                  | Average number of line items per order |
| FACT         | COUNT_LINE_ITEMS             | ORDERS        | TABLE                    | ORDERS                                 |
| FACT         | COUNT_LINE_ITEMS             | ORDERS        | EXPRESSION               | COUNT(line_items.line_item_id)         |
| FACT         | COUNT_LINE_ITEMS             | ORDERS        | DATA_TYPE                | NUMBER(18,0)                           |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | TABLE                    | ORDERS                                 |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | EXPRESSION               | AVG(orders.o_totalprice)               |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | DATA_TYPE                | NUMBER(30,8)                           |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | COMMENT                  | Average order value across all orders  |
| DIMENSION    | ORDER_DATE                   | ORDERS        | TABLE                    | ORDERS                                 |
| DIMENSION    | ORDER_DATE                   | ORDERS        | EXPRESSION               | o_orderdate                            |
| DIMENSION    | ORDER_DATE                   | ORDERS        | DATA_TYPE                | DATE                                   |
| DIMENSION    | ORDER_DATE                   | ORDERS        | COMMENT                  | Date when the order was placed         |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | TABLE                    | ORDERS                                 |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | EXPRESSION               | YEAR(o_orderdate)                      |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | DATA_TYPE                | NUMBER(4,0)                            |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | COMMENT                  | Year when the order was placed         |
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+

セマンティックビューの SQL ステートメントを取得します。

GET_DDL 関数を呼び出すと、セマンティックビューを作成した DDL ステートメントを取得できます。

注釈

セマンティックビューに関してこの関数を呼び出すには、:ref:` セマンティックビューに対するREFERENCES または OWNERSHIP 権限を付与された <label-semantic_views_privileges>` ロールを使用する必要があります。

GET_DDL を呼び出す際、オブジェクトタイプとして 'SEMANTIC_VIEW' を渡します。例:

SELECT GET_DDL('SEMANTIC_VIEW', 'tpch_rev_analysis', TRUE);

+-----------------------------------------------------------------------------------+
| GET_DDL('SEMANTIC_VIEW', 'TPCH_REV_ANALYSIS', TRUE)                               |
|-----------------------------------------------------------------------------------|
| create or replace semantic view DYOSHINAGA_DB.DYOSHINAGA_SCHEMA.TPCH_REV_ANALYSIS |
|     tables (                                                                                                                                                                       |
|             ORDERS primary key (O_ORDERKEY) with synonyms=('sales orders') comment='All orders table for the sales domain',                                                                                                                                                                       |
|             CUSTOMERS as CUSTOMER primary key (C_CUSTKEY) comment='Main table for customer data',                                                                                                                                                                       |
|             LINE_ITEMS as LINEITEM primary key (L_ORDERKEY,L_LINENUMBER) comment='Line items in orders'                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     relationships (                                                                                                                                                                       |
|             ORDERS_TO_CUSTOMERS as ORDERS(O_CUSTKEY) references CUSTOMERS(C_CUSTKEY),                                                                                                                                                                       |
|             LINE_ITEM_TO_ORDERS as LINE_ITEMS(L_ORDERKEY) references ORDERS(O_ORDERKEY)                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     facts (                                                                                                                                                                       |
|             ORDERS.COUNT_LINE_ITEMS as COUNT(line_items.line_item_id),                                                                                                                                                                       |
|             LINE_ITEMS.DISCOUNTED_PRICE as l_extendedprice * (1 - l_discount) comment='Extended price after discount',                                                                                                                                                                       |
|             LINE_ITEMS.LINE_ITEM_ID as CONCAT(l_orderkey, '-', l_linenumber)                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     dimensions (                                                                                                                                                                       |
|             ORDERS.ORDER_DATE as o_orderdate comment='Date when the order was placed',                                                                                                                                                                       |
|             ORDERS.ORDER_YEAR as YEAR(o_orderdate) comment='Year when the order was placed',                                                                                                                                                                       |
|             CUSTOMERS.CUSTOMER_NAME as customers.c_name with synonyms=('customer name') comment='Name of the customer'                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     metrics (                                                                                                                                                                       |
|             ORDERS.AVERAGE_LINE_ITEMS_PER_ORDER as AVG(orders.count_line_items) comment='Average number of line items per order',                                                                                                                                                                       |
|             ORDERS.ORDER_AVERAGE_VALUE as AVG(orders.o_totalprice) comment='Average order value across all orders'                                                                                                                                                                       |
|     );                                                                                                                                                                       |
+-----------------------------------------------------------------------------------+

戻り値には :ref:` プライベートなファクトとメトリック <label-semantic_views_private>`（PRIVATE キーワードでマークされたファクトとメトリック）が含まれます。

セマンティックビューのYAML仕様を取得する

セマンティックビューの:doc:YAML仕様<semantic-view-yaml-spec>`を取得するには、:doc:/sql-reference/functions/system_read_yaml_from_semantic_view`関数を呼び出します。

次の例は、データベース my_db とスキーマ my_schema にある tpch_analysis という名前のセマンティックビューの YAML 仕様を返します。

SELECT SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW(
  'my_db.my_schema.tpch_rev_analysis'
);

+-------------------------------------------------------------+
| READ_YAML_FROM_SEMANTIC_VIEW                                |
|-------------------------------------------------------------|
| name: TPCH_REV_ANALYSIS                                     |
| description: Semantic view for revenue analysis             |
| tables:                                                     |
|   - name: CUSTOMERS                                         |
|     description: Main table for customer data               |
|     base_table:                                             |
|       database: SNOWFLAKE_SAMPLE_DATA                       |
|       schema: TPCH_SF1                                      |
|       table: CUSTOMER                                       |
|     primary_key:                                            |
|       columns:                                              |
|         - C_CUSTKEY                                         |
|     dimensions:                                             |
|       - name: CUSTOMER_NAME                                 |
|         synonyms:                                           |
|           - customer name                                   |
|         description: Name of the customer                   |
|         expr: customers.c_name                              |
|         data_type: VARCHAR(25)                              |
|       - name: C_CUSTKEY                                     |
|         expr: C_CUSTKEY                                     |
|         data_type: VARCHAR(134217728)                       |
|   - name: LINE_ITEMS                                        |
|     description: Line items in orders                       |
|     base_table:                                             |
|       database: SNOWFLAKE_SAMPLE_DATA                       |
|       schema: TPCH_SF1                                      |
|       table: LINEITEM                                       |
|     primary_key:                                            |
|       columns:                                              |
|         - L_ORDERKEY                                        |
|         - L_LINENUMBER                                      |
|     dimensions:                                             |
|       - name: L_ORDERKEY                                    |
|         expr: L_ORDERKEY                                    |
|         data_type: VARCHAR(134217728)                       |
|       - name: L_LINENUMBER                                  |
|         expr: L_LINENUMBER                                  |
|         data_type: VARCHAR(134217728)                       |
|     facts:                                                  |
|       - name: DISCOUNTED_PRICE                              |
|         description: Extended price after discount          |
|         expr: l_extendedprice * (1 - l_discount)            |
|         data_type: "NUMBER(25,4)"                           |
|       - name: LINE_ITEM_ID                                  |
|         expr: "CONCAT(l_orderkey, '-', l_linenumber)"       |
|         data_type: VARCHAR(134217728)                       |
|   - name: ORDERS                                            |
|     synonyms:                                               |
|       - sales orders                                        |
|     description: All orders table for the sales domain      |
|     base_table:                                             |
|       database: SNOWFLAKE_SAMPLE_DATA                       |
|       schema: TPCH_SF1                                      |
|       table: ORDERS                                         |
|     primary_key:                                            |
|       columns:                                              |
|         - O_ORDERKEY                                        |
|     dimensions:                                             |
|       - name: ORDER_DATE                                    |
|         description: Date when the order was placed         |
|         expr: o_orderdate                                   |
|         data_type: DATE                                     |
|       - name: ORDER_YEAR                                    |
|         description: Year when the order was placed         |
|         expr: YEAR(o_orderdate)                             |
|         data_type: "NUMBER(4,0)"                            |
|       - name: O_ORDERKEY                                    |
|         expr: O_ORDERKEY                                    |
|         data_type: VARCHAR(134217728)                       |
|       - name: O_CUSTKEY                                     |
|         expr: O_CUSTKEY                                     |
|         data_type: VARCHAR(134217728)                       |
|     facts:                                                  |
|       - name: COUNT_LINE_ITEMS                              |
|         expr: COUNT(line_items.line_item_id)                |
|         data_type: "NUMBER(18,0)"                           |
|     metrics:                                                |
|       - name: AVERAGE_LINE_ITEMS_PER_ORDER                  |
|         description: Average number of line items per order |
|         expr: AVG(orders.count_line_items)                  |
|       - name: ORDER_AVERAGE_VALUE                           |
|         description: Average order value across all orders  |
|         expr: AVG(orders.o_totalprice)                      |
| relationships:                                              |
|   - name: LINE_ITEM_TO_ORDERS                               |
|     left_table: LINE_ITEMS                                  |
|     right_table: ORDERS                                     |
|     relationship_columns:                                   |
|       - left_column: L_ORDERKEY                             |
|         right_column: O_ORDERKEY                            |
|   - name: ORDERS_TO_CUSTOMERS                               |
|     left_table: ORDERS                                      |
|     right_table: CUSTOMERS                                  |
|     relationship_columns:                                   |
|       - left_column: O_CUSTKEY                              |
|         right_column: C_CUSTKEY                             |
|                                                             |
+-------------------------------------------------------------+

セマンティックビューのTableauデータソース（TDS）ファイルへのエクスポート

セマンティックビューを`Tableau Data Source（TDS）ファイル<https://help.tableau.com/current/pro/desktop/en-us/export_connection.htm#options-for-saving-a-local-data-source>`_にエクスポートするには、:doc:`/sql-reference/functions/system_export_tds_from_semantic_view`関数を呼び出します。

次の例は、セマンティックビュー``my_sv_for_export``のTDSファイルコンテンツを返します。

SELECT SYSTEM$EXPORT_TDS_FROM_SEMANTIC_VIEW('my_sv_for_export');

+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| SYSTEM$EXPORT_TDS_FROM_SEMANTIC_VIEW('MY_SV_FOR_EXPORT')                                                                                                                                                                                                              |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <?xml version="1.0" encoding="UTF-8"?>                                                                                                                                                                                                                                |
| <!--Tableau compatibility notice:                                                                                                                                                                                                                                     |
| - Generated TDS schema version 18.1 is validated against Tableau Desktop 2025.2                                                                                                                                                                                       |
| - Connection customization schema version 1 enables CAP_* settings to take effect.                                                                                                                                                                                    |
| - Update these versions if your Tableau client requires a different schema.-->                                                                                                                                                                                        |
| <!--Dimensions and measures with duplicated names [DUPLICATE_DIM] are not shown in the TDS file-->                                                                                                                                                                    |
| <datasource xmlns:user="http://www.tableausoftware.com/xml/user" formatted-name="federated.0484db64fcbd48d89e8af86a62" inline="true" version="18.1">                                                                                                                  |
|   <document-format-change-manifest>                                                                                                                                                                                                                                   |
| ...                                                                                                                                 |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

XMLを``.tds``ファイルにコピーし、Tableau Desktopでファイルを開きます。

Tableau Desktopは、左側のフォルダーリストに各論理テーブルのフォルダーを表示します。フォルダーの名前はアンダースコアの代わりにスペースを使用し、各単語は大文字で始まります。たとえば、``date_dim``論理テーブルのフォルダー名は``Date Dim``です。

各フォルダーには、セマンティックビューのディメンション、ファクト、およびメトリックに対応するTableauのディメンションとメジャーが含まれています。

次のセクションでは、変換プロセスの詳細と制限を説明します。

変換について

関数は、セマンティックビューのディメンション、ファクト、およびメトリックを、Tableau TDSファイルにおける以下の対応する要素に変換します。

セマンティックビューの要素

Tableauの対応するもの（ディメンションまたはメジャー）

データの集計方法

ディメンション

ディメンション

  • 数値ディメンションの値の場合は、SUMが使用されます。

  • 日付ディメンションは年ごとに集計されます。

  • 他のタイプのディメンションの場合は、COUNTが使用されます。

数値:ref:ファクト<label-semantic_views_create_facts_dimensions_metrics>

測定

SUM

非数値ファクト

ディメンション

  • 日付ディメンションは年ごとに集計されます。

  • 他のタイプのディメンションの場合は、COUNTが使用されます。

数値:ref:メトリック<label-semantic_views_create_facts_dimensions_metrics>

測定

TDSファイルは、メトリックの代わりに計算フィールドを使用します。計算フィールドは、メトリックの値をSnowflake :doc:`/sql-reference/functions/agg`関数に渡します。

非数値メトリック

ディメンション

  • 日付ディメンションは年ごとに集計されます。

  • 他のタイプのディメンションの場合は、COUNTが使用されます。

数値:ref:派生メトリック<label-semantic_views_create_derived_metrics>

測定

TDSファイルは、メトリックの代わりに計算フィールドを使用します。計算フィールドは、メトリックの値をSnowflake :doc:`/sql-reference/functions/agg`関数に渡します。

非数値派生メトリック

ディメンション

  • 日付ディメンションは年ごとに集計されます。

  • 他のタイプのディメンションの場合は、COUNTが使用されます。

次の:doc:`Snowflakeデータ型</sql-reference-data-types>`は、対応するTableauのTDSデータ型にマップされます。

Snowflakeデータ型

対応するTableauデータ型

NUMBER/FIXED（スケールが0より大きい場合）

real

NUMBER/FIXED（スケールが0またはnullの場合）

integer

FLOAT または DECFLOAT

real

STRING または BINARY

string

BOOLEAN

boolean

TIME

time

DATE

date

DATETIME または TIMESTAMP

datetime

GEOGRAPHY

spatial

半構造化（VARIANT、OBJECT、ARRAY）、構造化（ARRAY、OBJECT、MAP）、非構造化（FILE）、GEOMETRY、UUID、VECTOR

string

TDSファイルには、Snowflakeへの接続用にカスタマイズされた次の`機能<https://help.tableau.com/current/pro/desktop/en-us/odbc_capabilities.htm>`_があります。

カスタマイズ名

値

カスタマイズの効果

CAP_ODBC_METADATA_SUPPRESS_EXECUTED_QUERY

yes

Tableauが列名を表示するために:samp:`SELECT * FROM {table} WHERE 1=0`のようなクエリを実際に実行することを防止します。

CAP_ODBC_METADATA_SUPPRESS_PREPARED_QUERY

yes

Tableauが型について学習するためにステートメントを「準備」（実行せずに解析されるようにSnowflakeに送信）することを防止します。

CAP_ODBC_METADATA_SUPPRESS_SELECT_STAR

yes

Tableauがメタデータを読み取るために:code:`SELECT *`クエリを使用することを防止します。

CAP_ODBC_METADATA_SUPPRESS_SQLCOLUMNS_API

no

セマンティックビューに関する列情報を返すために、Tableauに標準のODBC :code:`SQLColumns`関数を有効にして使用するように強制します。この列情報には、列の名前、データ型、精度が含まれます。

CAP_DISABLE_ESCAPE_UNDERSCORE_IN_CATALOG

yes

データベース名を検索するときに、Tableauがアンダースコアをエスケープしないようにします。

Tableau Desktopでセマンティックビューを使用する際の制限

Tableau Desktopのセマンティックビューには以下の制限が適用されます。

  • セマンティックビューから抽出を作成することはできません。

    接続を:extui:`Live`から:extui:`Extract`に変更した場合、Tableau Desktopは次のエラーで失敗します。

    SQL compilation error:
Requested semantic expression 'XXX' in FACTS clause must be one of the following types: (DIMENSION, FACT).
Unable to create extract

  • セマンティックビューでは:extui:`Measure Values`フィールドを使用できません。

    セマンティックビューで:extui:`Measure Values`フィールドを選択した場合、Tableau Desktopは次のエラーを報告します。

    Unable to complete action

Error Code: B9F09DDB
SQL compilation error: error line 1 at position 7
Invalid metric expression 'SUM(1)'.

  • セマンティックビューでは:extui:`Count`フィールドを選択できません。

    :extui:`SemanticViewName(Count)`を選択した場合、Tableau Desktopは次のエラーを報告します。

    Unable to complete action

Error Code: B9F09DDB
SQL compilation error: error line 1 at position 7
Invalid metric expression 'SUM(1)'.

    クエリで指定されたディメンション、ファクト、およびメトリックによって行数が異なる可能性があるため、Tableau Desktopはセマンティックビューの行数をレポートできません。

  • メジャーを単独でドラッグすることはできません。

    メジャーをドラッグすると、Tableau Desktopは次のエラーを報告します。

    Unable to complete action

Error Code: B9F09DDB
SQL compilation error: error line 3 at position 8
Invalid metric expression 'COUNT(1)'.

  • 非数値メトリックを直接使用することはできません。

    SYSTEM$EXPORT_TDS_FROM_SEMANTIC_VIEWは、Tableauで非数値メトリックをディメンションに変換します。これらのディメンションのいずれかを使用しようとすると、Tableau Desktopは次のエラーを報告します。

    Unable to complete action

Error Code: B9F09DDB
SQL compilation error:
Requested semantic expression 'CUSTOMER.MIN_NAME' in DIMENSIONS clause must be one of the following types: (DIMENSION, FACT).

    これを回避するには、ディメンションをメジャーに変換します。

    1. ディメンションを右クリックして、:extui:`Convert to Measure`を選択します。

      これにより、デフォルトの集計:extui:`Count (Distinct)`を使用して、ディメンションをメジャーに変換します。

    2. 別の集計を使用するには、変換されたメジャーを右クリックし、Default Properties » :extui:`Aggregations`を選択して、使用する集計を選択します。

セマンティックビューの名前変更

セマンティックビューの名前を変更するには、ALTERSEMANTICVIEW... RENAMETO... を実行します。例:

ALTER SEMANTIC VIEW sv RENAME TO sv_new_name;

セマンティックビューの削除

セマンティックビューを削除するには、DROP SEMANTIC VIEW コマンドを実行します。例:

DROP SEMANTIC VIEW tpch_rev_analysis;

セマンティックビューの権限付与

セマンティックビュー権限 はセマンティックビューに付与できる権限のリストです。

セマンティックビューを操作するには、以下の権限が必要です。

  • ビューで DESCRIBE SEMANTIC VIEW コマンドを実行するには、そのビューに対する権限（例えば MONITOR、 REFERENCES または SELECT）が必要です。

  • SHOW SEMANTIC VIEWS コマンドの出力にそのビューを表示するには、ビューに対する権限が必要です。

  • セマンティックビューをクエリするには SELECT が必要です。

注釈

セマンティックビューをクエリには、SELECT セマンティックビューで使用されるテーブルに対するSELECT 権限は必要ありません。セマンティックビュー自体に対する SELECT 権限のみが必要です。

この動作は 標準クエリに必要な権限 と一致しています。

Cortex Analyst で所有していないセマンティック・ビューを使用するには、そのビューの REFERENCES および SELECT 権限を持つロールを使用する必要があります。

セマンティックビューに対する REFERENCES および SELECT 権限を付与するには、GRANT <権限> ... TO ROLE コマンドを使用します。たとえば、my_semantic_view という名前のセマンティックビューに対する REFERENCES および SELECT 権限をロール my_analyst_role に付与するには、次のステートメントを実行します。

GRANT REFERENCES, SELECT ON SEMANTIC VIEW my_semantic_view TO ROLE my_analyst_role;

Cortex Analyst ユーザーと共有したいセマンティックビューを含むスキーマがある場合、 future grants を使用して、そのスキーマで作成したセマンティックビューの権限を付与することができます。例:

GRANT REFERENCES, SELECT ON FUTURE SEMANTIC VIEWS IN SCHEMA my_schema TO ROLE my_analyst_role;