Práticas recomendadas para exibições semânticas¶

Propriedade e acesso aos dados¶

As exibições semânticas facilitam o acesso às informações que existem em diversas fontes de dados canônicas. A camada semântica permite mudar o foco da consulta de uma fonte de dados específica para os casos de uso e as questões comerciais com a ajuda de uma exibição unificada dos dados disponíveis. Com esse objetivo geral em mente, as equipes comerciais e de engenharia de dados devem trabalhar juntas. As equipes comerciais têm experiência nos casos comerciais, enquanto as equipes de engenharia de dados sabem como acessar os dados de tabelas e exibições. Ambas as equipes precisam compartilhar a propriedade do modelo semântico.

Para proteger a camada semântica de forma que atenda às necessidades das duas equipes, use o controle de acesso baseado em função (Role-Based Access Control, RBAC) para conceder privilégios apropriados a exibições semânticas e seus objetos dependentes. Se você está começando do zero, pode usar a sequência de instruções GRANT na próxima seção como um modelo de trabalho. Entretanto, se os membros da sua equipe já tiverem permissões configuradas de uma determinada maneira para ambientes de desenvolvimento, teste e produção, talvez seja necessário fazer algumas alterações ou orientá-los a usar funções diferentes conforme necessário.

-- Set variables for the specified role, database, and schema
SET my_role = 'snowflake_intelligence_sales_analysis_role';
SET my_db = 'sales';
SET my_schema = 'sales_analysis';
SET my_full_schema = $my_db || '.' || $my_schema;

-- Grant usage on the database and schema that will contain the tables and views
GRANT USAGE ON DATABASE IDENTIFIER($my_db) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);

-- Grant privileges on future objects within the schema
-- For tables and views, SELECT is the typical "usage" grant for read access
GRANT SELECT ON FUTURE TABLES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT SELECT ON FUTURE VIEWS IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT SELECT ON FUTURE SEMANTIC VIEWS IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);

-- For other object types, USAGE is the correct privilege
GRANT USAGE ON FUTURE FUNCTIONS IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON FUTURE PROCEDURES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON FUTURE STAGES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON FUTURE CORTEX SEARCH SERVICES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);

-- Grant usage on the database and schema that will contain the tables and views
GRANT USAGE ON DATABASE IDENTIFIER($my_db) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);

-- Grant privileges on future objects within the schema
-- For tables and views, SELECT is the typical "usage" grant for read access
GRANT SELECT ON FUTURE TABLES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT SELECT ON FUTURE VIEWS IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT SELECT ON FUTURE SEMANTIC VIEWS IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);

-- For other object types, USAGE is the correct privilege
GRANT USAGE ON FUTURE FUNCTIONS IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON FUTURE PROCEDURES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON FUTURE STAGES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);
GRANT USAGE ON FUTURE CORTEX SEARCH SERVICES IN SCHEMA IDENTIFIER($my_full_schema) TO ROLE IDENTIFIER($my_role);

-- Row access policy (restricts rows by user email)
CREATE OR REPLACE ROW ACCESS POLICY my_schema.account_row_policy AS (user_email STRING)
  RETURNS BOOLEAN ->
    EXISTS (
      SELECT 1
      FROM my_schema.account_access_list
      WHERE email = user_email()
    );

-- Masking policy (masks "sensitive_col" for users without a privileged role)
CREATE OR REPLACE MASKING POLICY my_schema.sensitive_col_masking_policy AS (val STRING)
RETURNS STRING ->
  CASE
    WHEN current_role() IN ('SENSITIVE_DATA_ACCESS_ROLE') THEN val
    ELSE 'MASKED'
  END;

-- Attach row access policy to the user_email column in the accounts table
ALTER TABLE my_schema.accounts
  ADD ROW ACCESS POLICY account_row_policy ON (user_email);

-- Attach masking policy to the sensitive_col column
ALTER TABLE my_schema.accounts
  MODIFY COLUMN sensitive_col
  SET MASKING POLICY sensitive_col_masking_policy;

