SQL コマンドを使用したセマンティックビューの作成と管理¶
このトピックでは、次のSQLコマンドを使用して:doc:`セマンティックビュー<overview>`を作成、管理する方法について説明します。
また、次のストアドプロシージャと関数を呼び出して、:doc:`セマンティックモデル仕様</user-guide/snowflake-cortex/cortex-analyst/semantic-model-spec>`からセマンティックビューを作成し、セマンティックビューの仕様を取得する方法についても説明します。
セマンティックビューの作成に必要な権限¶
セマンティックビューを作成するには、次の権限を持つロールを使用する必要があります。
CREATE SEMANTIC VIEW をセマンティックビューを作成するスキーマに追加します。
USAGE セマンティックビューを作成するデータベースとスキーマで、次のように設定します。
SELECT セマンティックビューで使用されるテーブルとビューで使用されます。
セマンティックビューのクエリに必要な権限については、:ref:`label-semantic_views_privileges_select`を参照してください。
セマンティックビューの作成¶
セマンティックビューを作成するには、次のいずれかを行います。
CREATE SEMANTIC VIEW コマンドを実行します。
セマンティックモデルのYAML仕様</user-guide/snowflake-cortex/cortex-analyst/semantic-model-spec>`からセマンティックビューを作成する場合は、:doc:/sql-reference/stored-procedures/system_create_semantic_view_from_yaml`ストアドプロシージャを呼び出します。
セマンティックビューは有効でなければなりません。Snowflakeによるセマンティックビューの検証方法 をご参照ください。
以降のセクションでは、セマンティックビューの作成方法について説明します。
CREATE SEMANTIC VIEWコマンドを使用する¶
次の例では、:doc:`/sql-reference/sql/create-semantic-view`コマンドを使用してセマンティックビューを作成します。
この例は、Snowflakeで利用可能な:doc:`TPC-Hサンプルデータ</user-guide/sample-data-tpch>`を使用しています。このデータセットには、顧客、注文、明細で個別のビジネスシナリオを表すテーブルが含まれています。
この例では、 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 句を使用して、ビュー内の論理テーブルを定義します。この句では、次のことができます。
物理テーブル名とオプションのエイリアスを指定します。
論理テーブルの以下の列の識別子。
主キーとなる列。
一意な値を含む列（主キー列以外）。
これらの列を使用して、このセマンティックビューでリレーションシップを定義することができます。
テーブルの同義語を追加します（発見性を高めるため）。
説明的なコメントを添えてください。
注釈
2つのテーブルを結合できる方法が複数ある場合は、その方法ごとに個別の論理テーブルを定義する必要があります。詳細については、 2つのテーブルを結合するパスごとに異なる論理テーブルを定義する をご参照ください。
先に示した の例では、、 TABLES 句は3つの論理テーブルを定義します。
TPC-H
ordersテーブルからのオーダー情報を含むordersテーブル。TPC-H
customersテーブルの顧客情報を含むcustomersテーブル。TPC-H
lineitemテーブルからのオーダーのラインアイテムを含むline_itemテーブル。
この例では、各論理テーブルの主キーとして使用する列を識別子として指定し、テーブル間の リレーションシップを識別 できるようにしています。
この例では、論理テーブルを説明する同義語やコメントもプロバイダーとして提供し、データを発見しやすくしています。
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'
2つのテーブルを結合するパスごとに異なる論理テーブルを定義する¶
2つの物理テーブルを結合するために使用できるパスが複数ある場合は、パスごとに個別の論理テーブルと関係を定義する必要があります。
たとえば、Snowflakeで利用可能な:doc:`TPC-Hサンプルデータ</user-guide/sample-data-tpch>`の場合、``region``テーブルと``lineitem``テーブルを結合する方法は2つあります。
region->nation->supplier->partsupp->lineitemregion->nation->customer->orders->lineitem
最初のパスはサプライヤーの地域を表し、2番目のパスは顧客の地域を表します。
``region``に単一の論理テーブルを使用し、``nation``に単一の論理テーブルを使用することもできますが、サプライヤーの地域、顧客の地域、サプライヤーの国、顧客の国ごとに別々の論理テーブルを定義する必要があります。
TABLES (
supplier_region AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.REGION PRIMARY KEY (r_regionkey).
customer_region AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.REGION PRIMARY KEY (r_regionkey),
supplier_nation AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.NATION PRIMARY KEY (n_nationkey),
customer_nation AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.NATION PRIMARY KEY (n_nationkey),
...
)
次に、異なるパスを表す個別の関係を定義します。
RELATIONSHIPS (
supplier_nation (n_regionkey) REFERENCES supplier_region,
customer_nation (n_regionkey) REFERENCES customer_region,
...
)
論理テーブル間のリレーションシップの識別子¶
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)
)
ファクト、ディメンション、メトリクスの定義¶
CREATE SEMANTIC VIEW コマンドでは、 FACTS、 DIMENSIONS、 METRICS 句を使用して、セマンティック・ビューのファクト、ディメンション、およびメトリクスを定義します。
セマンティックビューに、少なくとも 1 つのディメンションまたはメトリクスを定義する必要があります。
ファクト、ディメンション、またはメトリクスごとに指定します。
所属する論理テーブル。
ファクト、寸法、またはメトリクスの名前。
SQL 式で計算します。
任意の同義語とコメント。
先に示した 例 では、いくつかのファクト、ディメンション、メトリクスを定義しています。
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'
)
注釈
ウィンドウ関数を使用するメトリックの定義に関する追加のガイドラインについては、:ref:`label-semantic_views_querying_window`をご覧ください。
ファクトやメトリックをプライベートとしてマークする¶
セマンティックビューの計算でのみ使用するためにファクトまたはメトリックを定義し、クエリでファクトまたはメトリックを返さないようにする場合は、ファクトまたはメトリックをプライベートとしてマークする PRIVATE キーワードを指定できます。例:
FACTS (
PRIVATE my_private_fact AS ...
)
METRICS (
PRIVATE my_private_metric AS ...
)
注釈
ディメンションをプライベートとしてマークすることはできません。ディメンションは常にパブリックです。
プライベートなファクトまたはメトリックを含むセマンティックビューをクエリする場合、以下の句でプライベートなファクトまたはメトリックを指定することはできません。
SELECTリスト
:doc:`/sql-reference/constructs/semantic_view`句内のFACTS
:doc:`/sql-reference/constructs/semantic_view`句内のMETRICS
METRICS
SELECTステートメントまたは:doc:`/sql-reference/constructs/semantic_view`句内のWHERE
一部のコマンドと関数には、プライベートなファクトとメトリックが含まれます。
プライベートなファクトとメトリックは、:doc:`/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>`ビューにリストされます。
それ以外の場合、これらのビューにはパブリックなファクトとメトリックのみがリストされます。
その他のコマンドや関数には、プライベートなファクトとメトリックは含まれません。
プライベートメトリックは、:doc:`/sql-reference/sql/show-semantic-metrics`コマンドの出力には表示されません。
YAML仕様からセマンティックビューを作成する¶
セマンティックモデルのYAML仕様</user-guide/snowflake-cortex/cortex-analyst/semantic-model-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. |
+-----------------------------------------+
既存のセマンティックビューのコメントを変更する¶
既存のセマンティックビューのコメントを変更するには、:doc:`/sql-reference/sql/alter-semantic-view`コマンドを実行します。例:
ALTER SEMANTIC VIEW my_semantic_view SET COMMENT = 'my comment';
注釈
コメント以外のプロパティを変更するのに、ALTERSEMANTICVIEW コマンドは使用できません。セマンティックビューの他のプロパティを変更するには、セマンティックビューを置き換えます。既存のセマンティックビューの置き換え をご参照ください。
:doc:`/sql-reference/sql/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 |
+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+
また、 ACCOUNT_USAGE および INFORMATION_SCHEMA スキーマで、セマンティック・ビューのビューをクエリ できます。
ディメンションとメトリックをリストする¶
ビュー、スキーマ、データベース、またはアカウントで使用可能なディメンションとメトリックをリストするには、/sql-reference/sql/show-semantic-dimensions`コマンドと:doc:/sql-reference/sql/show-semantic-metrics`コマンドを実行します。
デフォルトでは、このコマンドにより、現在のスキーマで定義されたセマンティックビューで使用可能なディメンションとメトリックがリストされます。
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 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 METRICS IN DATABASE;
特定のスキーマまたはデータベースのセマンティックビュー。
SHOW SEMANTIC DIMENSIONS IN SCHEMA my_db.my_other_schema; SHOW SEMANTIC DIMENSIONS 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 METRICS IN ACCOUNT;
特定のセマンティックビュー。
SHOW SEMANTIC DIMENSIONS IN my_semantic_view;
セマンティックビューをクエリする場合、/sql-reference/sql/show-semantic-dimensions-for-metric`コマンドを使用すると、特定のメトリックを指定した際に返せるディメンションを確認できます。詳細については、 :ref:`label-semantic_views_query_dimensions_metrics をご参照ください。
セマンティックビューの詳細表示¶
セマンティック・ビューの詳細を表示するには、 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仕様</user-guide/snowflake-cortex/cortex-analyst/semantic-model-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 |
| |
+-------------------------------------------------------------+
セマンティックビューの削除¶
セマンティックビューを削除するには、 DROP SEMANTIC VIEW コマンドを実行します。例:
DROP SEMANTIC VIEW tpch_rev_analysis;
セマンティックビューの権限付与¶
セマンティックビュー権限 はセマンティックビューに付与できる権限のリストです。
セマンティックビューを操作するには、以下の権限が必要です。
ビューに対して:doc:`/sql-reference/sql/desc-semantic-view`コマンドを実行するには、権限（REFERENCESORSELECTなど）が必要です。
SELECT ... FROM SEMANTIC_VIEW()の実行には SELECT が必要です。SHOW SEMANTIC VIEWS コマンドの出力にビューを表示するには、これらの権限のいずれかが必要です。
注釈
セマンティックビューをクエリには、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;