Especificação do modelo semântico Cortex Analyst¶

Conceitos de camada semântica¶

A estrutura e os conceitos que definem a camada semântica lógica são semelhantes aos que definem a camada física do banco de dados. A seguir estão os tipos de conceito para uma camada semântica:

• Nível de tabela lógica

• Nível do modelo

• Contexto adicional

Conceitos lógicos em nível de tabela¶

Uma tabela lógica é um conceito fundamental do modelo semântico do Snowflake. Ela representa uma tabela do banco de dados física ou uma exibição. Normalmente, isso corresponde a entidades comerciais (como clientes, pedidos ou fornecedores) ou dimensões (como localização ou tempo). Normalmente, cada linha em uma tabela lógica representa uma instância exclusiva da entidade, como ID de um cliente.

As tabelas lógicas contêm os seguintes tipos de colunas:

• Fatos (dados quantitativos sobre eventos de negócios)

• Dimensões (quem, o que, onde e como)

• Hora (quando o evento ocorreu)

• Filtros associados à tabela lógica para permitir que os resultados de consulta sejam limitados a subconjuntos de dados específicos.

Você pode definir métricas usando agregações ou combinações de outros objetos lógicos.

Os exemplos a seguir usam o esquema TPC-H, que inclui a tabela de fatos LINEITEM. Para obter uma implementação completa do YAML, faça o download do arquivo snow_tpch.

Todos os exemplos de nível de tabela lógica a seguir pertencem à tabela lógica order_lineitems.

tables:
  - name: order_lineitems
    description: >
      The order line items table contains detailed information about each item within an
      order, including quantities, pricing, and dates.

    base_table:
      database: SNOWFLAKE_SAMPLE_DATA
      schema: TPCH_SF1
      table: LINEITEM
    primary_key:
      columns:
        - order_key
        - order_lineitem_number

Copy

Uma dimensão representa dados categóricos que fornecem contexto aos fatos, como informações sobre produtos, clientes ou locais. As dimensões normalmente contêm valores de texto descritivos, como nomes de produto ou endereços de cliente. Elas são usadas para filtrar, agrupar e rotular fatos em análises e relatórios.

Uma dimensão de tempo fornece contexto temporal para analisar fatos em diferentes períodos. Ela permite o rastreamento de métricas em intervalos de tempo específicos (datas, meses, anos) e oferece suporte a análises como identificação de tendências e comparações entre períodos.

time_dimensions:
  - name: shipment_duration
    synonyms:
      - "shipping time"
      - "shipment time"
    description: The time it takes for items to be shipped.

    expr: DATEDIFF(day, lineitem.L_SHIPDATE, lineitem.L_RECEIPTDATE)
    data_type: NUMBER
    unique: false

Copy

Fatos são dados mensuráveis e quantitativos que fornecem contexto para as análises. Os fatos representam valores numéricos relacionados aos processos de negócios, como vendas, custo ou quantidade. Um fato é um conceito não agregado, em nível de linha.

# Fact columns in the logical table.
facts:
  - name: net_revenue
    synonyms:
      - "revenue after discount"
      - "net sales"
    description: Net revenue after applying discounts.

    expr: lineitem.L_EXTENDEDPRICE * (1 - lineitem.L_DISCOUNT)
    data_type: NUMBER

Copy

For semantic views, facts can be made private (accessible in the semantic view, but not by end users) by setting the access_modifier field to private_access. By default, facts are public (accessible by users).

Um filtro é uma condição que limita os resultados de consulta a subconjuntos de dados específicos com base em critérios como período de tempo, local ou categoria.

- name: north_america
  synonyms:
    - "NA"
    - "North America region"
  description: >
    Filter to restrict data to orders from North America.
  comments: Used for analysis focusing on North American customers.
  expr: nation.N_NAME IN ('Canada', 'Mexico', 'United States')

Copy

Uma métrica é uma medida quantificável de desempenho comercial expressa como uma fórmula SQL. Você pode usar métricas como principais indicadores de desempenho (KPIs) em relatórios e painéis. É possível calcular dois tipos de métricas:

• Métricas regulares agregam valores (usando funções como SUM ou AVG) em uma coluna de fatos.

• Derived metrics are calculated from existing metrics, using arithmetic operations such as addition or division. Derived metrics are supported only in semantic views.

Definir métricas em seu nível mais granulares para agregação em níveis superiores. Por exemplo, defina total_revenue no nível do item de linha para permitir a agregação por cliente, fornecedor ou região.

O exemplo a seguir mostra o cálculo de duas métricas regulares: um simples e um mais complexo. Elas são definidas dentro de uma definição table, portanto, elas têm como escopo essa tabela lógica.

