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:
Este tópico também explica como chamar o seguinte procedimento armazenado e função para criar uma exibição semântica de uma especificação do modelo semântico e obter a especificação para uma exibição semântica:
Privilégios necessários para criar uma exibição semântica¶
Para criar uma exibição semântica, 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.
Para obter informações sobre os privilégios necessários para consultar uma exibição semântica, confira Privilégios necessários para consultar uma exibição semântica.
Criação de uma exibição semântica¶
Para criar uma exibição semântica, faça o seguinte:
Execute o comando CREATE SEMANTIC VIEW.
Chame o procedimento armazenado SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML, se quiser criar uma exibição semântica a partir da especificação YAML de um modelo semântico.
A exibição semântica deve ser válida. Consulte Como o Snowflake valida as exibições semânticas.
As próximas seções explicam como criar uma exibição semântica:
Uso do comando CREATE SEMANTIC VIEW¶
O exemplo a seguir usa o comando CREATE SEMANTIC VIEW para criar uma exibição semântica.
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 de negócios 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.
Nota
Se houver várias maneiras pelas quais duas tabelas possam ser unidas, você deverá definir uma tabela lógica separada para cada uma delas. Para obter mais informações, consulte Definição de tabelas lógicas diferentes para caminhos distintos que unem duas tabelas.
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'
Definição de tabelas lógicas diferentes para caminhos distintos que unem duas tabelas¶
Se houver vários caminhos que você possa usar para unir duas tabelas físicas, defina tabelas lógicas e relacionamentos separados para cada caminho.
Por exemplo, no dados de amostra TPC-H disponíveis no Snowflake, há duas maneiras possíveis de unir as tabelas region e lineitem:
region->nation->supplier->partsupp->lineitemregion->nation->customer->orders->lineitem
O primeiro caminho representa a região do fornecedor, e o segundo representa a região do cliente.
Você pode usar uma única tabela lógica para region e uma única tabela lógica para nation, mas deve definir tabelas lógicas separadas para a região do fornecedor, a região do cliente, o país do fornecedor e o país do cliente:
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),
...
)
Em seguida, defina relacionamentos separadas que representem os diferentes caminhos:
RELATIONSHIPS (
supplier_nation (n_regionkey) REFERENCES supplier_region,
customer_nation (n_regionkey) REFERENCES customer_region,
...
)
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'
)
Nota
Para ver mais diretrizes sobre a definição de métricas que usam funções de janela, consulte Definição e consulta de métricas de função de janela.
Marcação de fato ou métrica como privado¶
Se você estiver definindo um fato ou métrica apenas para uso em cálculos na exibição semântica e não quiser que o fato ou métrica seja retornado em uma consulta, poderá especificar a palavra-chave PRIVATE para marcar o fato ou métrica como privado. Por exemplo:
FACTS (
PRIVATE my_private_fact AS ...
)
METRICS (
PRIVATE my_private_metric AS ...
)
Nota
Você não pode marcar uma dimensão como privada. As dimensões são sempre públicas.
Ao consultar uma exibição semântica com fatos ou métricas privados, você não pode especificar um fato ou uma métrica privada nas seguintes cláusulas:
A lista SELECT
FACTS na cláusula SEMANTIC_VIEW
METRICS na cláusula SEMANTIC_VIEW
METRICS
WHERE na instrução SELECT ou na cláusula SEMANTIC_VIEW
Alguns comandos e funções incluem fatos e métricas privados:
Os fatos e as métricas privados aparecem na saída do comando DESCRIBE SEMANTIC VIEW. As linhas de fatos e métricas privados têm
PRIVATEna colunaaccess_modifier.Os fatos e as métricas privados são listados no valor de retorno de uma chamada de função GET_DDL, como indicado em Obtenção da instrução SQL para uma exibição semântica.
Alguns comandos e funções incluem fatos e métricas privados somente em condições específicas:
Os fatos e métricas privados serão listados nas exibições INFORMATION_SCHEMA SEMANTIC_FACTS e SEMANTIC_METRICS somente se você usar uma função que tenha recebido o privilégio REFERENCES ou OWNERSHIP na exibição semântica.
Caso contrário, essas exibições listarão apenas os fatos e métricas públicos.
Outros comandos e funções não incluem fatos e métricas privados:
As métricas privadas não aparecem na saída do comando SHOW SEMANTIC METRICS.
Criação de exibição semântica de uma especificação YAML¶
Para criar uma exibição semântica de uma especificação YAML para um modelo semântico, você pode chamar o procedimento armazenado SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML.
Primeiro, passe TRUE como terceiro argumento para verificar se você pode criar a exibição semântica da especificação YAML.
O seguinte exemplo verifica se você pode usar uma determinada especificação de modelo semântico em YAML para criar uma exibição semântica chamada tpch_analysis no banco de dados my_db e no esquema my_schema:
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);
Se a especificação for válida, o procedimento armazenado retornará a seguinte mensagem:
+----------------------------------------------------------------------------------+
| SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML |
|----------------------------------------------------------------------------------|
| YAML file is valid for creating a semantic view. No object has been created yet. |
+----------------------------------------------------------------------------------+
Se a sintaxe YAML é inválida, o procedimento armazenado gera uma exceção. Por exemplo, se faltar dois pontos:
relationships
- name: LINE_ITEM_TO_ORDERS
o procedimento armazenado gera uma exceção, indicando que a sintaxe YAML é inválida:
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
^
Se a especificação se referir a uma tabela física que não existe, o procedimento armazenado vai gerar uma exceção:
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.
Da mesma forma, se a especificação se referir a uma coluna de chave primária que não existe, o procedimento armazenado vai gerar uma exceção:
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'
Em seguida, você pode chamar o procedimento armazenado sem passar o terceiro argumento para criar a exibição semântica.
O seguinte exemplo cria uma exibição semântica chamada tpch_analysis no banco de dados my_db e no esquema my_schema:
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. |
+-----------------------------------------+
Modificação do comentário para uma exibição semântica existente¶
Para modificar o comentário de uma exibição semântica existente, execute o comando ALTER SEMANTIC VIEW. Por exemplo:
ALTER SEMANTIC VIEW my_semantic_view SET COMMENT = 'my comment';
Nota
Não é possível usar o comando ALTER SEMANTIC VIEW para alterar propriedades diferentes do que o comentário. Para alterar outras propriedades da exibição semântica, substitua a exibição semântica. Consulte Substituição de uma exibição semântica existente.
Você também pode usar o comando COMMENT para definir um comentário para uma exibição semântica:
COMMENT ON SEMANTIC VIEW my_semantic_view IS 'my comment';
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.
Listagem de dimensões e métricas¶
Para listar as dimensões e métricas disponíveis em uma exibição, um esquema, um banco de dados ou uma conta, você pode executar os comandos SHOW SEMANTIC DIMENSIONS e SHOW SEMANTIC METRICS.
Por padrão, os comandos listam as dimensões e métricas disponíveis nas exibições semânticas definidas no esquema atual:
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 |
...
É possível alterar o escopo para listar as dimensões e métricas definidas em:
Exibições semânticas no banco de dados atual:
SHOW SEMANTIC DIMENSIONS IN DATABASE; SHOW SEMANTIC METRICS IN DATABASE;
Exibições semânticas em esquemas ou bancos de dados específicos.
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;
Exibições semânticas na conta.
SHOW SEMANTIC DIMENSIONS IN ACCOUNT; SHOW SEMANTIC METRICS IN ACCOUNT;
Uma exibição semântica específica:
SHOW SEMANTIC DIMENSIONS IN my_semantic_view;
Se você estiver consultando uma exibição semântica, poderá usar o comando SHOW SEMANTIC DIMENSIONS FOR METRIC para determinar quais dimensões você pode retornar ao especificar uma determinada métrica. Para obter mais detalhes, consulte Escolha das dimensões que você pode retornar para uma determinada métrica.
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.
Nota
Para chamar essa função para uma exibição semântica, você deve usar uma função que tenha recebido o privilégio REFERENCES ou OWNERSHIP na 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' |
| ); |
+-----------------------------------------------------------------------------------+
O valor de retorno inclui fatos e métricas privados (fatos e métricas marcados com a palavra-chave PRIVATE).
Como obter a especificação YAML para uma exibição semântica¶
Para obter a especificação YAML de um modelo semântico para uma exibição semântica, chame a função SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW.
O seguinte exemplo retorna a especificação YAML para a exibição semântica chamada tpch_analysis no banco de dados my_db e no esquema my_schema:
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 |
| |
+-------------------------------------------------------------+
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, REFERENCES OR SELECT) é necessário para executar o comando DESCRIBE SEMANTIC VIEW na exibiçã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
Para consultar uma exibição semântica, você não precisa do privilégio SELECT nas tabelas usadas na exibição semântica. Você só precisa do privilégio SELECT na própria exibição semântica.
Esse comportamento é consistente com os privilégios necessários para consultar exibições padrão.
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;