Metadata agenta v zobrazeních metrik

Metadata agenta (označovaná také jako sémantická metadata) vylepšují vizualizaci dat a vylepšují přesnost velkého jazykového modelu (LLM) tím, že poskytují zobrazované názvy, specifikace formátu a synonyma, které poskytují obchodnímu kontextu metriky. Tato metadata pomáhají vizualizačním nástrojům a nástrojům přirozeného jazyka, jako jsou agenti Genie, interpretovat data a pracovat s daty efektivněji.

Poznámka:

Vyžaduje Databricks Runtime 17.3 a YAML verze 1.1. Viz požadavky na verzi.

Co jsou metadata agenta?

Metadata agenta zahrnují zobrazované názvy, specifikace formátu a synonyma, která poskytují další kontext. Tato metadata pomáhají vizualizačním nástrojům, jako jsou řídicí panely AI/BI a nástroje přirozeného jazyka, jako jsou Agenti Genie, interpretovat data a pracovat s daty efektivněji. Metadata agenta jsou definována v zobrazení metrik YAML.

Poznámka:

Při vytváření nebo změně zobrazení metrik se specifikací verze 1.1 se při uložení definice YAML odeberou všechny jednořádkové komentáře (označené ) #v definici YAML. Informace o možnostech a doporučeních při upgradu existujících definic YAML najdete v tématu Upgrade na YAML 1.1 .

Příklady na této stránce používají ukázkovou datovou sadu TPC-H (samples.tpch.orders), která je ve výchozím nastavení k dispozici v datových sadách katalogu Unity. Datová sada TPC-H modeluje velkoobchodní dodavatelský řetězec s tabulkami pro objednávky, zákazníky, dodavatele a části. Názvy sloupců v orders tabulce používají předponu (například o_ pro datum o_orderdate objednávky pro celkovou o_totalprice cenu). Podrobnosti o schématu TPC-H a datovém modelu najdete v kurzu: Vytvoření zobrazení metriky s propojeními a modelováním dat.

Zobrazované názvy

Zobrazované názvy poskytují popisky čitelné pro člověka, které se zobrazují v nástrojích vizualizace místo technických názvů sloupců. Zobrazované názvy jsou omezené na 255 znaků.

Následující příklad ukazuje zobrazované názvy definované v order_date poli (sledování, kdy byly objednávky zadány) a total_revenue míra (výpočet součtu všech cen objednávek).

version: 1.1
source: samples.tpch.orders

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

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

Synonyms

Synonyma pomáhají nástrojům LLM, jako je Genie, zjišťovat pole (označovaná také jako dimenze) a míry prostřednictvím uživatelského vstupu zadáním alternativních názvů. Synonyma můžete definovat pomocí stylu bloku nebo stylu toku YAML. Každé pole nebo míra můžou mít až 10 synonym. Každé synonymum je omezeno na 255 znaků.

Následující příklad ukazuje synonyma definovaná v order_date poli (při zadání objednávek) a total_revenue míru (součet všech cen objednávek). Synonyma umožňují uživatelům klást otázky pomocí přirozeného jazyka, například "show me revenue by order time" (zobrazit výnosy podle času objednávky) nebo "what are total sales by date of order":

version: 1.1
source: samples.tpch.orders

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

Specifikace formátu

Specifikace formátu definují, jak se mají hodnoty zobrazovat v nástrojích pro vizualizaci. Následující tabulky obsahují podporované typy formátů a příklady.

Číselné formáty

Typ formátu Požadované možnosti Volitelné možnosti
Číslo: Pro obecné číselné hodnoty s volitelným ovládacím prvku desetinné čárky a možnostmi zkratek použijte formát prostého čísla. type: number
  • decimal_places: Určuje počet míst zobrazených za desetinnou čárkou.
    • type: (Povinné, pokud decimal_places je zadáno)
      • max
      • exact
      • all
    • places: Celočíselná hodnota od 0 do 10 (povinné, pokud je max typ nebo exact)
  • hide_group_separator: Pokud je nastavena hodnota true, odebere všechny platné oddělovače seskupení čísel, například ,.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Měna: Použijte formát měny pro peněžní hodnoty s kódy měny ISO-4217. type: currency
  • currency_code: Kód ISO-4217 (povinný). Například následující kódy vloží symbol amerických dolarů, eur a jenů v uvedeném pořadí.
    • USD
    • EUR
    • JPY
  • decimal_places: Určuje počet míst zobrazených za desetinnou čárkou.
    • type: (Povinné, pokud decimal_places je zadáno)
      • max
      • exact
      • all
  • hide_group_separator: Pokud je nastavená hodnota true, odebere všechny příslušné oddělovače seskupování čísel.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Procento: Pro hodnoty poměru vyjádřené jako procenta použijte procentuální formát. type: percentage
  • decimal_places: Určuje počet míst zobrazených za desetinnou čárkou.
    • type: (Povinné, pokud decimal_places je zadáno)
      • max
      • exact
      • all
  • hide_group_separator: Pokud je nastavená hodnota true, odebere všechny příslušné oddělovače seskupování čísel.
    • true
    • false