metrics:

    # Simple metric referencing objects from the same logical table
    - name: total_revenue
      expr: SUM(lineitem.l_extendedprice * (1 - lineitem.l_discount))

    # Complex metric referencing objects from multiple logical tables.
    # The relationships between tables have been defined below.
    - name: total_profit_margin
      description: >
                  The profit margin from orders. This metric is not additive
                  and should always be calculated directly from the base tables.
      expr: (SUM(order_lineitems.net_revenue) -
            SUM(part_suppliers.part_supplier_cost * order_lineitems.lineitem_quantity))
            / SUM(order_lineitems.net_revenue)

Copy

Dica

For semantic views, metrics can be made private (accessible in the semantic view, but not by end users) by setting the access_modifier field to private_access. By default, metrics are public (accessible by users).

Referências permitidas¶

Expressões para dimensões, fatos, filtros ou métricas regulares com escopo de tabela podem fazer referência a:

• Colunas físicas de sua própria tabela base

• Colunas lógicas dentro da mesma tabela lógica

• Colunas lógicas de outras tabelas lógicas no modelo semântico

For semantic views, derived metrics can reference metrics defined in any logical table in the semantic view or other derived metrics.

Nota

As expressões não podem fazer referência a colunas físicas de outras tabelas físicas.

Conceitos em nível de modelo¶

As relações conectam tabelas lógicas por meio de junções de chaves compartilhadas. Por exemplo, pode haver uma relação entre as tabelas de clientes e pedidos por meio de uma junção na coluna customer_id. Você pode usar junções para analisar os dados de pedidos com atributos de clientes.

relationships:

  # Relationship between orders and lineitems
  - name: order_lineitems_to_orders
    left_table: order_lineitems
    right_table: orders
    relationship_columns:
      - left_column: order_key
        right_column: order_key
    # For semantic views, do not specify
    # join_type or relationship_type.
    join_type: left_outer
    relationship_type: many_to_one

  # Relationship between lineitems and partsuppliers
  - name: order_lineitems_to_part_suppliers
    left_table: order_lineitems
    right_table: part_suppliers
    # The relationship requires equality of multiple columns from each table
    relationship_columns:
      - left_column: part_key
        right_column: part_key
      - left_column: supplier_key
        right_column: supplier_key
    # For semantic views, do not specify
    # join_type or relationship_type.
    join_type: left_outer
    relationship_type: many_to_one

Um repositório de consultas verificadas (VQR) é uma coleção de perguntas e consultas SQL correspondentes que são verificadas como corretas. Você pode usar as consultas para ajudar a melhorar a precisão dos resultados do Cortex Analyst.

Você pode usar Instruções personalizadas no Cortex Analyst para ter maior controle sobre a geração de consulta SQL do Cortex Analyst. Nas instruções personalizadas, você fornece o contexto exclusivo de seu negócio para o LLM.

Os modelos semânticos do Cortex Analyst são especificados em YAML. O modelo fornece as informações semânticas necessárias para responder a perguntas de linguagem natural com alta precisão.

Formato YAML¶

YAML é um meio-termo entre legibilidade humana e precisão. Os usuários corporativos podem entendê-lo, enquanto os engenheiros e analistas de dados podem definir claramente os conceitos técnicos.

A sintaxe geral de um modelo semântico do Cortex Analyst é a seguinte:

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

# Logical table-level concepts

# A semantic model 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 >  # Supported only for semantic views.
                                                             # 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 >  # Supported only for semantic views.
                                                             # Default is public_access.

        expr: <SQL expression>


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

        expr: <SQL expression>

# Model-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>
    # For semantic views, do not specify
    # join_type or relationship_type.
    join_type: <left_outer | inner>
    relationship_type: < one_to_one | many_to_one >

# Derived metrics scoped to the semantic view.
# Derived metrics are supported only for semantic views.
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:        # A descriptive name of the query.

    question:    # The natural language question that this query answers.
    verified_at: # Optional: Time (in seconds since the UNIX epoch, January 1, 1970) when the query was verified.
    verified_by: # Optional: Name of the person who verified the query.
    use_as_onboarding_question:  # Optional: Marks this question as an onboarding question for the end user.
    sql:                         # The SQL query for answering the question

Para obter um exemplo de especificação, consulte o arquivo snow_tpch.yaml.

Modelo semântico¶

Um modelo semântico representa uma coleção de tabelas. O modelo contém descrições de tabelas, cada uma das quais contém descrições de aspectos específicos da tabela. Cada tabela descrita no modelo é mapeada para uma tabela base física no Snowflake.

Ela possui os seguintes campos:

Obrigatório

name

Um nome descritivo para este modelo semântico.

Deve ser único e seguir os requisitos de identificadores sem aspas. Também não pode entrar em conflito com palavras-chave reservadas do Snowflake.

Opcional

Esses campos não são obrigatórios, mas devem ser incluídos sempre que possível.

description

