Especificação YAML para exibições semânticas¶

Exibições semânticas são objetos no nível do esquema que definem conceitos comerciais com base em seus dados, facilitando a consulta e análise de dados pelos usuários com o uso de uma terminologia de negócios. Você pode usar a especificação YAML para criar uma exibição semântica em Cortex Analyst ou usar o procedimento armazenado SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML para criar uma exibição semântica de uma especificação YAML.

Visão geral¶

Exibições semânticas são a abordagem recomendada para definir a semântica de negócios no Snowflake. Elas são objetos de esquema que se integram ao sistema de privilégios, aos mecanismos de compartilhamento e ao catálogo de metadados do Snowflake.

Nota

Os arquivos YAML do modelo semântico legado (armazenados em estágios) ainda podem ser usados com Cortex Analyst para compatibilidade com versões anteriores, mas recomendamos o uso de exibições semânticas para novas implementações.

Os benefícios das exibições semânticas em comparação aos modelos semânticos legados são:

Integração nativa com o Snowflake: objetos em nível de esquema com RBAC completo, compartilhamento e suporte de catálogo
**Recursos avançados*: suporte para métricas derivadas e modificadores de acesso (público/privado)
Melhor governança: integração com os sistemas de privilégio e compartilhamento do Snowflake
Gerenciamento simplificado: não é necessário gerenciar arquivos YAML em estágios

Formato YAML¶

Exibições semânticas podem exigir uma especificação YAML para definir seu comportamento, permitindo definições de texto simples legíveis.

A sintaxe geral de uma especificação YAML de exibição semântica é:

# Name and description of the semantic view.
name: <name>
description: <string>

# Logical table-level concepts
# A semantic view can contain one or more logical tables.
tables:
  # A logical table on top of a base table.
  - name: <name>
    description: <string>
    # The fully qualified name of the base table.
    base_table:
      database: <database>
      schema: <schema>
      table: <base table name>

    # Dimension columns in the logical table.
    dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>
        cortex_search_service:
          service: <string>
          literal_column: <string>
          database: <string>
          schema: <string>
        is_enum: <boolean>
    - ...
    # Time dimension columns in the logical table.
    time_dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>

    # Fact columns in the logical table.
    facts:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: <public_access | private_access>  # Default is public_access.
        expr: <SQL expression>
        data_type: <data type>

    # Regular metrics scoped to the logical table.
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: <public_access | private_access>  # Default is public_access.
        expr: <SQL expression>
        non_additive_dimensions:
        - table: <table name>
          dimension: <dimension name>
          sort_direction: <ascending | descending>
          null_order: <first | last>
        using_relationships:
        - <relationship_name>

    # Commonly used filters over the logical table.
    filters:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>

# View-level concepts
# Relationships between logical tables
relationships:
  - name: <string>
    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>
      - left_column: <column>
        right_column: <column>

# Derived metrics scoped to the semantic view.
# Derived metrics combine metrics from multiple tables.
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    access_modifier: <public_access | private_access>  # Default is public_access
    expr: <SQL expression>

# Additional context concepts
# Verified queries with example questions and queries that answer them
verified_queries:
  - name: <string>       # A descriptive name of the query.
    question: <string>   # The natural language question that this query answers.
    verified_at: <int>   # Optional: Time (in seconds since the UNIX epoch, January 1, 1970) when the query was verified.
    verified_by: <string> # Optional: Name of the person who verified the query.
    use_as_onboarding_question: <boolean>  # Optional: Marks this question as an onboarding question for the end user.
    sql: <string>        # The SQL query for answering the question

Importante

Exibições semânticas não exigem os campos join_type ou relationship_type que eram usados em modelos semânticos legados. O tipo de relacionamento é inferido automaticamente a partir dos dados.

Principais conceitos¶

Tabelas¶

As tabelas lógicas representam entidades comerciais (como clientes, pedidos ou produtos) e são mapeadas para tabelas de banco de dados físicas. Cada tabela lógica pode definir:

Tabela base: o nome totalmente qualificado da tabela física
Chave primária: colunas que identificam linhas de forma única
Sinônimos: nomes alternativos para a tabela
Descrição: explicação simples sobre o que a tabela representa

