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

Por que usar modelos semânticos?¶

O Cortex Analyst permite que os usuários façam perguntas sobre dados do Snowflake usando linguagem natural. Normalmente, há uma lacuna entre o vocabulário usado pelos usuários empresariais ao fazer perguntas sobre dados e o vocabulário usado no esquema do banco de dados. Esses usuários normalmente usam termos específicos de negócios ou domínio, enquanto o esquema do banco de dados pode usar abreviações ou termos frequentemente usados em pipelines ETL. Os esquemas de banco de dados também costumam carecer de detalhes semânticos que ajudem alguém que não esteja familiarizado com um conjunto de dados a entendê-los. Essa diferença de vocabulário torna difícil para o Cortex Analyst responder às perguntas sobre dados com alta precisão.

Um modelo semântico é um mecanismo leve que aborda esses problemas, permitindo a especificação de detalhes semânticos adicionais sobre um conjunto de dados. Esses detalhes semânticos adicionais, como nomes mais descritivos ou sinônimos, permitem ao Cortex Analyst responder a perguntas de dados de forma muito mais confiável.

Nota

Modelos semânticos são considerados metadados.

Principais conceitos¶

Nota

Ao longo deste tópico, os artefatos relacionados ao banco de dados básico são chamados de artefatos “físicos” e os artefatos relacionados ao modelo semântico são chamados de artefatos “lógicos”.

A estrutura e os conceitos do modelo semântico são semelhantes aos dos esquemas de banco de dados, mas os modelos semânticos permitem que você forneça mais informações semânticas sobre seus dados.

Um conceito central dos modelos semânticos do Snowflake é a tabela lógica. Uma tabela lógica pode ser considerada uma exibição simples sobre uma tabela do banco de dados ou exibição de banco de dados física. Cada tabela lógica é uma coleção de colunas lógicas, que são categorizadas em dimensions, time_dimensions e measures.

Uma coluna lógica pode ser uma referência a uma coluna física subjacente ou uma expressão envolvendo uma ou mais colunas físicas. A expressão pode ser simples, como uma concatenação de cadeia de caracteres ou uma operação matemática, ou pode incluir expressões de agregação. Por exemplo, você pode usar uma expressão como SUM(click)/SUM(spend) para calcular o custo por clique (CPC).

O modelo semântico também pode conter um repositório de consulta verificadas (VQR), que pode ajudar a melhorar a precisão e a confiabilidade dos resultados, fornecendo uma coleção de perguntas e consultas SQL correspondentes para respondê-las.

O modelo semântico para especificação do Cortex Analyst está em YAML. Ele fornece as informações semânticas necessárias para responder a perguntas em linguagem natural com alta precisão.

A sintaxe geral é:

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

# 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_name: <string>

    # 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>

    # Measure columns in the logical table.
    measures:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        default_aggregation: <aggregate function>

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

# Example questions and queries that answer them
verified_queries:

# Verified Query (1 of n)
- 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.

Copy

Gerador de modelo semântico¶

Você pode usar a ferramenta geradora de modelo semântico para gerar um modelo semântico para usar com Cortex Analyst. A ferramenta oferece várias opções para gerar modelos semânticos: por meio de um aplicativo Streamlit, pela linha de comando ou diretamente no seu código Python. O aplicativo Streamlit é particularmente prático, permitindo que você crie modelos semânticos do zero ou itere em modelos existentes enviados para um estágio do Snowflake.

Dicas para criar um modelo semântico¶

Organize seu arquivo YAML por domínio ou tópico de negócios
- Estruture seus arquivos YAML para alinhá-los a domínios ou tópicos comerciais específicos, mantendo o escopo focado. Por exemplo, crie modelos semânticos separados para análise de vendas e análise de marketing.
- Adapte seus casos de uso com base no público-alvo, nas perguntas esperadas ou KPIs e nos dados necessários. Casos de uso bem definidos levam a modelos semânticos mais ricos e recuperação de dados mais eficaz.
Pense pela perspectiva do usuário final
- Identifique as principais perguntas que os usuários provavelmente farão sobre o tópico e inclua apenas as tabelas e colunas necessárias para responder a essas perguntas.
- Use nomes e sinônimos que sejam semelhantes ao vocabulário usado pelos usuários finais.
- Inclua detalhes importantes nos campos de descrição que seriam úteis para alguém que está escrevendo consultas neste conjunto de dados pela primeira vez, como o fuso horário de uma coluna DATETIME.
Capture cálculos complexos

Incorpore consultas mais difíceis ou específicas do negócio em expressões.
Use tabelas largas em vez de tabelas longas

Se você tiver uma tabela com colunas como “métrica” e “valor”, nivele a tabela para que cada métrica seja uma coluna. Essa abordagem fornece ao modelo mais informações semânticas sobre cada métrica.
Revise as descrições geradas automaticamente

Se você estiver usando o gerador de modelo semântico, ele tentará gerar automaticamente descrições para suas tabelas e colunas. Sempre revise essas descrições para garantir que sejam razoáveis e relevantes; faça modificações conforme necessário.
Comece de forma simples e expanda gradualmente

Um arquivo semântico bem delimitado garante maior precisão e exatidão dos resultados. Comece com um pequeno número de tabelas e colunas e expanda o YAML do modelo semântico gradualmente para abranger mais tipos de perguntas. Lembre-se de que a construção do YAML é um processo contínuo.
Inclua consultas verificadas

Um repositório de consulta verificado (VQR), que é uma coleção de perguntas e consultas em inglês simples que as respondem, pode ajudar a melhorar a precisão e a confiabilidade dos resultados.