Uma descrição deste modelo semântico, incluindo detalhes sobre para que tipo de análise ele é útil.

tables

Uma lista de tabelas lógicas neste modelo semântico.

relationships

Uma lista de junções entre tabelas lógicas.

Tabela lógica¶

Você pode pensar em uma tabela lógica como uma exibição sobre uma tabela ou exibição do banco de dados física. Ela possui os seguintes campos:

Obrigatório

name

Um nome descritivo para esta tabela.

Deve ser único e seguir os requisitos de identificadores sem aspas. Também não pode entrar em conflito com palavras-chave reservadas do Snowflake.

base_table

Um nome totalmente qualificado da tabela base subjacente no banco de dados.

Opcional

Esses campos não são obrigatórios, mas devem ser incluídos sempre que possível.

synonyms

Uma lista de outros termos/frases usados para se referir a esta tabela. Ela deve ser exclusiva entre sinônimos dentro da tabela lógica.

description

Uma descrição desta tabela.

primary_key

As colunas de chave primária dessa tabela. Necessário se você estiver definindo relações.

dimensions

Uma lista de colunas de dimensão nesta tabela.

time_dimensions

Uma lista de colunas de dimensão de tempo nesta tabela.

facts

Uma lista de colunas de fatos nessa tabela.

metrics

Uma lista de métricas nessa tabela.

filters

Filtros predefinidos nesta tabela, se houver.

Dimensão¶

Uma dimensão descreve valores categóricos como estado, tipo_de_usuário, plataforma etc. Ela possui os seguintes campos:

Obrigatório

name

Um nome descritivo para esta dimensão.

Deve ser único e seguir os requisitos de identificadores sem aspas. Também não pode entrar em conflito com palavras-chave reservadas do Snowflake.

expr

A expressão SQL para esta dimensão. Isso pode ser uma referência a uma coluna física ou uma expressão SQL com uma ou mais colunas da tabela base subjacente.

data_type

O tipo de dados desta dimensão. Para uma visão geral de todos os tipos de dados no Snowflake, consulte Referência dos tipos de dados SQL. Observe que VARIANT, OBJECT, GEOGRAPHY e ARRAY e não são suportados atualmente.

Opcional

Esses campos não são obrigatórios, mas devem ser incluídos sempre que possível.

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 breve descrição sobre esta dimensão, incluindo quais dados ela possui.

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.

Dimensão do tempo¶

Uma dimensão de tempo descreve valores de tempo, como sale_date, created_at e year. Ela possui os seguintes campos:

Obrigatório

name

Um nome descritivo para esta dimensão de tempo.

Deve ser único e seguir os requisitos de identificadores sem aspas. Também não pode entrar em conflito com palavras-chave reservadas do Snowflake.

expr

A expressão SQL para esta coluna. Isso pode ser uma referência a uma coluna física ou uma expressão SQL com uma ou mais colunas da tabela base subjacente.

data_type

O tipo de dados desta dimensão de tempo. Para uma visão geral de todos os tipos de dados no Snowflake, consulte Referência dos tipos de dados SQL. Observe que VARIANT, OBJECT, GEOGRAPHY e ARRAY e não são suportados atualmente.

Opcional

Esses campos não são obrigatórios, mas devem ser incluídos sempre que possível.

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 breve descrição sobre esta dimensão, incluindo quais dados ela possui. Forneça informações que ajudarão alguém a escrever consultas usando esta tabela. Por exemplo, para colunas DATETIME, especifique o fuso horário dos dados.

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. Este campo é opcional.

Fato¶

Uma medida descreve valores numéricos, como receita, impressões e salário. Fatos usavam para ser chamados de medidas em versões anteriores de Cortex Analyst. Os fatos são compatíveis com as medidas. Os fatos têm os seguintes campos:

Obrigatório

name

Um nome descritivo para esse fato.

Deve ser único e seguir os requisitos de identificadores sem aspas. Também não pode entrar em conflito com palavras-chave reservadas do Snowflake.

expr

Essa instrução SQL pode se referir a uma coluna física na mesma tabela física de base da tabela lógica ou a uma coluna lógica (fato, dimensão ou dimensão de tempo) dentro dessa tabela lógica.

data_type

O tipo de dados desse fato. Para uma visão geral de todos os tipos de dados no Snowflake, consulte Referência dos tipos de dados SQL. Observe que VARIANT, OBJECT, GEOGRAPHY e ARRAY e não são suportados atualmente.

Opcional

Os campos a seguir não são obrigatórios, mas devem ser incluídos sempre que possível.

synonyms

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

description

Uma breve descrição sobre esta medida, incluindo quais dados esta coluna possui.

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.

O campo a seguir é opcional. Se não estiver incluído, o padrão será public_access.

access_modifier

Supported only for semantic views. The possible values are public_access and private_access. If this is set to private_access, the fact is accessible in the semantic view, but not by end users.

