メインコンテンツまでスキップ
に最終更新

メトリクスビューにおけるエージェント メタデータ

エージェントメタデータ（セマンティックメタデータとも呼ばれます）は、表示名、形式仕様、およびビジネスコンテキストをメトリクスに付与する同義語を提供することで、データ可視化を強化し、大規模言語モデル（LLM）の精度を向上させます。このメタデータは、可視化ツールやGenieエージェントのような自然言語ツールがデータをより効果的に解釈し、操作するのに役立ちます。

注記

Databricks Runtime 17.3とYAMLバージョン1.1が必要です。バージョン要件を参照してください。

エージェントメタデータとは何ですか？​

エージェント メタデータには、表示名、書式設定、および追加のコンテキストを提供する同義語が含まれます。このメタデータは、AI/BI ダッシュボードなどの可視化ツールや、Genie エージェントなどの自然言語ツールが、データをより効果的に解釈し、操作するのに役立ちます。エージェント メタデータは、メトリクス ビューの YAML 定義で定義されています。

注記

仕様バージョン 1.1 のメトリクスビューを作成または変更すると、YAML 定義内の単一行コメント (# で示される) は、定義が保存されるときに削除されます。既存の YAML 定義をアップグレードする際のオプションと推奨事項については、YAML 1.1 へのアップグレードを参照してください。

このページの例では、TPC-Hサンプルデータセット（samples.tpch.orders）を使用しています。これは、Unity Catalog datasetsでdefaultで利用できます。TPC-Hデータセットは、注文、顧客、サプライヤー、部品のテーブルを含む卸売サプライチェーンをモデル化しています。ordersテーブルの列名にはo_プレフィックスが使用されます（例：注文日にはo_orderdate、合計価格にはo_totalprice）。TPC-Hスキーマとデータモデルの詳細については、「チュートリアル: 結合とデータモデリングによるメトリクスビューの構築」を参照してください。

表示名​

表示名は、技術的な列名の代わりに、視覚化ツールに表示される人間が判読できるラベルを提供します。表示名は255文字に制限されています。

次の例は、order_dateフィールド（注文がいつ行われたかを追跡する）とtotal_revenueメジャー（すべての注文価格の合計を計算する）に定義されている表示名を示します。

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

同義語​

類義語は、代替名を提供することで、ユーザー入力を介して、Genie のような LLM ツールがフィールド（ディメンションとも呼ばれます）とメジャーを検出するのに役立ちます。ブロック形式またはフロー形式のYAMLを使用して、類義語を定義できます。各フィールドまたはメジャーは、最大10個の類義語を持つことができます。各類義語は255文字に制限されています。

次の例は、order_dateフィールド（注文が発注されたとき）とtotal_revenueメジャー（すべての注文価格の合計）で定義されたシノニムを示しています。シノニムを使用すると、ユーザーは「注文時間別の収益を表示」や「注文日別の総売上高」などの自然言語を使用して質問できます。

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

書式仕様​

書式指定は、ビジュアライゼーションツールにおける値の表示方法を定義します。次の表には、サポートされている形式と例が含まれています。

数値の書式設定​

形式タイプ

必須オプション

オプション

数値 ：一般的な数値に、小数位の制御と省略オプションを任意で指定できます。

type: number

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。

      • max
      • exact
      • all

    • places：0～10の整数値（タイプがmaxまたはexactの場合に必須）

  • hide_group_separatortrueに設定されている場合、,などの適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

通貨 : ISO-4217通貨コードを使用して、通貨値には通貨形式を使用します。

type: currency

  • currency_code：ISO-4217コード（必須）。たとえば、次のコードはそれぞれ米ドル、ユーロ、円の記号を挿入します。

    • USD
    • EUR
    • JPY

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。
      • max
      • exact
      • all

  • hide_group_separatortrueに設定されている場合、適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

パーセンテージ ：パーセンテージとして表される比率値には、パーセンテージ形式を使用します。

type: percentage

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。
      • max
      • exact
      • all

  • hide_group_separatortrueに設定されている場合、適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

バイト ：適切なバイト単位 (KB、MB、GB など) で表示されるデータサイズ値にバイト形式を使用してください。

type: byte

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。

      • max
      • exact
      • all

    • places：0～10の整数値（タイプがmaxまたはexactの場合に必須）

  • hide_group_separatortrueに設定されている場合、適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

形式タイプ

必須オプション

オプション

数値 ：一般的な数値に、小数位の制御と省略オプションを任意で指定できます。

type: number

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。

      • max
      • exact
      • all

    • places：0～10の整数値（タイプがmaxまたはexactの場合に必須）

  • hide_group_separatortrueに設定されている場合、,などの適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

通貨 : ISO-4217通貨コードを使用して、通貨値には通貨形式を使用します。

type: currency

  • currency_code：ISO-4217コード（必須）。たとえば、次のコードはそれぞれ米ドル、ユーロ、円の記号を挿入します。

    • USD
    • EUR
    • JPY

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。
      • max
      • exact
      • all

  • hide_group_separatortrueに設定されている場合、適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

パーセンテージ ：パーセンテージとして表される比率値には、パーセンテージ形式を使用します。

type: percentage

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。
      • max
      • exact
      • all

  • hide_group_separatortrueに設定されている場合、適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

バイト ：適切なバイト単位 (KB、MB、GB など) で表示されるデータサイズ値にバイト形式を使用してください。

type: byte

  • decimal_places: 小数点以下の桁数を制御します。

    • type：(decimal_placesが指定されている場合、必須)です。

      • max
      • exact
      • all

    • places：0～10の整数値（タイプがmaxまたはexactの場合に必須）

  • hide_group_separatortrueに設定されている場合、適用可能な数字のグループ区切り文字は削除されます。

    • true
    • false

数値書式設定の例​

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

日付と時刻の形式​

次の表は、日付と時刻の書式を操作する方法を説明します。

形式タイプ

必須オプション

オプション

日付 ：日付値には日付フォーマットを使用し、さまざまな表示オプションを指定します。

  • type: date
  • date_format：日付の表示方法を制御します。
    • locale_short_month略称の月で日付を表示します
    • locale_long_month：月のフルネームで日付を表示します。
    • year_month_day日付の形式をYYYY-MM-DDに設定します。
    • locale_number_month月を数値として日付を表示します。
    • year_week日付を年と週番号の形式でフォーマットします。例えば、 2025-W1
  • leading_zeros1桁の数値の前にゼロが付くかどうかを制御します
  • true
  • false

DateTime ：日付と時刻を組み合わせたTimestamp値には、datetime形式を使用してください。

  • type: date_time

  • date_format：日付の表示方法を制御します。

    • no_date: 日付は非表示です
    • locale_short_month略称の月で日付を表示します
    • locale_long_month：月のフルネームで日付を表示します。
    • year_month_day日付の形式をYYYY-MM-DDに設定します。
    • locale_number_month月を数値として日付を表示します。
    • year_week日付を年と週番号の形式でフォーマットします。例えば、 2025-W1

  • time_format:

    • no_time時間：非表示
    • locale_hour_minute: 時と分を表示します。
    • locale_hour_minute_second時、分、秒を表示します。
  • leading_zeros1桁の数値の前にゼロが付くかどうかを制御します
    • true
    • false

形式タイプ

必須オプション

オプション

日付 ：日付値には日付フォーマットを使用し、さまざまな表示オプションを指定します。

  • type: date
  • date_format：日付の表示方法を制御します。
    • locale_short_month略称の月で日付を表示します
    • locale_long_month：月のフルネームで日付を表示します。
    • year_month_day日付の形式をYYYY-MM-DDに設定します。
    • locale_number_month月を数値として日付を表示します。
    • year_week日付を年と週番号の形式でフォーマットします。例えば、 2025-W1
  • leading_zeros1桁の数値の前にゼロが付くかどうかを制御します
  • true
  • false

DateTime ：日付と時刻を組み合わせたTimestamp値には、datetime形式を使用してください。

  • type: date_time

  • date_format：日付の表示方法を制御します。

    • no_date: 日付は非表示です
    • locale_short_month略称の月で日付を表示します
    • locale_long_month：月のフルネームで日付を表示します。
    • year_month_day日付の形式をYYYY-MM-DDに設定します。
    • locale_number_month月を数値として日付を表示します。
    • year_week日付を年と週番号の形式でフォーマットします。例えば、 2025-W1

  • time_format:

    • no_time時間：非表示
    • locale_hour_minute: 時と分を表示します。
    • locale_hour_minute_second時、分、秒を表示します。
  • leading_zeros1桁の数値の前にゼロが付くかどうかを制御します
    • true
    • false
注記

date_timeタイプを操作する場合、date_formatまたはtime_formatの少なくとも1つは、no_dateまたはno_time以外の値を指定する必要があります。

日時書式設定の例​

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

ダウンストリームツールの統合​

セマンティックメタデータは、メトリクスビューを利用するダウンストリームツールに自動的に入力されます。

  • AI/BI ダッシュボード ：ダッシュボードの表示名と書式設定の仕様は、ダッシュボードのデータセットと視覚化に自動的に入力され、ダッシュボードの判読性が向上します。
  • **Genieエージェント**：Genieがメトリクスビューから利用可能なフィールドとメジャーをより適切に検出して理解できるよう、シノニムが自動的にインポートされます。

完全な例​

次の例は、売上実績を追跡し、すべてのエージェントメタデータ型を含むメトリクスビュー定義を示しています。メトリクスビューは注文データを分析し、収益メトリクスを計算し、注文額で顧客をセグメント化し、注文量を追跡します。

顧客セグメントは次のように定義されます：

  • エンタープライズ：100,000ドルを超える注文
  • ミッドマーケット：注文額が $ 10,000 から $ 100,000 の範囲
  • 中小企業：10,000 ドル未満の注文

メタデータは、「顧客セグメント別の総売上を表示」や「注文あたりの平均収益は何か」といった自然言語クエリーをサポートしています。

YAML
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
このページの見出し