-- Create the semantic view on the "accounts" table
CREATE OR REPLACE SEMANTIC VIEW my_schema.account_semantic_view
  TABLES (
    accounts AS my_schema.accounts
    PRIMARY KEY (account_id)
  )
  FACTS (
    account_id AS accounts.account_id,
    account_name AS accounts.account_name
  )
  DIMENSIONS (
    user_email AS accounts.user_email,
    sensitive_col AS accounts.sensitive_col
);

models:
- name: accounts
  description: "Table of accounts for semantic analytics."
  columns:
    - name: account_id
      description: "Unique identifier for the account."
    - name: account_name
      description: "Name of the account."
    - name: user_email
      description: "Email address linked to each account row."
    - name: sensitive_col
      description: "Sensitive information to be masked for non-privileged users."
  post-hook:
    - >
      ALTER TABLE {{ this }}
        ADD ROW ACCESS POLICY account_row_policy ON (user_email);
  ...

SELECT GET_DDL('SEMANTIC_VIEW','TEST_SAMPLE_VALUES');

create or replace semantic view TEST_SAMPLE_VALUES
tables (MARCH_TEMPS
  ...)
facts (MARCH_TEMPS.TEMPERATURE as TEMPERATURE
  ...)
dimensions (MARCH_TEMPS.CITY as CITY,
MARCH_TEMPS.COUNTY as COUNTY,
MARCH_TEMPS.OBSERVED as OBSERVED)
  ...
with extension (CA='{"tables":[{"name":"MARCH_TEMPS","dimensions":[{"name":"CITY","sample_values":["South Lake Tahoe","Big Bear City"]},{"name":"COUNTY","sample_values":["San Bernardino","El Dorado"]}],"facts":[{"name":"TEMPERATURE","sample_values":["44","46","52"]}],"time_dimensions":[{"name":"OBSERVED","sample_values":["2025-03-15T09:50:00.000+0000","2025-03-15T09:55:00.000+0000","2025-03-15T10:10:00.000+0000"]}]}
...);

Opções para criar, atualizar e consultar exibições semânticas¶

Você pode criar exibições semânticas no Snowflake escrevendo um arquivo YAML, usando a sintaxe Snowflake DDL ou a UI no Snowsight. O Snowflake oferece funções práticas tanto para importar modelos YAML quanto para exportar exibições semânticas para modelos YAML. Para obter mais detalhes, consulte Conversão de modelos semânticos YAML em exibições semânticas nativas.

Em geral, é melhor começar criando exibições semânticas (em vez de modelos semânticos), que são objetos de metadados do Snowflake que usam o RBAC, as estatísticas de uso e a integração direta com outros recursos do Snowflake, como Cortex Analyst e Snowflake Intelligence.

Para criar uma exibição semântica, você tem três opções principais:

• Criar uma exibição semântica no Snowsight:

  • Você pode usar o assistente ou carregar uma especificação YAML.

  • A abordagem do assistente é recomendada para configuração inicial e inclui a criação automática de sinônimos, valores de amostra e descrições de colunas. Para obter instruções, consulte Uso da Snowsight para criar e gerenciar exibições semânticas.

• Criar uma exibição semântica por meio de uma instrução SQL CREATE OR REPLACE SEMANTIC VIEW, usando qualquer interface compatível com SQL. Para obter instruções, consulte Utilização dos comandos SQL para criar e gerenciar exibições semânticas.

  A criação e a consulta programáticas são possíveis por meio de interfaces como os drivers JDBC e ODBC ou a SQL API. No entanto, você não pode usar as Snowflake REST APIs.

• Criar uma exibição semântica de uma especificação YAML em SQL chamando o procedimento armazenado SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML. Consulte Conversão de modelos semânticos YAML em exibições semânticas nativas.

Além disso, se você usa o dbt, pode configurar a criação de exibições semânticas no Snowflake instalando o pacote dbt_semantic_view. Para obter mais informações, consulte Integração com projetos dbt.

Tenha em mente que a configuração de funções e privilégios para os membros da sua equipe pode ter um impacto na capacidade deles de criar exibições semânticas. Por exemplo, se o seu ambiente de produção exige a execução como usuário SERVICE, você não pode fazer login no Snowsight nesse ambiente. Você deve usar comandos SQL para criar e gerenciar exibições semânticas.