Filter¶

Um filtro representa uma expressão SQL usada para filtragem. Ela possui os seguintes campos:

Obrigatório

name

Um nome descritivo para este filtro.

expr

A expressão SQL deste filtro, referenciando colunas lógicas.

Opcional

Esses campos não são obrigatórios, mas devem ser incluídos sempre que possível.

synonyms

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

description

Uma breve descrição sobre esse filtro, incluindo detalhes sobre a finalidade para a qual ele é normalmente usado.

Métrica¶

Uma métrica descreve medidas quantificáveis de desempenho comercial, como receita total, valor médio do pedido ou contagem de clientes. As métricas podem ser métricas regulares ou métricas derivadas.

• Métricas regulares têm escopo para uma tabela lógica e podem fazer referência a colunas lógicas (fatos, dimensões ou dimensões de tempo) dentro da mesma tabela lógica ou colunas lógicas de outras tabelas lógicas no modelo semântico. No modelo semântico, o elemento metric está dentro de um elemento table. Métricas regulares usam funções agregadas e de janela para calcular valores gerais para a tabela.

• Derived metrics (which are supported only for semantic views) are scoped to the semantic view and provide a way of combining other metrics. In the semantic model, the metric element is inside the semantic_model element. You can refer only to other metrics (including other derived metrics) in the metric’s expression.

As métricas têm os seguintes campos.

Obrigatório

name

Um nome descritivo para esta métrica. Este nome determina se é uma métrica regular.

Deve ser único e seguir os requisitos de identificadores sem aspas. Também não pode entrar em conflito com palavras-chave reservadas do Snowflake.

expr

A expressão SQL para esta coluna. O formato da expressão depende de se a métrica é uma métrica regular ou uma métrica derivada.

• As métricas regulares, que são definidas para uma tabela, referenciam uma coluna lógica (fato, dimensão ou dimensão temporal) na mesma tabela lógica ou uma coluna lógica de outra tabela lógica no modelo semântico e usam funções agregadas ou de janela para calcular valores gerais.

• Métricas derivadas são expressões escalares que podem fazer referência a métricas regulares ou outras métricas derivadas.

Opcional

Os campos a seguir não são obrigatórios, mas devem ser incluídos sempre que possível.

synonyms

Uma lista de outros termos/frases usados para se referir a essa métrica. Cada sinônimo deve ser único entre todos os sinônimos no modelo semântico.

description

Uma breve descrição dessa métrica, incluindo quais dados essa coluna possui.

sample_values

Valores de amostra desta coluna, se houver. Adicione quaisquer valores que provavelmente serão referenciados nas perguntas do usuário.

O campo a seguir é opcional. Se não estiver incluído, o padrão será public_access.

access_modifier

Supported only for semantic views. The possible values are public_access or private_access. If this is set to private_access, the metric is accessible in the semantic view, but not by end users.

Tabela base¶

Uma tabela base é usada para representar nomes de tabela totalmente qualificados. Esta é a tabela física para a qual uma tabela lógica é mapeada. Ela possui os seguintes campos:

Obrigatório

database

Nome do banco de dados.

schema

Nome do esquema.

table

Nome da tabela.

Chave primária¶

Uma chave primária representa as colunas que representam exclusivamente cada linha da tabela. A chave primária é necessária se a tabela for usada em uma relação. Ela possui os seguintes campos:

Obrigatório

columns

Uma lista de colunas de dimensão que representam exclusivamente a tabela.

Relações¶

Define as relações de junção entre as tabelas lógicas. Para garantir a funcionalidade adequada de junção, as chaves primárias devem ser definidas para as tabelas envolvidas nas relações. Ela possui os seguintes campos:

Obrigatório

name

Um identificador exclusivo para a relação.

left_table

Nome da tabela lógica, conforme definido anteriormente no arquivo YAML. Para relações de muitos para um, a tabela da esquerda deve ser o lado muitos da relação para obter o desempenho ideal.

right_table

Nome da tabela lógica, conforme definido anteriormente no arquivo YAML. Para relações de muitos para um, a tabela correta deve ser o lado da relação para obter o desempenho ideal.

relationship_columns

Uma lista de colunas iguais de cada uma das tabelas da esquerda e da direita que representam o caminho de junção.

join_type

left_outer ou inner.

Do not specify this for semantic views.

relationship_type

many_to_one ou one_to_one.

Do not specify this for semantic views. Instead, use unique or primary keys in the logical tables to indicate that the relationship should be many-to-one or one-to-one.

Consultas verificadas¶

Consulte Cortex Analyst Verified Query Repository para obter informações sobre a finalidade e a estrutura desta seção do arquivo YAML.

Instruções personalizadas¶

Para obter informações sobre instruções personalizadas, consulte Instruções personalizadas no Cortex Analyst.