Verwendung von SQL-Befehlen zum Erstellen und Verwalten semantischer Ansichten¶
In diesem Thema wird erklärt, wie die folgenden SQL-Befehle zum Erstellen und Verwalten von semantische Ansichten verwendet werden:
In diesem Thema wird außerdem erläutert, wie die folgende gespeicherte Prozedur und Funktion aufgerufen werden, um aus einer Semantikmodellspezifikation eine semantische Sicht zu erstellen und die Spezifikation für eine semantische Sicht abzurufen.
Erforderliche Berechtigungen zum Erstellen einer semantischen Ansicht¶
Um eine semantische Ansicht zu erstellen, müssen Sie eine Rolle mit den folgenden Berechtigungen verwenden:
CREATE SEMANTIC VIEW in dem Schema, in dem Sie die semantische Ansicht erstellen.
USAGE für die Datenbank und das Schema, in dem Sie die semantische Ansicht erstellen.
SELECT auf die in der semantischen Ansicht verwendeten Tabellen und Ansichten.
Informationen zu den Berechtigungen, die für die Abfrage einer semantischen Ansicht erforderlich sind, finden Sie unter Erforderliche Berechtigungen für die Abfrage einer semantischen Ansicht.
Erstellen einer semantischen Ansicht¶
Für das Erstellen einer semantischen Ansicht gibt es zwei Möglichkeiten:
Führen Sie den Befehl CREATE SEMANTIC VIEW aus.
Rufen Sie den SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML gespeicherten Prozess auf, wenn Sie eine semantische Ansicht aus YAML-Spezifikation für ein semantisches Modell erstellen möchten.
Die semantische Ansicht muss gültig sein. Siehe Wie Snowflake semantische Ansichten validiert.
In den nächsten Abschnitten erfahren Sie, wie Sie eine semantische Ansicht erstellen:
Verwenden des Befehls CREATE SEMANTIC VIEW¶
Im folgenden Beispiel wird der Befehl CREATE SEMANTIC VIEW verwendet, um eine semantische Ansicht zu erstellen.
In dem Beispiel werden die TPC-H-Beispieldaten verwendet, die in Snowflake verfügbar sind. Dieses Datenset enthält Tabellen, die ein vereinfachtes Geschäftsszenario mit Kunden, Bestellungen und Einzelposten darstellen.
In diesem Beispiel wird eine semantische Ansicht mit dem Namen tpch_rev_analysis erstellt, die die Tabellen im Datensatz TPC-H verwendet. Die semantische Ansicht definiert:
Drei logische Tabellen (
orders,customers, undline_items).Eine Beziehung zwischen den Tabellen
ordersundcustomers.Eine Beziehung zwischen den Tabellen
line_itemsundorders.Fakten, die zur Berechnung der Metriken verwendet werden.
Dimensionen für den Kundennamen, das Bestelldatum und das Jahr, in dem die Bestellung aufgegeben wurde.
Metriken für den durchschnittlichen Wert einer Bestellung und die durchschnittliche Anzahl von Einzelposten in einer Bestellung.
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';
In den nächsten Abschnitten wird dieses Beispiel ausführlicher erläutert:
Bemerkung
Ein vollständiges Beispiel finden Sie unter Beispiel für die Verwendung von SQL zur Erstellung einer semantischen Ansicht.
Definieren der logischen Tabellen¶
Verwenden Sie im Befehl CREATE SEMANTIC VIEW die Klausel TABLES, um die logischen Tabellen in der Ansicht zu definieren. In dieser Klausel können Sie:
Geben Sie den Namen der physischen Tabelle und einen optionalen Alias an.
Identifizieren Sie die folgenden Spalten in der logischen Tabelle:
Spalten, die als Primärschlüssel dienen.
Spalten, die eindeutige Werte enthalten (andere als die Primärschlüsselspalten).
Sie können diese Spalten verwenden, um Beziehungen in dieser semantischen Ansicht zu definieren.
Fügen Sie Synonyme für die Tabelle hinzu (für eine bessere Auffindbarkeit).
Fügen Sie einen beschreibenden Kommentar hinzu.
Bemerkung
Wenn es mehrere Möglichkeiten gibt, wie zwei Tabellen verknüpft werden können, sollten Sie für jede diese Möglichkeiten eine eigene logische Tabelle definieren. Weitere Informationen dazu finden Sie unter Definieren verschiedener logischer Tabellen für verschiedene Pfade, die zwei Tabellen verbinden.
In dem zuvor vorgestellten Beispiel definiert die Klausel TABLES drei logische Tabellen:
Eine Tabelle
orders, die die Bestellinformationen aus der Tabelle TPC-Hordersenthält.Eine Tabelle
customers, die die Kundeninformationen aus der Tabelle TPC-Hcustomersenthält.Eine Tabelle
line_item, mit den Einzelposten in Bestellungen aus der Tabelle TPC-Hlineitem.
Das Beispiel bezeichnet die Spalten, die als Primärschlüssel für jede logische Tabelle verwendet werden sollen, sodass Sie die Beziehungen zwischen den Tabellen erkennen können.
Das Beispiel enthält auch Synonyme und Kommentare, die die logischen Tabellen beschreiben und die Daten leichter auffindbar machen.
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'
Definieren verschiedener logischer Tabellen für verschiedene Pfade, die zwei Tabellen verbinden¶
Wenn es mehrere Pfade gibt, die Sie verwenden können, um zwei physische Tabellen zu verknüpfen, sollten Sie für jeden Pfad eigene logische Tabellen und Beziehungen definieren.
In den TPC-H-Beispieldaten, die in Sind verfügbar sind, gibt es beispielsweise zwei Möglichkeiten die Tabellen region und lineitem zu verknüpfen:
region->Nation>Lieferanten->Teile->Einzelelementregion->Nation->Kunde->Aufträge->Einzelelement
Der erste Pfad steht für die Region des Anbieters und der zweite Pfad für die Region des Kunden.
Obwohl Sie eine einzige logische Tabelle für region und eine einzige logische Tabelle für nation verwenden können, sollten Sie separate logische Tabellen für die Region des Anbieters, die Region des Kunden, das Land des Anbieters und das Land des Kunden definieren:
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),
...
)
Definieren Sie dann separate Beziehungen, die die verschiedenen Pfade darstellen:
RELATIONSHIPS (
supplier_nation (n_regionkey) REFERENCES supplier_region,
customer_nation (n_regionkey) REFERENCES customer_region,
...
)
Identifizierung der Beziehungen zwischen logischen Tabellen¶
Verwenden Sie im Befehl CREATE SEMANTIC VIEW die Klausel RELATIONSHIPS, um die Beziehungen zwischen den Tabellen in der Ansicht zu identifizieren. Für jede Beziehung geben Sie an:
Einen optionalen Namen für die Beziehung.
Den Namen der logischen Tabelle, die den Fremdschlüssel enthält.
Die Spalten in dieser Tabelle, die den Fremdschlüssel definieren.
Den Namen der logischen Tabelle, die den Primärschlüssel oder Spalten mit eindeutigen Werten enthält.
Die Spalten in dieser Tabelle, die den Primärschlüssel definieren oder eindeutige Werte enthalten.
Wenn Sie in der Klausel TABLES bereits PRIMARY KEY für die logische Tabelle angegeben haben, müssen Sie die Primärschlüsselspalte in der Beziehung nicht angeben.
Wenn es in der Klausel TABLES ein einziges UNIQUE-Schlüsselwort für die logische Tabelle gibt, müssen Sie die entsprechenden Spalten in der Beziehung nicht angeben.
In dem zuvor vorgestellten Beispiel gibt die Klausel RELATIONSHIPS zwei Beziehungen an:
Eine Beziehung zwischen den Tabellen
ordersundcustomers. In der Tabelleordersisto_custkeyder Fremdschlüssel, der sich auf den Primärschlüssel in der Tabellecustomers(c_custkey) bezieht.Eine Beziehung zwischen den Tabellen
line_itemsundorders. In der Tabelleline_itemsistl_orderkeyder Fremdschlüssel, der sich auf den Primärschlüssel in der Tabelleorders(o_orderkey) bezieht.
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)
)
Definition von Fakten, Dimensionen und Metriken¶
Verwenden Sie im Befehl CREATE SEMANTIC VIEW die Klauseln FACTS, DIMENSIONS und METRICS, um die Fakten, Dimensionen und Metriken in der semantischen Ansicht zu definieren.
Sie müssen mindestens eine Dimension oder Metrik in der semantischen Ansicht definieren.
Für jeden Fakt, jede Dimension oder Metrik, geben Sie an:
Die logische Tabelle, zu der sie gehört.
Einen Namen für den Fakt, die Dimension oder die Metrik.
Den SQL-Ausdruck, um ihn zu berechnen.
Optionale Synonyme und Kommentare.
Das zuvor vorgestellte Beispiel definiert mehrere Fakten, Dimensionen und Metriken:
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'
)
Bemerkung
Weitere Richtlinien zum Definieren von Metriken, die Fensterfunktionen verwenden, finden Sie unter Fensterfunktionsmetriken definieren und abfragen.
Tatsache oder Metrik als privat markieren¶
Wenn Sie einen Fakt oder eine Kennzahl nur zur Verwendung in Berechnungen in der semantischen Ansicht definieren und nicht möchten, dass der Fakt oder die Kennzahl in einer Abfrage zurückgegeben werden, können Sie das Schlüsselwort PRIVATE angeben, um die Tatsache oder Kennzahl als privat zu markieren. Beispiel:
FACTS (
PRIVATE my_private_fact AS ...
)
METRICS (
PRIVATE my_private_metric AS ...
)
Bemerkung
Sie können eine Dimension nicht als privat markieren. Dimensionen sind immer öffentlich.
Wenn Sie eine semantische Ansicht abfragen, die private Fakten oder Metriken enthält, können Sie in den folgenden Klauseln keine privaten Fakten oder Metriken angeben:
Die SELECT-Liste
FACTS in der SEMANTIC_VIEW-Klausel
METRICS in der SEMANTIC_VIEW-Klausel
METRICS
WHERE in der SELECT-Anweisung oder SEMANTIC_VIEW-Klausel
Einige Befehle und Funktionen beinhalten private Fakten und Kennzahlen:
Private Fakten und Kennzahlen werden nicht in der Ausgabe des DESCRIBE SEMANTIC VIEW-Befehls angezeigt. Die Zeilen für private Fakten und Metriken zeigen
PRIVATEin deraccess_modifier-Spalte.Private Fakten und Metriken werden im Rückgabewert eines GET_DDL-Funktionsaufrufs aufgeführt, wie unter Abrufen der SQL-Anweisung für eine semantische Ansicht erwähnt.
Einige Befehle und Funktionen enthalten private Fakten und Metriken nur unter bestimmten Bedingungen:
Private Fakten und Metriken sind unter INFORMATION_SCHEMA SEMANTIC_FACTS und SEMANTIC_METRICS-Ansichten aufgeführt. Dies gilt nur, wenn Sie eine Rolle verwenden, die die Berechtigung gewährt hat fürREFERENCES oder OWNERSHIP. Diese muss für die semantische Ansicht gelten.
Andernfalls werden in diesen Ansichten nur die öffentlichen Fakten und Metriken aufgelistet.
Andere Befehle und Funktionen enthalten keine privaten Fakten und Metriken:
Private Metriken werden nicht in der Ausgabe des Befehls SHOW SEMANTIC METRICS angezeigt.
Semantischen Ansicht aus einer YAML-Spezifikation erstellen¶
Erstellen einer semantischen Ansicht aus einer YAML-Spezifikation für ein semantisches Modell:. Rufen Sie dazu den gespeicherten Prozess SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML auf.
Übergeben Sie zuerst TRUE als drittes Argument, um zu verifizieren, ob Sie die semantische Ansicht aus derYAML-Spezifikation erstellen können.
Das folgende Beispiel bestätigt, dass Sie eine bestimmte Spezifikation eines semantischen Modells in YAML verwenden können, um eine semantische Ansicht namens tpch_analysis in der Datenbank my_db und im Schema my_schema zu erstellen:
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);
Wenn die Spezifikation gültig ist, gibt die gespeicherte Prozedur die folgende Meldung zurück:
+----------------------------------------------------------------------------------+
| SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML |
|----------------------------------------------------------------------------------|
| YAML file is valid for creating a semantic view. No object has been created yet. |
+----------------------------------------------------------------------------------+
Wenn die YAML-Syntax ungültig ist, löst die gespeicherte Prozedur eine Ausnahme aus. Wenn zum Beispiel ein Doppelpunkt fehlt:
relationships
- name: LINE_ITEM_TO_ORDERS
Die gespeicherte Prozedur löst eine Ausnahme aus, die anzeigt, dass die YAML-Syntax ungültig ist:
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
^
Wenn sich die Spezifikation auf eine physische Tabelle bezieht, die nicht existiert, löst die gespeicherte Prozedur eine Ausnahme aus:
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.
In ähnlicher Weise löst der gespeicherte Prozess eine Ausnahme aus, wenn sich die Spezifikation auf eine Primärschlüsselspalte bezieht, die nicht existiert:
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'
Sie können dann den gespeicherten Prozess aufrufen, ohne das dritte Argument zu übergeben, um die semantische Ansicht zu erstellen.
Im folgenden Beispiel wird eine semantische Ansicht namens tpch_analysis in der Datenbank my_db und im Schema my_schema erstellt:
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. |
+-----------------------------------------+
Kommentar für eine bestehende semantische Ansicht ändern¶
Um den Kommentar für eine bestehende semantische Ansicht zu ändern, führen Sie den Befehl ALTER SEMANTIC VIEW aus. Beispiel:
ALTER SEMANTIC VIEW my_semantic_view SET COMMENT = 'my comment';
Bemerkung
Sie können den Befehl ALTER SEMANTIC VIEW verwenden, um andere Eigenschaften als den Kommentar zu ändern. Um andere Eigenschaften der semantischen Ansicht zu ändern, ersetzen Sie die semantische Ansicht. Siehe Ersetzen einer bestehenden semantischen Ansicht.
Sie können auch den Befehl COMMENT verwenden, um einen Kommentar für eine semantische Ansicht festzulegen:
COMMENT ON SEMANTIC VIEW my_semantic_view IS 'my comment';
Ersetzen einer bestehenden semantischen Ansicht¶
Um eine bestehende semantische Ansicht zu ersetzen (z. B. um die Definition der Ansicht zu ändern), geben Sie OR REPLACE an, wenn Sie CREATE SEMANTIC VIEW ausführen. Wenn Sie die Berechtigungen für die bestehende semantische Ansicht beibehalten wollen, geben Sie COPY GRANTS an. Beispiel:
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;
Auflistung semantischer Ansichten¶
Um semantische Ansichten im aktuellen Schema oder einem bestimmten Schema aufzulisten, führen Sie den Befehl SHOW SEMANTIC VIEWS aus. Beispiel:
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 |
+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+
Sie können auch die Ansichten für semantische Ansichten in den Schemas ACCOUNT_USAGE und INFORMATION_SCHEMA abfragen.
Dimensionen und Metriken aufführen¶
Um die Dimensionen und Metriken aufzulisten, die in einer Ansicht, einem Schema, einer Datenbank oder einem Konto verfügbar sind, können Sie die Befehle SHOW SEMANTIC DIMENSIONS und SHOW SEMANTIC METRICS ausführen.
Standardmäßig listen die Befehle die Dimensionen und Metriken auf, die in semantischen Ansichten verfügbar sind, die im aktuellen Schema definiert sind:
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 |
...
Sie können den Bereich ändern, um die im Folgenden definierten Dimensionen und Metriken aufzulisten:
Semantische Ansichten in der aktuellen Datenbank:
SHOW SEMANTIC DIMENSIONS IN DATABASE; SHOW SEMANTIC METRICS IN DATABASE;
Semantische Ansichten in bestimmten Schemas oder Datenbanken.
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;
Semantische Ansichten im Konto.
SHOW SEMANTIC DIMENSIONS IN ACCOUNT; SHOW SEMANTIC METRICS IN ACCOUNT;
Eine bestimmte semantische Ansicht:
SHOW SEMANTIC DIMENSIONS IN my_semantic_view;
Wenn Sie eine semantische Ansicht abfragen, können Sie den Befehl SHOW SEMANTIC DIMENSIONS FOR METRIC verwenden, um zu bestimmen, welche Dimensionen Sie bei Angabe einer bestimmten Kennzahl zurückgeben können. Weitere Details dazu finden Sie unter Auswahl der Dimensionen, die Sie für eine bestimmte Metrik zurückgeben können.
Details zu einer semantischen Ansicht anzeigen¶
Um die Details einer semantischen Ansicht anzuzeigen, führen Sie den Befehl DESCRIBE SEMANTIC VIEW aus. Beispiel:
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 |
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
Abrufen der SQL-Anweisung für eine semantische Ansicht¶
Sie können die Funktion GET_DDL aufrufen, um die DDL-Anweisung abzurufen, mit der eine semantische Ansicht erstellt wurde.
Bemerkung
Um diese Funktion für eine semantische Ansicht aufzurufen, müssen Sie eine Rolle verwenden, der die folgenden Berechtigungen gewährt wurden: REFERENCES oder OWNERSHIP. Dies muss in der semantischen Ansicht erfolgen.
Wenn Sie GET_DDL aufrufen, geben Sie 'SEMANTIC_VIEW' als Objekttyp an. Beispiel:
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' |
| ); |
+-----------------------------------------------------------------------------------+
Der Rückgabewert enthält private Fakten und Metriken (Fakten und Metriken, die mit dem Schlüsselwort PRIVATE markiert sind).
YAML-Spezifikation für eine semantische Ansicht abrufen¶
Um die YAML-Spezifikation für ein semantisches Modell für eine semantische Ansicht zu erhalten, rufen Sie die Funktion SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW auf.
Das folgende Beispiel gibt die YAML-Spezifikation für die semantische Ansicht namens``tpch_analysis`` in der Datenbank my_db und im Schema my_schema zurück:
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 |
| |
+-------------------------------------------------------------+
Entfernen einer semantischen Ansicht¶
Um eine semantische Ansicht zu entfernen, führen Sie den Befehl DROP SEMANTIC VIEW aus. Beispiel:
DROP SEMANTIC VIEW tpch_rev_analysis;
Erteilung von Berechtigungen für semantische Ansichten¶
Berechtigungen für semantische Ansichten listet die Berechtigungen auf, die Sie für eine semantische Ansicht gewähren können.
Die folgenden Berechtigungen für eine semantische Ansicht sind erforderlich, um mit der Ansicht zu arbeiten:
Jede Berechtigung (z. B. REFERENCES OR SELECT) muss den Befehl DESCRIBE SEMANTIC VIEW in der Ansicht ausführen.
SELECT ist erforderlich, um
SELECT ... FROM SEMANTIC_VIEW()auszuführen.Eine dieser beiden Berechtigungen ist erforderlich, um die Ansicht in der Ausgabe des Befehls SHOW SEMANTIC VIEWS anzuzeigen.
Bemerkung
Um eine semantische Ansicht abzufragen, benötigen Sie die SELECT-Berechtigung für die in der semantischen Ansicht verwendeten Tabellen nicht. Sie benötigen die SELECT-Berechtigung nur für die semantische Ansicht selbst.
Dieses Verhalten ist konsistent mit den Berechtigungen, die zum Abfragen von Standardansichten erforderlich sind.
Um eine semantische Ansicht zu verwenden, die Sie nicht in Cortex Analyst besitzen, müssen Sie eine Rolle verwenden, die über die Berechtigungen REFERENCES und SELECT für diese Ansicht verfügt.
Um die Berechtigungen REFERENCES und SELECT für eine semantische Ansicht zu erteilen, verwenden Sie den Befehl GRANT <Berechtigungen> … TO ROLE. Um beispielsweise der Rolle my_analyst_role die Berechtigungen REFERENCES und SELECT für die semantische Ansicht mit dem Namen my_semantic_view zu gewähren, können Sie die folgende Anweisung ausführen:
GRANT REFERENCES, SELECT ON SEMANTIC VIEW my_semantic_view TO ROLE my_analyst_role;
Wenn Sie ein Schema haben, das semantische Ansichten enthält, die Sie mit Cortex Analyst-Benutzern gemeinsam nutzen möchten, können Sie zukünftige Berechtigungen verwenden, um die Berechtigungen für jede semantische Ansicht zu gewähren, die Sie in diesem Schema erstellen. Beispiel:
GRANT REFERENCES, SELECT ON FUTURE SEMANTIC VIEWS IN SCHEMA my_schema TO ROLE my_analyst_role;