Pular para o conteúdo principal

Usar metadados semânticos na visualização de métricas

info

Visualização

Este recurso está em Visualização Pública.

Esta página explica como usar metadados semânticos na visualização de métricas para aprimorar a visualização de dados e melhorar a precisão do modelo de linguagem grande (LLM).

nota

Requer Databricks Runtime 17.2 ou acima. As definições YAML view de métricas devem usar a versão de especificação 1.1 ou acima. Veja o changelog da especificação da versão para mais detalhes.

O que são metadados semânticos?​

Metadados semânticos incluem nomes de exibição, especificações de formato e sinônimos que fornecem contexto adicional. Esses metadados ajudam ferramentas de visualização, como painéis de AI/BI e ferramentas de linguagem natural, como Genie spaces, a interpretar e trabalhar com seus dados de forma mais eficaz. Metadados semânticos são definidos na definição YAML de uma view de métricas.

nota

Quando você cria ou altera a exibição de métricas com a versão de especificação 1.1, todos os comentários de linha única (indicados com #) na definição YAML são removidos quando a definição é salva. Consulte Atualize seu YAML para 1.1 para obter opções e recomendações ao atualizar definições de YAML existentes.

Os seguintes tipos de metadados podem ser incluídos:

Nomes de exibição​

Os nomes de exibição fornecem rótulos legíveis que aparecem em ferramentas de visualização em vez de nomes de colunas técnicas. Os nomes de exibição são limitados a 255 caracteres.

O exemplo a seguir mostra nomes de exibição definidos na dimensão order_date e na medida total_revenue .

YAML
version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
    display_name: 'Order Date'

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    display_name: 'Total Revenue'

Sinônimos​

Sinônimos ajudam ferramentas de LLM, como AI/BI Genie, a descobrir dimensões e medidas por meio da entrada do usuário, fornecendo nomes alternativos. Você pode definir sinônimos usando o estilo de bloco ou o estilo de fluxo YAML. Cada dimensão ou medida pode ter até 10 sinônimos. Cada sinônimo é limitado a 255 caracteres.

O exemplo a seguir mostra sinônimos definidos na dimensão order_date :

YAML
version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
    # block style
    synonyms:
      - 'order time'
      - 'date of order'

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    # flow style
    synonyms: ['revenue', 'total sales']

Especificações de formato​

As especificações de formato definem como os valores devem ser exibidos nas ferramentas de visualização. As tabelas a seguir incluem tipos de formatos suportados e exemplos.

Formatos Numéricos​

Tipo de formato

Opções necessárias

Opções opcionais

Número : use o formato numérico simples para valores numéricos gerais com controle de casas decimais opcionais e opções de abreviação.

type: number

  • decimal_places: Controla o número de casas decimais mostradas após o decimal.

    • type: (Obrigatório se decimal_places for especificado)

      • max
      • exact
      • all

    • places: Valor inteiro de 0 a 10 (obrigatório se o tipo for max ou exact)

  • hide_group_separator: Quando definido como verdadeiro, remove qualquer separador de agrupamento numérico aplicável, como ,.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Moeda : Use o formato de moeda para valores monetários com códigos de moeda ISO-4217.

type: currency

  • currency_code: Código ISO-4217 (obrigatório). Por exemplo, os códigos a seguir inserem o símbolo para dólares americanos, euros e ienes, respectivamente.

    • USD
    • EUR
    • JPY

  • decimal_places: Controla o número de casas decimais mostradas após o decimal.

    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all

  • hide_group_separator: Quando definido como verdadeiro, remove qualquer separador de agrupamento numérico aplicável.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Porcentagem : use o formato de porcentagem para valores de proporção expressos como porcentagens.

type: percentage

  • decimal_places: Controla o número de casas decimais mostradas após o decimal.

    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all

  • hide_group_separator: Quando definido como verdadeiro, remove qualquer separador de agrupamento numérico aplicável.

    • true
    • false

Exemplos de formatação numérica​

YAML
format:
  type: number
  decimal_places:
    type: max
    places: 2
  hide_group_separator: false
  abbreviation: compact

Formatos de data e hora​

A tabela a seguir explica como trabalhar com formatos de data e hora.

Tipo de formato

Opções necessárias

Opções opcionais

Data : use o formato de data para valores de data com várias opções de exibição.

  • type: date
  • date_format: Controla a maneira como a data é exibida
    • locale_short_month: Exibe a data com um mês abreviado
    • locale_long_month: Exibe a data com o nome completo do mês
    • year_month_day: Formata a data como AAAA-MM-DD
    • locale_number_month: Exibe a data com um mês como um número
    • year_week: Formata a data como um ano e um número de semana. Por exemplo, 2025-W1
  • leading_zeros: Controla se números de um único dígito são precedidos por zero
  • true
  • false

DateTime : Use o formato datetime para valores de registro de data e hora combinando data e hora.

  • type: date_time

  • date_format: Controla a maneira como a data é exibida

    • no_date:Data oculta
    • locale_short_month: Exibe a data com um mês abreviado
    • locale_long_month: Exibe a data com o nome completo do mês
    • year_month_day: Formata a data como AAAA-MM-DD
    • locale_number_month: Exibe a data com um mês como um número
    • year_week: Formata a data como um ano e um número de semana. Por exemplo, 2025-W1

  • time_format:

    • no_time:O tempo está escondido
    • locale_hour_minute: Exibe a hora e o minuto
    • locale_hour_minute_second: Exibe a hora, o minuto e o segundo
  • leading_zeros: Controla se números de um único dígito são precedidos por zero
    • true
    • false
nota

Ao trabalhar com um tipo date_time , pelo menos um de date_format ou time_format deve especificar um valor diferente de no_date ou no_time.

Exemplos de formatação de data e hora​

YAML
format:
  type: date
  date_format: year_month_day
  leading_zeros: true

Exemplo completo​

O exemplo a seguir mostra uma definição view de métricas que inclui todos os tipos de metadados semânticos:

YAML
version: 1.1
source: samples.tpch.orders
comment: Comprehensive sales metrics with enhanced semantic metadata
dimensions:
  - name: order_date
    expr: o_orderdate
    comment: Date when the order was placed
    display_name: Order Date
    format:
      type: date
      date_format: year_month_day
      leading_zeros: true
    synonyms:
      - order time
      - date of order
  - name: customer_segment
    expr: |
      CASE
        WHEN o_totalprice > 100000 THEN 'Enterprise'
        WHEN o_totalprice > 10000 THEN 'Mid-market'
        ELSE 'SMB'
      END
    comment: Customer classification based on order value
    display_name: Customer Segment
    synonyms:
      - segment
      - customer tier
measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: Total revenue from all orders
    display_name: Total Revenue
    format:
      type: currency
      currency_code: USD
      decimal_places:
        type: exact
        places: 2
      hide_group_separator: false
      abbreviation: compact
    synonyms:
      - revenue
      - total sales
      - sales amount
  - name: order_count
    expr: COUNT(1)
    comment: Total number of orders
    display_name: Order Count
    format:
      type: number
      decimal_places:
        type: all
      hide_group_separator: true
    synonyms:
      - count
      - number of orders
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(1)
    comment: Average revenue per order
    display_name: Average Order Value
    format:
      type: currency
      currency_code: USD
      decimal_places:
        type: exact
        places: 2
    synonyms:
      - aov
      - average revenue
Última atualização em