Bajt: Pro hodnoty velikosti dat zobrazené s příslušnými bajtovými jednotkami (KB, MB, GB atd.) použijte formát bajtu. type: byte
  • decimal_places: Určuje počet míst zobrazených za desetinnou čárkou.
    • type: (Povinné, pokud decimal_places je zadáno)
      • max
      • exact
      • all
    • places: Celočíselná hodnota od 0 do 10 (povinné, pokud je max typ nebo exact)
  • hide_group_separator: Pokud je nastavená hodnota true, odebere všechny příslušné oddělovače seskupování čísel.
    • true
    • false

Příklady číselného formátování

Number

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

Měna

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

Procento

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

Formáty data a času

Následující tabulka vysvětluje, jak pracovat s formáty data a času.

Typ formátu Požadované možnosti Volitelné možnosti
Datum: Pro hodnoty kalendářních dat použijte formát data s různými možnostmi zobrazení.
  • type: date
  • date_format: Určuje způsob zobrazení data.
    • locale_short_month: Zobrazí datum s zkráceným měsícem.
    • locale_long_month: Zobrazí datum s úplným názvem měsíce.
    • year_month_day: Formátuje datum jako YYYY-MM-DD
    • locale_number_month: Zobrazí datum s měsícem jako číslem.
    • year_week: Formátuje datum jako rok a číslo týdne. Například 2025-W1
  • leading_zeros: Určuje, zda jsou jednociferná čísla doplněna nulou před nimi.
  • true
  • false
DateTime: Pro hodnoty časového razítka zkombinující datum a čas použijte formát datetime.
  • type: date_time
  • date_format: Určuje způsob zobrazení data.
    • no_date: Datum je skryté.
    • locale_short_month: Zobrazí datum s zkráceným měsícem.
    • locale_long_month: Zobrazí datum s úplným názvem měsíce.
    • year_month_day: Formátuje datum jako YYYY-MM-DD
    • locale_number_month: Zobrazí datum s měsícem jako číslem.
    • year_week: Formátuje datum jako rok a číslo týdne. Například 2025-W1
  • time_format:
    • no_time: Čas je skrytý.
    • locale_hour_minute: Zobrazí hodinu a minutu.
    • locale_hour_minute_second: Zobrazí hodinu, minutu a sekundu.
  • leading_zeros: Určuje, zda jsou jednociferná čísla uváděna s nulou na začátku.
    • true
    • false

Poznámka:

Při práci s typem date_time musí alespoň jeden z date_format nebo time_format musí zadat jinou hodnotu než no_date nebo no_time.

Příklady formátování data a času

Date

format:
  type: date
  date_format: year_month_day
  leading_zeros: true

Datum a čas

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

Integrace podřízených nástrojů

Sémantická metadata automaticky naplní podřízené nástroje, které využívají zobrazení metrik:

  • Řídicí panely AI/BI: Zobrazované názvy a specifikace formátu se automaticky vyplní v datových sadách a vizualizacích řídicích panelů, aby se zlepšila čitelnost řídicího panelu.
  • Agenti Genie: Synonyma se automaticky naimportují, aby Genie lépe objevila dostupná pole a míry z zobrazení metrik a porozuměla jim.

Kompletní příklad

Následující příklad ukazuje definici zobrazení metrik, která sleduje prodejní výkon a zahrnuje všechny typy metadat agenta. Zobrazení metriky analyzuje data objednávek, aby vypočítala metriky výnosů, segmentuje zákazníky podle hodnoty objednávky a sleduje objemy objednávek.

Segmenty zákazníků jsou definovány takto:

  • Organizace: Objednávky nad 100 000 KČ
  • Střední trh: Objednávky mezi 10 000 a 100 000 Kč
  • Malé a střední firmy: Objednávky do 10 000 KČ

Metadata podporují dotazy v přirozeném jazyce, například "show me total sales by customer segment" (zobrazit celkový prodej podle segmentu zákazníka) nebo "what's the average revenue per order" (jaké jsou průměrné výnosy za objednávku).

version: 1.1
source: samples.tpch.orders
comment: Comprehensive sales metrics with enhanced semantic metadata
fields:
  - 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
  • Last updated on