Dimensões¶

As dimensões representam atributos categóricos que fornecem contexto para análise. Elas respondem às perguntas «quem», «o que», «onde» e «quando». As dimensões podem ser:

Dimensões regulares: valores de texto, numéricos ou de outras categorias
Dimensões temporais: colunas de data ou carimbo de data/hora com tratamento especial baseado no horário

Propriedades de dimensões¶

expr: expressão SQL para calcular o valor da dimensão
synonyms: termos alternativos que os usuários podem utilizar
unique: se os valores são únicos entre as linhas
is_enum: se a dimensão tem um conjunto fixo de valores
cortex_search_service: Cortex Search Service opcional para pesquisa semântica

Propriedades opcionais para dimensões físicas¶

Esses campos são opcionais, mas recomendados para produzir resultados de maior qualidade com base em uma pesquisa de exibição semântica.

synonyms

Uma lista de outros termos/frases usados para se referir a esta dimensão. Deve ser único entre todos os sinônimos neste modelo semântico.

description

Uma descrição curta da dimensão. Inclua informações contextuais úteis, como os dados que esta dimensão representa.

unique

Um valor booliano que indica que esta dimensão tem valores únicos.

sample_values

Valores de amostra desta coluna, se houver. Adicione qualquer valor que provavelmente será mencionado nas perguntas do usuário.

is_enum

Um valor booliano. Se for True, os valores no campo sample_values serão considerados como a lista completa de valores possíveis, e o modelo só escolherá entre esses valores ao filtrar essa coluna.

cortex_search_service

Especifica o Cortex Search Service a ser usado para esta dimensão. Ela possui os seguintes campos:

service: o nome do serviço Cortex Search Service.
literal_column: (opcional) a coluna no Cortex Search Service com os valores literais.
database: (opcional) o banco de dados em que o Cortex Search Service está localizado. O padrão é o banco de dados de base_table.
schema: (opcional) o esquema em que o Cortex Search Service está localizado. O padrão é o esquema de base_table.

cortex_search_service substitui o campo cortex_search_service_name, que só podia especificar o nome. cortex_search_service_name foi descontinuado.

Propriedades opcionais para dimensões temporais¶

Esses campos são opcionais, mas recomendados para produzir resultados de maior qualidade com base em uma pesquisa de exibição semântica.

synonyms: Uma lista de outros termos/frases usados para se referir a esta dimensão de tempo. Deve ser único entre todos os sinônimos neste modelo semântico.
description: Uma descrição curta da dimensão. Inclua informações contextuais úteis, como o fuso horário que esta dimensão usa como ponto de referência.
unique:: Um valor booliano que indica que esta coluna tem valores exclusivos.
sample_values:: Valores de amostra desta coluna, se houver. Adicione quaisquer valores que provavelmente serão referenciados nas perguntas do usuário.

Fatos¶

Os fatos são atributos quantitativos em nível de linha que representam eventos ou transações comerciais específicos. Os fatos capturam “quanto” ou “quantos” no nível mais granular, como valores de vendas individuais, quantidades compradas ou custos.

Os fatos normalmente funcionam como conceitos “auxiliares” dentro da exibição semântica para ajudar a construir dimensões e métricas.

As propriedades dos fatos são:

expr: expressão SQL para calcular o valor do fato
access_modifier: defina como private_access para ocultar de consultas (útil para cálculos intermediários)
data_type: o tipo de dados do fato

Métricas¶

Métricas são medidas quantificáveis de desempenho comercial calculadas por meio da agregação de fatos ou outras colunas usando funções como SUM, AVG e COUNT.

Dois tipos de métricas:

Métricas em nível de tabela: com escopo para uma tabela lógica específica, agregando dados nessa tabela
Métricas derivadas: métricas em nível de exibição que combinam métricas de várias tabelas

Propriedades das métricas¶

expr: expressão SQL com função de agregação
access_modifier: defina como private_access para ocultar de consultas (útil para cálculos intermediários)
synonyms: termos alternativos para a métrica

Propriedades opcionais das métricas¶