Quando as exibições semânticas são criadas em um banco de dados do Snowflake, os administradores podem gerenciá-las usando os comandos padrão SHOW e DESCRIBE, e os usuários podem acessá-las posteriormente por meio das instruções SQL SELECT e das seguintes maneiras:

• Diretamente pela interface de usuário do Cortex Analyst

• Por meio do Streamlit ou de outros aplicativos personalizados que usam a Cortex Analyst API e/ou geram instruções SELECT FROM SEMANTIC_VIEW

• Por meio dos Cortex Agents no Cortex Analyst (exibições semânticas devem ser adicionadas a um agente novo ou existente)

Exceto para comentários, não é possível adicionar ou alterar tabelas, colunas ou metadados nas exibições semânticas existentes, portanto você deve recriá-los (com os comandos CREATE OR REPLACE) para incorporar alterações. Observe também que a atualização de uma exibição semântica por meio de um comando SQL substitui todas as edições manuais feitas em uma sessão ativa do Snowsight. Não há suporte para preservação de ambos os conjuntos de alterações.

Conversão de modelos semânticos YAML em exibições semânticas nativas¶

Você pode usar funções do sistema e procedimentos armazenados SQL para criar exibições semânticas de modelos YAML e criar modelos YAML de exibições semânticas.

Atualmente, o Snowflake não oferece suporte à conversão em massa. Você deve converter os arquivos YAML em exibições semânticas nativas um de cada vez. Você pode usar o procedimento armazenado SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML para conversão. Se você precisar de conversão ou integração em massa em um pipeline de CI/CD, crie um script para as conversões em uma série. Não há planos para incluir suporte à conversão em lote/massa no Snowflake em um futuro próximo.

Para exportar uma exibição semântica nativa de volta ao YAML, você pode usar a função SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW. Essa função habilita pós-processamento automatizado, ida e volta ou serialização no controle de versão.

As mesmas diretrizes práticas relacionadas ao tamanho se aplicam tanto a exibições semânticas nativas quanto a modelos baseados em YAML. Há uma diretriz prática (não um limite fixo) que, para melhor desempenho, as exibições semânticas não devem ter mais do que 50-100 colunas no total em todas as tabelas. Essa diretriz se aplica tanto a exibições semânticas nativas quanto a modelos baseados em YAML, e se deve principalmente aos limites da janela de contexto em componentes de AI, como o Cortex Analyst. Exceder essa recomendação pode levar à latência ou degradação da qualidade, mas não é um limite técnico.

Implementação automatizada de exibições semânticas¶

Sempre que possível, aproveite os pipelines de CI/CD e as interfaces programáticas para criar, modificar e gerenciar exibições semânticas. O ideal é configurar seu fluxo de trabalho para que as atualizações de exibições semânticas sejam sincronizadas automaticamente com seu repositório Git. Essa abordagem reduz os erros manuais que podem ser causados por copiar e colar ou enviar alterações ao Git.

• Armazene o YAML da exibição semântica (ou SQL DDL) em um repositório Git. Essa abordagem oferece suporte a controle de versão, revisão por pares, histórico e reversão.

• Se você usa o Snowsight, exporte ou baixe o modelo YAML regularmente e faça commit no Git.

• Acione os pipelines de CI/CD em caso de alterações no Git (para executar testes e verificações de precisão e, em seguida, implantar somente se esses testes forem aprovados).

• Se necessário, faça a reversão ao último bom estado conhecido reimplantando o YAML ou DDL do Git.

Para promover modelos dos ambientes de desenvolvimento a teste ou produção, você pode incorporar scripts de implantação automatizada para essa finalidade, ou pode usar a clonagem no nível do esquema. As exibições semânticas são clonadas quando os esquemas que as contêm são clonados. Considerando que a replicação ainda não é compatível com as exibições semânticas, a clonagem é uma boa alternativa para promover exibições semânticas em bancos de dados e ambientes que usam a mesma conta Snowflake.

As exibições semânticas podem ser compartilhadas diretamente pelo Snowflake Marketplace e por compartilhamento de dados. Você pode criar exibições seguras com base em exibições semânticas, e o compartilhamento dessas exibições aninhadas é permitido. No entanto, alguns cenários de recompartilhamento têm limitações; por exemplo, quando o consumidor de um compartilhamento também deseja compartilhar uma exibição criada com base em uma exibição semântica.