Limitações conhecidas¶

Cortex Analyst impõe um limite de tamanho de 1MB no arquivo do modelo semântico para restringir o tamanho das entradas da API.
Cortex Analyst executa a recuperação na memória de valores de amostra e consultas verificadas adicionadas do YAML semântico. Após remover todos os valores de amostra e consultas verificadas, o modelo semântico não pode exceder 32 mil tokens (aproximadamente 4 x 32 mil caracteres ou aproximadamente 128 KB). Você pode usar o comando de validação do gerador de modelo semântico para garantir que seu arquivo permaneça dentro desses limites. Os limites podem aumentar à medida que o suporte for adicionado para modelos com janelas de contexto maiores.

Especificação¶

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 (recomendado)

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.

Tabela¶

Uma tabela lógica pode ser considerada como uma exibição sobre uma tabela do banco de dados ou exibição de 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 (recomendado)

synonyms: Uma lista de outros termos/frases usados para se referir a esta tabela. Deve ser único entre sinônimos dentro da tabela lógica.
description: Uma descrição desta tabela.
dimensions: Uma lista de colunas de dimensão nesta tabela.
time_dimensions: Uma lista de colunas de dimensão de tempo nesta tabela.
measures: Uma lista de medidas nesta 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 (recomendado)

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á referenciado nas perguntas do usuário.
cortex_search_service_name: Nome do Cortex Search Service que pesquisa os valores literal na coluna. Se um nome de serviço e sample_values forem especificados, os valores no campo sample_values serão ignorados.

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 (recomendado)

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.

Medida¶

Uma medida descreve valores numéricos, como receita, impressões e salário. Ela possui os seguintes campos:

Obrigatório

name

Um nome descritivo para esta medida.

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 medida. 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 (recomendado)

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.
default_aggregation: A agregação padrão aplicada a esta coluna no contexto de um agrupamento. Alguns valores de exemplo são soma, média, mínimo, máximo, mediana, contagem, contagem_distinta etc.
sample_values: Valores de amostra desta coluna, se houver. Adicione quaisquer valores que provavelmente serão referenciados nas perguntas do usuário.

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.

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 deste filtro, referenciando colunas lógicas.

Opcional (recomendado)

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.

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.

Consultas verificadas¶

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

Exemplo de YAML¶

Esta seção mostra um exemplo de YAML do modelo semântico.

Este exemplo pressupõe que você tenha a seguinte tabela em seu esquema:

CREATE TABLE sales.public.sd_data (
    id INT PRIMARY KEY,
    dt DATETIME,
    cat VARCHAR(255),
    loc VARCHAR(255),
    cntry VARCHAR(255),
    chn VARCHAR(50),
    amt DECIMAL(10, 2),
    unts INT,
    cst DECIMAL(10, 2)
);

Copy

Esta tabela tem nomes de colunas enigmáticos e pouca informação semântica sobre as colunas. A seguir, um modelo semântico YAML que fornece mais informações semânticas sobre essa tabela:

# Name and description of the semantic model.
name: Sales Data
description: This semantic model can be used for asking questions over the sales data.

# A semantic model can contain one or more tables.
tables:

  # A logical table on top of the 'sd_data' base table.
  - name: sales_data
    description: A logical table capturing daily sales information across different store locations and product categories.

    # The fully qualified name of the base table.
    base_table:
      database: sales
      schema: public
      table: sd_data

    # Dimension columns in the logical table.
    dimensions:
      - name: product_category
        synonyms:
          - "item_category"
          - "product_type"
        description: The category of the product sold.
        expr: cat
        data_type: NUMBER
        unique: false
        sample_values:
          - "501"
          - "544"

      - name: store_country
        description: The country where the sale took place.
        expr: cntry
        data_type: TEXT
        unique: false
        sample_values:
          - "USA"
          - "GBR"

      - name: sales_channel
        synonyms:
          - "channel"
          - "distribution_channel"
        description: The channel through which the sale was made.
        expr: chn
        data_type: TEXT
        unique: false
        sample_values:
          - "FB"
          - "GOOGLE"

    # Time dimension columns in the logical table.
    time_dimensions:
      - name: sale_timestamp
        synonyms:
          - "time_of_sale"
          - "transaction_time"
        description: The time when the sale occurred. In UTC.
        expr: dt
        data_type: TIMESTAMP
        unique: false

    # Measure columns in the logical table.
    measures:
      - name: sales_amount
        synonyms:
          - "revenue"
          - "total_sales"
        description: The total amount of money generated from the sale.
        expr: amt
        data_type: NUMBER
        default_aggregation: sum

      - name: sales_tax
        description: The sales tax paid for this sale.
        expr: amt * 0.0975
        data_type: NUMBER
        default_aggregation: sum

      - name: units_sold
        synonyms:
          - "quantity_sold"
          - "number_of_units"
        description: The number of units sold in the transaction.
        expr: unts
        data_type: NUMBER
        default_aggregation: sum

      - name: cost
        description: The cost of the product sold.
        expr: cst
        data_type: NUMBER
        default_aggregation: sum

      - name: profit
        synonyms:
          - "earnings"
          - "net income"
        description: The profit generated from a sale.
        expr: amt - cst
        data_type: NUMBER
        default_aggregation: sum

    # A table can define commonly used filters over it. These filters can then be referenced in user questions directly.
    filters:
      - name: north_america
        synonyms:
          - "North America"
          - "N.A."
          - "NA"
        description: "A filter to restrict only to north american countries"
        expr: cntry IN ('canada', 'mexico', 'usa')

Copy