Metadati dell'agente nelle visualizzazioni delle metriche

I metadati dell'agente (noti anche come metadati semantici) migliorano la visualizzazione dei dati e migliorano l'accuratezza del modello linguistico di grandi dimensioni fornendo nomi visualizzati, specifiche di formato e sinonimi che forniscono contesto aziendale alle metriche. Questi metadati consentono agli strumenti di visualizzazione e agli strumenti del linguaggio naturale, come gli spazi Genie, di interpretare e usare i dati in modo più efficace.

Annotazioni

Richiede Databricks Runtime 17.3 e YAML versione 1.1. Vedere i requisiti della versione.

Che cos'è i metadati dell'agente?

I metadati dell'agente includono nomi visualizzati, specifiche di formato e sinonimi che forniscono contesto aggiuntivo. Questi metadati aiutano strumenti di visualizzazione, ad esempio dashboard AI/BI, e strumenti di linguaggio naturale, come spazi Genie, a interpretare e utilizzare i dati in modo più efficace. I metadati dell'agente vengono definiti nella definizione YAML della visualizzazione metrica.

Annotazioni

Quando si creano o modificano le visualizzazioni delle metriche con la versione 1.1 della specifica, tutti i commenti a riga singola (indicati con #) nella definizione YAML vengono rimossi quando la definizione viene salvata. Vedere Aggiornare YAML alla versione 1.1 per le opzioni e le raccomandazioni durante l'aggiornamento delle definizioni YAML esistenti.

Gli esempi in questa pagina usano il set di dati di esempio TPC-H (samples.tpch.orders), disponibile per impostazione predefinita nei set di dati del catalogo Unity. Il set di dati TPC-H modella una supply chain all'ingrosso con tabelle per ordini, clienti, fornitori e parti. I nomi di colonna nella orders tabella usano il o_ prefisso ( ad esempio, o_orderdate per la data dell'ordine, o_totalprice per il prezzo totale). Per informazioni dettagliate sullo schema e sul modello di dati di TPC-H, vedere Esercitazione: Creare una visualizzazione metrica completa con join.

Nomi visualizzati

I nomi visualizzati forniscono etichette leggibili che vengono visualizzate negli strumenti di visualizzazione anziché nei nomi delle colonne tecniche. I nomi visualizzati sono limitati a 255 caratteri.

Nell'esempio seguente vengono mostrati i nomi di visualizzazione definiti nella dimensione order_date (monitoraggio di quando sono stati effettuati gli ordini) e nella misura total_revenue (calcolo della somma di tutti i prezzi degli ordini).

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'

Sinonimi

I sinonimi consentono agli strumenti LLM, ad esempio Genie, di individuare dimensioni e misure tramite l'input dell'utente fornendo nomi alternativi. È possibile definire sinonimi usando lo stile del blocco o lo stile del flusso YAML. Ogni dimensione o misura può avere fino a 10 sinonimi. Ogni sinonimo è limitato a 255 caratteri.

Nell'esempio seguente vengono illustrati i sinonimi definiti nella order_date dimensione (quando gli ordini sono stati inseriti) e total_revenue la misura (somma di tutti i prezzi degli ordini). I sinonimi consentono agli utenti di porre domande usando il linguaggio naturale, ad esempio "mostra i ricavi in base all'ora dell'ordine" o "quali sono le vendite totali per data dell'ordine":

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']

Specifiche di formato

Le specifiche di formato definiscono la modalità di visualizzazione dei valori negli strumenti di visualizzazione. Le tabelle seguenti includono tipi di formato e esempi supportati.

Formati numerici