Para oferecer suporte à materialização e manutenção de exibições semânticas como parte de um pipeline de dados do Snowflake, você pode usar um projeto dbt. Consulte Integração com projetos dbt. O suporte para um processo semelhante usando o Provedor Snowflake Terraform está planejado.

Por fim, seu objetivo deve ser habilitar um fluxo de trabalho semelhante ao seguinte exemplo de dbt:

• Trabalhar nas alterações do projeto dbt em um IDE, como VS Code.

• Adicionar uma nova definição de exibição semântica ao código dbt.

• Enviar as alterações para o Git.

• Configurar acionadores que executam uma operação 'dbt run' como parte do pipeline de dados.

Como resultado, a exibição semântica é materializada na conta Snowflake.

Integração com projetos dbt¶

Você pode integrar exibições semânticas a seu fluxo de trabalho dbt instalando o pacote dbt_semantic_view que está disponível no Snowflake Labs: https://hub.getdbt.com/Snowflake-Labs/dbt_semantic_view/latest/.

Esse pacote funciona nativamente com Projetos dbt no Snowflake ou qualquer instalação dbt que tenha acesso a uma conta Snowflake. É possível usar esse pacote para materializar exibições semânticas pelo dbt e fazer referência a elas nos modelos subsequentes.

As instruções a seguir consideram que você está familiarizado e tem o dbt instalado em um ambiente que pode se conectar ao Snowflake.

Para instalar e usar o pacote dbt_semantic_view:

1. Adicione o seguinte código ao arquivo packages.yml:

   packages:
     - package: Snowflake-Labs/dbt_semantic_view
       version: 1.0.3
   

   Copy

   Inclua o número da versão. O número da versão do pacote pode mudar. Recomenda-se usar a última versão.

2. Execute o comando dbt deps para instalar o pacote.

3. No diretório models do dbt, crie um modelo que use o código de materialização da exibição semântica:

   {{ config(materialized='semantic_view') }}
   
   TABLES(
   {{ source('<source_name>', '<table_name>') }},
   {{ ref('<another_model>') }}
   )
   [ RELATIONSHIPS ( relationshipDef [ , ... ] ) ]
   [ FACTS ( semanticExpression [ , ... ] ) ]
   [ DIMENSIONS ( semanticExpression [ , ... ] ) ]
   [ METRICS ( semanticExpression [ , ... ] ) ]
   [ COMMENT = '<comment>' ]
   [ COPY GRANTS ]
   

   Copy

   Por exemplo, você pode materializar uma exibição semântica simples da seguinte forma:

   {{ config(materialized='semantic_view') }}
   
   TABLES(t1 AS {{ ref('base_table') }}, t2 as {{ source('seed_sources', 'base_table2') }})
   DIMENSIONS(t1.count as value, t2.volume as value)
   METRICS(t1.total_rows AS SUM(t1.count), t2.max_volume as max(t2.volume))
   COMMENT='test semantic view'
   

   Copy

4. Configure sua conexão com o Snowflake no dbt, especificando os detalhes da conexão no arquivo profiles.yml do dbt. Para obter mais informações, consulte a documentação do dbt. Por exemplo:

   semantic_project:
     target: snowflake
     outputs:
       snowflake:
       type: "snowflake"
       account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
       user: "{{ env_var('SNOWFLAKE_USER') }}"
       password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
       authenticator: "{{ env_var('SNOWFLAKE_AUTHENTICATOR') }}"
       role: "{{ env_var('SNOWFLAKE_ROLE') }}"
       database: "{{ env_var('SNOWFLAKE_DATABASE') }}"
       warehouse: "{{ env_var('SNOWFLAKE_WAREHOUSE') }}"
       schema: "{{ env_var('SNOWFLAKE_SCHEMA') }}"
       threads: 4
   

   Copy

5. Considerando este perfil, você pode se autenticar com as seguintes variáveis de ambiente:

   $ export SNOWFLAKE_ACCOUNT=snowflake_acct1
   $ export SNOWFLAKE_USER=sem_user1
   $ export SNOWFLAKE_PASSWORD=**************
   $ export SNOWFLAKE_AUTHENTICATOR=externalbrowser
   $ export SNOWFLAKE_ROLE=semantic_role
   $ export SNOWFLAKE_DATABASE=sem_db
   $ export SNOWFLAKE_WAREHOUSE=sem_wh
   $ export SNOWFLAKE_SCHEMA=sem_schema
   

   Copy