Se você quiser especificar as dimensões que devem ser não aditivas para a métrica, use os seguintes campos:
non_additive_dimensions
Especifica as dimensões às quais a métrica não deve ser agregada.
table
Nome da tabela lógica que contém a dimensão.

dimension
Nome da dimensão.

sort_direction
Ordem de classificação para a dimensão não aditiva. Especifique um dos seguintes valores:

ascending: classificar os valores de dimensão em ordem crescente.

descending: classificar os valores de dimensão em ordem decrescente.

Padrão: ascending
null_order
Especifica se NULLs são classificados antes ou depois dos valores não NULL. Especifique um dos seguintes valores:

first: NULLs são classificados antes dos valores não NULL.

last: NULLs são classificados após os valores não NULL.

Padrão: sem valor. Depende do valor no campo sort_direction (ascending ou descending). Consulte as notas de uso na documentação de ORDER BY.
Nota

Como as linhas são classificadas pelas dimensões não aditivas, a ordem na qual você especifica as dimensões é importante. Isso é semelhante à ordem na qual você especifica as colunas na cláusula ORDER BY.
O exemplo a seguir especifica que a métrica m_account_balance não pode ser agregada pelas dimensões year_dim e month_dim:
```
metrics:
  - name: m_account_balance
    ...
    non_additive_dimensions:
    - table: bank_accounts
      dimension: year_dim
      sort_direction: ascending
      null_order: last
    - table: bank_accounts
      dimension: month_dim
      sort_direction: descending
      null_order: first
```
Se houver vários caminhos de relacionamento entre duas tabelas lógicas específicas em uma exibição semântica, use o seguinte campo para especificar o caminho de relacionamento a ser usado:

using_relationships

Recurso em versão preliminar — Aberto

Disponível para todas as contas.

Especifica o nome do relacionamento a ser usado para unir as tabelas lógicas ao calcular a métrica.

Métricas derivadas¶

Métricas derivadas são métricas em nível de exibição não vinculadas a uma tabela específica. Elas podem combinar métricas de várias tabelas ou realizar cálculos em toda a exibição.

Exemplo de uma métrica derivada:

metrics:
  - name: total_profit_margin
    description: "Overall profit margin across all products"
    expr: (orders.total_revenue - orders.total_cost) / orders.total_revenue
    access_modifier: public_access

Relações¶

As relações definem como as tabelas lógicas se unem. Cada relacionamento especifica:

left_table: a tabela que contém a chave estrangeira
right_table: a tabela sendo referenciada
relationship_columns: pares de colunas para unir, como left_column e right_column

O tipo de relacionamento (um para um, muitos para um) é inferido automaticamente a partir dos dados e definições da chave primária.

Nota

Ao contrário dos modelos semânticos legados, as exibições semânticas não exigem especificações join_type ou relationship_type explícitas. Elas são determinadas automaticamente.

Filtros¶

Os filtros definem condições comumente usadas que podem ser referenciadas pelo nome. Isso ajuda a garantir uma lógica de filtragem consistente nas consultas.

Exemplo:

filters:
  - name: active_customers
    description: "Customers who have made a purchase in the last 12 months"
    expr: "customer_last_purchase_date >= DATEADD(month, -12, CURRENT_DATE())"

Consultas verificadas¶

As consultas verificadas são perguntas de exemplo com suas consultas SQL correspondentes. Elas ajudam Cortex Analyst a entender como responder a perguntas semelhantes e funcionam como documentação para os usuários.

Propriedades:

question: pergunta em linguagem natural
sql: consulta SQL que responde à pergunta
verified_by: pessoa opcional que verificou se a consulta está correta
verified_at: carimbo de data/hora opcional quando há verificação
use_as_onboarding_question: sinalizador opcional para mostrar isso como uma sugestão aos usuários

Modificadores de acesso¶

Exibições semânticas oferecem suporte a modificadores de acesso para fatos e métricas, permitindo controlar a visibilidade:

public_access (padrão): pode ser visualizado e consultado pelos usuários
private_access: oculto nas consultas, usado apenas para cálculos intermediários

Exemplo:

facts:
  - name: internal_cost
    expr: unit_cost * quantity
    data_type: NUMBER
    access_modifier: private_access  # Not visible in queries