Tipo di formato	Opzioni obbligatorie	Opzioni facoltative
Numero: usare il formato numerico normale per i valori numerici generali con opzioni facoltative per il controllo della posizione decimale e l'abbreviazione.	type: number	decimal_places: controlla il numero di posizioni visualizzate dopo il decimale. type: (obbligatorio se decimal_places specificato) max exact all places: valore intero compreso tra 0 e 10 (obbligatorio se il tipo è max o exact) hide_group_separator: se impostato su true, rimuove qualsiasi separatore di raggruppamento di numeri applicabile, ad esempio ., true false abbreviation: none compact scientific
Valuta: usare il formato valuta per i valori monetari con codici di valuta ISO-4217.	type: currency	currency_code: codice ISO-4217 (obbligatorio). Ad esempio, i codici seguenti inseriscono rispettivamente il simbolo per dollari, euro e yen statunitensi. USD EUR JPY decimal_places: controlla il numero di posizioni visualizzate dopo il decimale. type: (obbligatorio se decimal_places specificato) max exact all hide_group_separator: se impostato su true, rimuove qualsiasi separatore di raggruppamento di numeri applicabile. true false abbreviation: none compact scientific
Percentuale: usare il formato percentuale per i valori di rapporto espressi come percentuali.	type: percentage	decimal_places: controlla il numero di posizioni visualizzate dopo il decimale. type: (obbligatorio se decimal_places specificato) max exact all hide_group_separator: se impostato su true, rimuove qualsiasi separatore di raggruppamento di numeri applicabile. true false
Byte: usare il formato byte per i valori delle dimensioni dei dati visualizzati con unità di byte appropriate (KB, MB, GB e così via).	type: byte	decimal_places: controlla il numero di posizioni visualizzate dopo il decimale. type: (obbligatorio se decimal_places specificato) max exact all places: valore intero compreso tra 0 e 10 (obbligatorio se il tipo è max o exact) hide_group_separator: se impostato su true, rimuove qualsiasi separatore di raggruppamento di numeri applicabile. true false

Esempi di formattazione numerica

Number

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

Valuta

format:
  type: currency
  currency_code: USD
  decimal_places:
    type: exact
    places: 2
  hide_group_separator: false
  abbreviation: compact

Percentuale

format:
  type: percentage
  decimal_places:
    type: all
  hide_group_separator: true

Byte

format:
  type: byte
  decimal_places:
    type: max
    places: 2
  hide_group_separator: false

Formati di data e ora

Nella tabella seguente viene illustrato come usare i formati di data e ora.

Tipo di formato	Opzioni obbligatorie	Opzioni facoltative
Data: usare il formato data per i valori di data con varie opzioni di visualizzazione.	type: date date_format: controlla la modalità di visualizzazione della data locale_short_month: visualizza la data con un mese abbreviato locale_long_month: visualizza la data con il nome completo del mese year_month_day: formatta la data come AAAA-MM-DD locale_number_month: visualizza la data con un mese come numero year_week: formatta la data come anno e un numero di settimana. Ad esempio, 2025-W1	leading_zeros: controlla se i numeri a cifra singola sono preceduti da zero true false
DateTime: usare il formato datetime per i valori timestamp che combinano data e ora.	type: date_time date_format: controlla la modalità di visualizzazione della data no_date: la data è nascosta locale_short_month: visualizza la data con un mese abbreviato locale_long_month: visualizza la data con il nome completo del mese year_month_day: formatta la data come AAAA-MM-DD locale_number_month: visualizza la data con un mese come numero year_week: formatta la data come anno e un numero di settimana. Ad esempio, 2025-W1 time_format: no_time: l'ora è nascosta locale_hour_minute: visualizza l'ora e il minuto locale_hour_minute_second: visualizza l'ora, il minuto e il secondo	leading_zeros: controlla se i numeri a cifra singola sono preceduti da zero true false

Annotazioni

Quando si utilizza un date_time tipo, almeno uno di date_format o time_format deve specificare un valore diverso da no_date o no_time.

Esempi di formattazione data e ora

Date

format:
  type: date
  date_format: year_month_day
  leading_zeros: true

DateTime

format:
  type: date_time
  date_format: year_month_day
  time_format: locale_hour_minute_second
  leading_zeros: false

Integrazione degli strumenti downstream

I metadati semantici popolano automaticamente gli strumenti downstream che usano la visualizzazione metrica:

• Dashboard di intelligenza artificiale/BI: i nomi visualizzati e le specifiche di formato vengono popolati automaticamente nei set di dati e nelle visualizzazioni del dashboard per migliorare la leggibilità del dashboard.
• Spazi genie: i sinonimi vengono importati automaticamente per aiutare Genie a individuare e comprendere meglio le dimensioni e le misure disponibili dalla vista metrica.

Esempio completo

L'esempio seguente mostra una definizione di visualizzazione delle metriche che tiene traccia delle prestazioni delle vendite e include tutti i tipi di metadati dell'agente. La visualizzazione delle metriche analizza i dati degli ordini per calcolare le metriche dei ricavi, segmentare i clienti in base al valore dell'ordine e tenere traccia dei volumi degli ordini.

I segmenti dei clienti sono definiti come segue:

• Enterprise: ordini superiori a $ 100.000
• Mid-market: ordini compresi tra $10.000 e $100.000
• Piccole e medie imprese: ordini inferiori a 10.000 dollari

I metadati supportano query in linguaggio naturale, ad esempio "mostra le vendite totali per segmento di clienti" o "qual è il fatturato medio per ordine".

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