6. Execute o comando dbt build para se conectar à sua conta Snowflake e criar o modelo. O exemplo a seguir cria um modelo específico definido como models/semantic_view_basic. Observe que outro modelo, table_refer_to_semantic_view, depende desse modelo, portanto o comando requer o sinal + no final.

   $ dbt build --target snowflake --select semantic_view_basic+
   23:43:16  Running with dbt=1.11.0-b3
   23:43:17  Registered adapter: snowflake=1.10.2
   23:43:17  Found 9 models, 8 data tests, 1 seed, 2 operations, 2 sources, 500 macros
   23:43:17
   23:43:17  Concurrency: 4 threads (target='snowflake')
   23:43:17
   23:43:32  1 of 2 START hook: dbt_semantic_view_integration_tests.on-run-start.0 .......... [RUN]
   23:43:32  1 of 2 OK hook: dbt_semantic_view_integration_tests.on-run-start.0 ............. [OK in 0.90s]
   23:43:33  2 of 2 START hook: dbt_semantic_view_integration_tests.on-run-start.1 .......... [RUN]
   23:43:33  2 of 2 OK hook: dbt_semantic_view_integration_tests.on-run-start.1 ............. [OK in 0.38s]
   23:43:33
   23:43:33  1 of 6 START sql semantic_view model sem_schema.semantic_view_basic ............ [RUN]
   23:43:33  1 of 6 OK created sql semantic_view model sem_schema.semantic_view_basic ....... [SUCCESS 1 in 0.26s]
   23:43:33  3 of 6 START test semantic_view_basic_has_no_copy_grants ....................... [RUN]
   23:43:33  2 of 6 START test semantic_view_basic_has_comment .............................. [RUN]
   23:43:33  4 of 6 START test semantic_view_sum_matches_base_table ......................... [RUN]
   23:43:33  2 of 6 PASS semantic_view_basic_has_comment .................................... [PASS in 0.23s]
   23:43:34  3 of 6 PASS semantic_view_basic_has_no_copy_grants ............................. [PASS in 0.75s]
   23:43:34  4 of 6 PASS semantic_view_sum_matches_base_table ............................... [PASS in 1.05s]
   23:43:34  5 of 6 START sql table model sem_schema.table_refer_to_semantic_view ........... [RUN]
   23:43:35  5 of 6 OK created sql table model sem_schema.table_refer_to_semantic_view ...... [SUCCESS 1 in 1.22s]
   23:43:35  6 of 6 START test table_refer_semantic_view_matches_semantic_view .............. [RUN]
   23:43:36  6 of 6 PASS table_refer_semantic_view_matches_semantic_view .................... [PASS in 0.26s]
   23:43:36
   23:43:36  Finished running 2 project hooks, 1 semantic view model, 1 table model, 4 data tests in 0 hours 0 minutes and 19.34 seconds (19.34s).
   23:43:36
   23:43:36  Completed successfully
   23:43:36
   23:43:36  Done. PASS=8 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=8
   

   Copy

Para obter mais informações sobre o pacote dbt_semantic_view, que inclui modelos e testes já criados que você pode executar, consulte o arquivo README.md. Vá para https://hub.getdbt.com/Snowflake-Labs/dbt_semantic_view/latest/ e selecione View on GitHub.

Consulte também https://www.snowflake.com/en/engineering-blog/dbt-semantic-view-package/.

Integração com ferramentas de BI¶

Vários fornecedores de ferramentas de BI oferecem integrações com as exibições semânticas do Snowflake. Para saber mais sobre essas integrações, entre em contato as equipes de conta da ferramenta de BI e siga estes links:

• Sigma: https://www.sigmacomputing.com/blog/snowflake-semantic-views-launch

• Omni: https://omni.co/snowflake

• Honeydew: https://honeydew.ai/blog/honeydew-and-snowflake-semantic-views/

• Hex: https://hex.tech/blog/introducing-snowflake-semantic-sync-aisql/