Utilização dos comandos SQL para criar e gerenciar exibições semânticas¶
Este tópico explica como usar os seguintes comandos SQL para criar e gerenciar exibições semânticas.
Criação de uma exibição semântica¶
Para criar uma exibição semântica, execute o comando CREATE SEMANTIC VIEW. Você deve usar uma função com os seguintes privilégios:
CREATE SEMANTIC VIEW no esquema em que você está criando a exibição semântica.
USAGE no banco de dados e no esquema em que você está criando a exibição semântica.
SELECT nas tabelas e visualizações usadas na exibição semântica.
A exibição semântica deve ser válida. Consulte Como o Snowflake valida as exibições semânticas.
O exemplo usa os dados de amostra TPC-H disponíveis no Snowflake. Esse conjunto de dados contém tabelas que representam um cenário comercial simplificado com clientes, pedidos e itens de linha.
O exemplo cria uma exibição semântica chamada tpch_rev_analysis, usando as tabelas do conjunto de dados TPC-H. A exibição semântica define:
Três tabelas lógicas (
orders,customerseline_items).Uma relação entre as tabelas
ordersecustomers.Uma relação entre as tabelas
line_itemseorders.Fatos que serão usados para calcular as métricas.
Dimensões para o nome do cliente, a data do pedido e o ano em que o pedido foi feito.
Métricas para o valor médio de um pedido e o número médio de itens de linha em um pedido.
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';
As próximas seções explicam esse exemplo em mais detalhes:
Nota
Para obter um exemplo completo, consulte Exemplo de uso do SQL para criar uma exibição semântica.
Definição das tabelas lógicas¶
No comando CREATE SEMANTIC VIEW, use a cláusula TABLES para definir as tabelas lógicas na visualização. Nessa cláusula, você pode:
Especificar o nome da tabela física e um alias opcional.
Identificar as seguintes colunas na tabela lógica:
Colunas que servem como chaves primárias.
Colunas que contêm valores exclusivos (que não sejam colunas de chave primária).
Você pode usar essas colunas para definir relações nessa exibição semântica.
Adicionar sinônimos para a tabela (para melhorar a capacidade de descoberta).
Incluir um comentário descritivo.
No exemplo apresentado anteriormente, a cláusula TABLES define três tabelas lógicas:
Uma tabela
orderscontendo as informações do pedido da tabela TPC-Horders.Uma tabela
customerscontendo as informações do cliente da tabela TPC-Hcustomers.Uma tabela
line_itemcontendo os itens de linha em pedidos da tabela TPC-Hlineitem.
O exemplo identifica as colunas a serem usadas como chaves primárias para cada tabela lógica para que você possa identificar as relações entre as tabelas.
O exemplo também fornece sinônimos e comentários que descrevem as tabelas lógicas e facilitam a descoberta dos dados.
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'
Identificar as relações entre as tabelas lógicas¶
No comando CREATE SEMANTIC VIEW, use a cláusula RELATIONSHIPS para identificar as relaçõe entre as tabelas na visualização. Para cada relação, você especifica:
Um nome opcional para a relação.
O nome da tabela lógica que contém a chave estrangeira.
As colunas dessa tabela que definem a chave estrangeira.
O nome da tabela lógica que contém a chave primária ou as colunas com valores exclusivos.
As colunas dessa tabela que definem a chave primária ou que contêm valores exclusivos.
Se você já tiver especificado PRIMARY KEY para a tabela lógica na cláusula TABLES, não precisará especificar a coluna de chave primária na relação.
Se houver uma única palavra-chave UNIQUE para a tabela lógica na cláusula TABLES, você não precisará especificar as colunas correspondentes na relação.
No exemplo apresentado anteriormente, a cláusula RELATIONSHIPS especifica duas relações:
Uma relação entre as tabelas
ordersecustomers. Na tabelaorders,o_custkeyé a chave estrangeira que se refere à chave primária na tabelacustomers(c_custkey).Uma relação entre as tabelas
line_itemseorders. Na tabelaline_items,l_orderkeyé a chave estrangeira que se refere à chave primária na tabelaorders(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)
)
Definição de fatos, dimensões e métricas¶
No comando CREATE SEMANTIC VIEW, use as cláusulas FACTS, DIMENSIONS e METRICS para definir os fatos, as dimensões e as métricas na exibição semântica.
Você deve definir pelo menos uma dimensão ou métrica na exibição semântica.
Para cada fato, dimensão ou métrica, você deve especificar:
A tabela lógica à qual pertence.
Um nome para o fato, a dimensão ou a métrica.
A expressão SQL para calculá-lo.
Sinônimos e comentários opcionais.
O exemplo apresentado anteriormente define vários fatos, dimensões e métricas:
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'
)
Substituição de uma exibição semântica existente¶
Para substituir uma exibição semântica existente (por exemplo, para alterar a definição da exibição), especifique OR REPLACE ao executar CREATE SEMANTIC VIEW. Se você quiser preservar os privilégios concedidos na exibição semântica existente, especifique COPY GRANTS. Por exemplo:
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;
Listagem de exibições semânticas¶
Para listar as exibições semânticas no esquema atual ou em um esquema especificado, execute o comando SHOW SEMANTIC VIEWS. Por exemplo:
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 |
+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+
Você também pode consultar as exibições de exibições semânticas nos esquemas ACCOUNT_USAGE e INFORMATION_SCHEMA.
Exibição dos detalhes sobre uma exibição semântica¶
Para visualizar os detalhes de uma exibição semântica, execute o comando DESCRIBE SEMANTIC VIEW. Por exemplo:
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 |
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
Obtenção da instrução SQL para uma exibição semântica¶
Você pode chamar a função GET_DDL para recuperar a instrução DDL que criou uma exibição semântica.
Ao chamar GET_DDL, passe 'SEMANTIC_VIEW' como o tipo de objeto. Por exemplo:
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' |
| ); |
+-----------------------------------------------------------------------------------+
Remoção de uma exibição semântica¶
Para remover uma exibição semântica, execute o comando DROP SEMANTIC VIEW. Por exemplo:
DROP SEMANTIC VIEW tpch_rev_analysis;
Concessão de privilégios em exibições semânticas¶
Privilégios de exibição semântica lista os privilégios que você pode conceder em uma exibição semântica.
Os seguintes privilégios em uma exibição semântica são necessários para trabalhar com a exibição:
Qualquer privilégio (por exemplo, REFERENCE OR SELECT) é necessário para executar o comando DESCRIBE SEMANTIC VIEW na visualização.
SELECT é necessário para executar
SELECT ... FROM SEMANTIC_VIEW().Qualquer um desses privilégios é necessário para exibir a visualização na saída do comando SHOW SEMANTIC VIEWS.
Nota
Atualmente, o privilégio REFERENCES permite que você consulte uma exibição semântica, mas, no futuro, a capacidade de consultar uma exibição semântica será restrita a funções com o privilégio SELECT.
Para usar uma exibição semântica que não é de sua propriedade no Cortex Analyst, você deve usar uma função que tenha os privilégios REFERENCES e SELECT nessa exibição.
Para conceder os privilégios REFERENCES e SELECT em uma exibição semântica, use o comando GRANT <privilégios> … TO ROLE. Por exemplo, para conceder os privilégios REFERENCES e SELECT na exibição semântica denominada my_semantic_view à função my_analyst_role, você pode executar a seguinte instrução:
GRANT REFERENCES, SELECT ON SEMANTIC VIEW my_semantic_view TO ROLE my_analyst_role;
Se tiver um esquema contendo exibições semânticas que deseja compartilhar com usuários Cortex Analyst, você pode usar concessões futuras para conceder os privilégios para qualquer exibição semântica criada nesse esquema. Por exemplo:
GRANT REFERENCES, SELECT ON FUTURE SEMANTIC VIEWS IN SCHEMA my_schema TO ROLE my_analyst_role;