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.

Metadados semânticos na visualização de métricas fornecem contexto e informações adicionais que aprimoram a visualização de dados e melhoram a precisão do modelo de linguagem grande (LLM) ao trabalhar com a visualização de métricas. Os metadados incluem nomes de exibição, especificações de formato e sinônimos que ajudam ferramentas de visualização, como painéis AI/BI e ferramentas AI de linguagem natural, como Genie spaces, a entender e trabalhar com seus dados de forma mais eficaz.

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?

Os metadados semânticos fornecem contexto e informações adicionais para view dimensões e medidas. É definido na definição YAML para a view métricas. A seguir estão os tipos de metadados que você pode incluir.

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.

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.

    • 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