Freigeben über

Agentmetadaten in Metrikansichten

Agentmetadaten (auch als semantische Metadaten bezeichnet) verbessern die Datenvisualisierung und verbessern die Genauigkeit des großen Sprachmodells (LLM), indem Anzeigenamen, Formatspezifikationen und Synonyme bereitgestellt werden, die Ihren Metriken Geschäftskontext verleihen. Diese Metadaten helfen Visualisierungstools und natürliche Sprachtools wie Genie-Räume, Ihre Daten besser zu interpretieren und effektiver mit ihnen zu arbeiten.

Hinweis

Erfordert Databricks Runtime 17.3 und YAML, Version 1.1. Siehe Versionsanforderungen.

Was ist Agent-Metadaten?

Agentmetadaten umfassen Anzeigenamen, Formatspezifikationen und Synonyme, die zusätzlichen Kontext bereitstellen. Diese Metadaten helfen Visualisierungstools, wie KI/BI-Dashboards, und natursprachlichen Werkzeugen, wie Genie-Räume, Ihre Daten effektiver zu interpretieren und mit ihnen zu arbeiten. Agentmetadaten werden in der YaML-Definition der Metrikansicht definiert.

Hinweis

Wenn Sie Metrikansichten mit Spezifikationsversion 1.1 erstellen oder ändern, werden alle Kommentare in einer Zeile (mit #) in der YAML-Definition entfernt, wenn die Definition gespeichert wird. Informationen zu Optionen und Empfehlungen beim Aktualisieren vorhandener YAML-Definitionen finden Sie unter Upgrade Ihres YAML auf 1.1 .

Die Beispiele auf dieser Seite verwenden das TPC-H Beispiel-Dataset (samples.tpch.orders), das standardmäßig in Unity Catalog-Datasets verfügbar ist. Das TPC-H-Datasets modelliert eine Großhandels-Lieferkette mit Tabellen für Bestellungen, Kunden, Lieferanten und Teile. Spaltennamen in der orders Tabelle verwenden das o_ Präfix (z. B. o_orderdate für das Bestelldatum, o_totalprice für den Gesamtpreis). Ausführliche Informationen zum TPC-H Schema- und Datenmodells finden Sie im Lernprogramm: Erstellen einer vollständigen Metrikansicht mit Verknüpfungen.

Anzeigenamen

Anzeigenamen bieten lesbare Bezeichnungen, die in Visualisierungstools anstelle von technischen Spaltennamen angezeigt werden. Anzeigenamen sind auf 255 Zeichen beschränkt.

Das folgende Beispiel zeigt Anzeigenamen, die für die order_date Dimension definiert sind (Nachverfolgung, wann Bestellungen aufgegeben wurden) und total_revenue Messen (berechnung der Summe aller Auftragspreise).

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'

Synonyme

Synonyme helfen LLM-Tools wie Genie, Dimensionen und Maßnahmen über Benutzereingaben zu erkennen, indem sie alternative Namen bereitstellen. Sie können Synonyme entweder mithilfe von Blockstil oder Flow-Stil YAML definieren. Jede Dimension oder jedes Maß kann bis zu 10 Synonyme aufweisen. Jedes Synonym ist auf 255 Zeichen beschränkt.

Das folgende Beispiel zeigt Synonyme, die für die order_date Dimension definiert sind (wann Bestellungen aufgegeben wurden) und total_revenue Maß (Summe aller Auftragspreise). Mit den Synonymen können Benutzer Fragen mit natürlicher Sprache stellen, z. B. "Zeige mir den Umsatz nach Bestellzeit" oder "Wie hoch ist der Gesamtumsatz nach Bestelldatum".

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

Formatspezifikationen

Formatspezifikationen definieren, wie Werte in Visualisierungstools angezeigt werden sollen. Die folgenden Tabellen enthalten unterstützte Formattypen und Beispiele.

Numerische Formate

Formattyp Erforderliche Optionen Optionale Optionen
Zahl: Verwenden Sie einfaches Zahlenformat für allgemeine numerische Werte mit optionalen Dezimalplatz-Steuerelementen und Abkürzungsoptionen. type: number
  • decimal_places: Bestimmt die Anzahl der Stellen nach dem Dezimaltrennzeichen.
    • type: (Erforderlich, wenn decimal_places angegeben)
      • max
      • exact
      • all
    • places: Ganzzahliger Wert von 0-10 (erforderlich, wenn Typ ist max oder exact)
  • hide_group_separator: Wenn dieser Wert auf "true" festgelegt ist, werden alle anwendbaren Nummerngruppierungstrennzeichen entfernt, z. B. ein ,.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Währung: Währungsformat für Geldwerte mit ISO-4217-Währungscodes verwenden. type: currency
  • currency_code: ISO-4217-Code (erforderlich). Die folgenden Codes fügen z. B. das Symbol für US-Dollar, Euro und Yen ein.
    • USD
    • EUR
    • JPY
  • decimal_places: Bestimmt die Anzahl der Stellen nach dem Dezimaltrennzeichen.
    • type: (Erforderlich, wenn decimal_places angegeben)
      • max
      • exact
      • all
  • hide_group_separator: Wenn dieser Wert auf "true" festgelegt ist, werden alle anwendbaren Nummerngruppierungstrennzeichen entfernt.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Prozentsatz: Verwenden Sie das Prozentformat für Verhältniswerte, die als Prozentwerte ausgedrückt werden. type: percentage
  • decimal_places: Bestimmt die Anzahl der Stellen nach dem Dezimaltrennzeichen.
    • type: (Erforderlich, wenn decimal_places angegeben)
      • max
      • exact
      • all
  • hide_group_separator: Wenn dieser Wert auf "true" festgelegt ist, werden alle anwendbaren Nummerngruppierungstrennzeichen entfernt.
    • true
    • false
Byte: Verwenden Sie das Byteformat für Datengrößenwerte, die mit entsprechenden Byteeinheiten (KB, MB, GB usw.) angezeigt werden. type: byte
  • decimal_places: Bestimmt die Anzahl der Stellen nach dem Dezimaltrennzeichen.
    • type: (Erforderlich, wenn decimal_places angegeben)
      • max
      • exact
      • all
    • places: Ganzzahliger Wert von 0-10 (erforderlich, wenn Typ ist max oder exact)
  • hide_group_separator: Wenn dieser Wert auf "true" festgelegt ist, werden alle anwendbaren Nummerngruppierungstrennzeichen entfernt.
    • true
    • false

Beispiele für numerische Formatierungen

Nummer

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

Währungen

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

Prozentsatz

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

Datums- und Uhrzeitformate

In der folgenden Tabelle wird erläutert, wie Sie mit Datums- und Uhrzeitformaten arbeiten.

Formattyp Erforderliche Optionen Optionale Optionen
Datum: Verwenden Sie das Datumsformat für Datumswerte mit verschiedenen Anzeigeoptionen.
  • type: date
  • date_format: Steuert, wie das Datum angezeigt wird.
    • locale_short_month: Zeigt das Datum mit einem abgekürzten Monat an.
    • locale_long_month: Zeigt das Datum mit dem vollständigen Namen des Monats an.
    • year_month_day: Formatiert das Datum als JJJJ-MM-DD
    • locale_number_month: Zeigt das Datum mit einem Monat als Zahl an.
    • year_week: Formatiert das Datum als Jahr und eine Wochenzahl. Beispiel: 2025-W1
  • leading_zeros: Steuert, ob einstellige Zahlen einer Null vorangestellt sind.
  • true
  • false
DateTime: Verwenden Sie das Datetime-Format für Zeitstempelwerte, die Datum und Uhrzeit kombinieren.
  • type: date_time
  • date_format: Steuert, wie das Datum angezeigt wird.
    • no_date: Datum ist ausgeblendet
    • locale_short_month: Zeigt das Datum mit einem abgekürzten Monat an.
    • locale_long_month: Zeigt das Datum mit dem vollständigen Namen des Monats an.
    • year_month_day: Formatiert das Datum als JJJJ-MM-DD
    • locale_number_month: Zeigt das Datum mit einem Monat als Zahl an.
    • year_week: Formatiert das Datum als Jahr und eine Wochenzahl. Beispiel: 2025-W1
  • time_format:
    • no_time: Die Uhrzeit ist ausgeblendet.
    • locale_hour_minute: Zeigt die Stunde und Minute an.
    • locale_hour_minute_second: Zeigt die Stunde, Minute und Sekunde an.
  • leading_zeros: Steuert, ob einstellige Zahlen einer Null vorangestellt sind.
    • true
    • false

Hinweis

Wenn Sie mit einem date_time-Typ arbeiten, müssen mindestens date_format oder time_format einen anderen Wert als no_date oder no_time angeben.

Datetime-Formatierungsbeispiele

Datum

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

Integration nachgeschalteter Tools

Semantische Metadaten füllen automatisch nachgeschaltete Tools auf, die die Metrikansicht nutzen:

  • AI/BI-Dashboards: Anzeigenamen und Formatspezifikationen werden automatisch in Dashboard-Datasets und Visualisierungen aufgefüllt, um die Lesbarkeit des Dashboards zu verbessern.
  • Genie Spaces: Synonyme werden automatisch importiert, um Genie dabei zu helfen, verfügbare Dimensionen und Kennzahlen aus der Metrikansicht besser zu erkennen und zu verstehen.

Vollständiges Beispiel

Das folgende Beispiel zeigt eine Metrikansichtsdefinition, die die Vertriebsleistung nachverfolgt und alle Agent-Metadatentypen enthält. In der Metrikansicht werden Bestelldaten analysiert, um Umsatzmetriken zu berechnen, Kunden nach Auftragswert zu segmentieren und Bestellvolumen nachzuverfolgen.

Kundensegmente werden wie folgt definiert:

  • Enterprise: Bestellungen über 100.000 $
  • Mittlerer Markt: Aufträge zwischen 10.000 $ und 100.000 $
  • Kleine und mittlere Unternehmen: Bestellungen unter 10.000 $

Die Metadaten unterstützen Abfragen in natürlicher Sprache, z. B. "Gesamtumsatz nach Kundensegment anzeigen" oder "Was ist der durchschnittliche Umsatz pro Bestellung".

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
  • Last updated on