metrics:
  - name: total_revenue
    expr: SUM(sale_amount)
    access_modifier: public_access  # Visible in queries

Instruções personalizadas para o Cortex Analyst¶

Você pode usar comandos SQL para fornecer instruções personalizadas na definição da exibição semântica. Essas instruções orientam como as consultas são geradas e como as perguntas são categorizadas. Essas instruções não fazem parte da especificação YAML, mas são definidas usando o comando CREATE SEMANTIC VIEW.

Para obter mais informações, consulte Fornecendo instruções personalizadas para o Cortex Analyst.

Exemplo de exibição semântica YAML¶

Aqui está um exemplo completo de uma especificação YAML de exibição semântica:

name: revenue_analysis
description: "Semantic view for analyzing revenue across products and customers"

tables:
  - name: customers
    description: "Customer information"
    base_table:
      database: sales_db
      schema: public
      table: customers
    dimensions:
      - name: customer_name
        synonyms: ["client name", "customer"]
        description: "Full name of the customer"
        expr: c_name
        data_type: VARCHAR
      - name: customer_segment
        synonyms: ["segment", "market segment"]
        description: "Customer market segment"
        expr: c_mktsegment
        data_type: VARCHAR
        is_enum: true

  - name: orders
    description: "Order information"
    base_table:
      database: sales_db
      schema: public
      table: orders
    dimensions:
      - name: order_date
        description: "Date when order was placed"
        expr: o_orderdate
        data_type: DATE
    time_dimensions:
      - name: order_year
        description: "Year when order was placed"
        expr: YEAR(o_orderdate)
        data_type: NUMBER
    facts:
      - name: order_total
        description: "Total order amount"
        expr: o_totalprice
        data_type: NUMBER
    metrics:
      - name: total_orders
        description: "Total number of orders"
        expr: COUNT(*)
      - name: average_order_value
        description: "Average order value"
        expr: AVG(o_totalprice)

relationships:
  - name: orders_to_customers
    left_table: orders
    right_table: customers
    relationship_columns:
      - left_column: o_custkey
        right_column: c_custkey

metrics:
  - name: revenue_per_customer
    description: "Average revenue per customer"
    expr: orders.total_revenue / customers.customer_count
    access_modifier: public_access

verified_queries:
  - name: top_customers_by_revenue
    question: "Who are the top 10 customers by revenue?"
    sql: |
      SELECT
        customer_name,
        SUM(order_total) as total_revenue
      FROM revenue_analysis
      GROUP BY customer_name
      ORDER BY total_revenue DESC
      LIMIT 10
    use_as_onboarding_question: true

Criação de uma exibição semântica YAML¶

Para criar uma exibição semântica a partir de uma especificação YAML, use o procedimento armazenado SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML.

Para obter mais informações, consulte Criação de exibição semântica de uma especificação YAML.

Como obter um YAML de uma exibição semântica¶

Para exportar uma exibição semântica para o formato YAML, use a função SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW.

Para obter mais informações, consulte Como obter a especificação YAML para uma exibição semântica.

Diferenças de modelos semânticos legados¶

Se você estiver migrando de arquivos do modelo semântico YAML legado para exibições semânticas, considere estas diferenças importantes:


Recurso	Modelos semânticos legados	Exibições semânticas
Armazenamento	Arquivos YAML em estágios	Objetos em nível de esquema no banco de dados
Privilégios	Controle de acesso baseado em estágio	Integração completa do Snowflake RBAC
Compartilhamento	Compartilhamento manual de arquivos	Compartilhamento do Native Snowflake
Tipos de junção	Requer `join_type` e `relationship_type`	Inferido automaticamente
Métricas derivadas	Sem suporte	Suporte total
Modificadores de acesso	Sem suporte	`public_access` / `private_access`
Instruções personalizadas	No arquivo YAML	Definido pelos comandos SQL

Ao converter de um modelo semântico legado para uma exibição semântica:

Remova join_type e relationship_type das relações
Considere o uso de métricas derivadas para cálculos em nível de exibição
Adicione access_modifier aos fatos/métricas que você deseja tornar privados
Mova instruções personalizadas para o comando SQL CREATE SEMANTIC VIEW