Metrix ビューのエージェントメタデータ

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

注記

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

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

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

注記

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

このページの例では、TPC-H サンプルデータセット ( samples.tpch.orders ) を使用します。これは、 Unity Catalogデータセットで確実に入手できます。 TPC-H データセットは、注文、顧客、サプライヤー、部品のテーブルを含む卸売サプライチェーンをモデル化します。 ordersテーブルの列名にはo_接頭辞が使用されます (たとえば、 o_orderdateは注文日、 o_totalpriceは合計金額)。TPC-H スキーマとデータモデルの詳細については、「チュートリアル: 結合を使用して完全なメトリクスビューを構築する」を参照してください。

表示名

表示名は、技術的な列名の代わりに、視覚化ツールに表示される人間が読みやすいラベルです。表示名は255文字までです。

次の例は、 order_dateディメンション (注文が行われた日時を追跡する) と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'

同義語

同義語は、 GenieなどのLLMツールが、代替名を提供することで、ユーザー入力から次元や測定値を発見するのに役立ちます。同義語は、ブロック形式またはフロー形式のYAMLを使用して定義できます。各次元または指標には、最大10個の同義語を設定できます。各同義語は255文字までです。

次の例は、 order_date次元 (注文が行われた時点) とtotal_revenueメジャー (すべての注文価格の合計) で定義された同義語を示しています。同義語を使うことで、ユーザーは「注文時間別の売上を表示してください」や「注文日別の総売上高はいくらですか」といった自然言語で質問できるようになります。

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

フォーマット仕様

フォーマット仕様は、可視化ツールにおいて値をどのように表示するかを定義するものです。以下の表には、サポートされているフォーマットの種類と例が記載されています。

数値形式

フォーマットタイプ	必須オプション	オプション
数値：一般的な数値には、小数点以下の桁数制御と略語オプションを備えた、通常の数値形式を使用します。	`type: number`	`decimal_places`小数点以下の桁数を制御します。 `type`（ `decimal_places`が指定されている場合は必須） `max` `exact` `all` `places`: 0～10の整数値（型が`max`または`exact`場合は必須） `hide_group_separator`: true に設定すると、 `,`などの該当する数値グループ化区切り文字を削除します。 `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_separator`: trueに設定すると、該当する数値の区切り文字をすべて削除します。 `true` `false` `abbreviation`: `none` `compact` `scientific`
パーセンテージ：比率の値をパーセンテージで表す場合は、パーセンテージ形式を使用してください。	`type: percentage`	`decimal_places`小数点以下の桁数を制御します。 `type`（ `decimal_places`が指定されている場合は必須） `max` `exact` `all` `hide_group_separator`: trueに設定すると、該当する数値の区切り文字をすべて削除します。 `true` `false`
バイト：適切なバイト単位（KB、MB、GBなど）で表示されるデータサイズ値には、バイト形式を使用します。	`type: byte`	`decimal_places`小数点以下の桁数を制御します。 `type`（ `decimal_places`が指定されている場合は必須） `max` `exact` `all` `places`: 0～10の整数値（型が`max`または`exact`場合は必須） `hide_group_separator`: trueに設定すると、該当する数値の区切り文字をすべて削除します。 `true` `false`

数値書式設定の例

Number
Currency
Percentage
Byte

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

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

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

YAML
format:
  type: byte
  decimal_places:
    type: max
    places: 2
  hide_group_separator: 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_zeros`1桁の数字の前にゼロを付けるかどうかを制御します。 `true` `false`
DateTime ：日付と時刻を組み合わせたタイムスタンプ値には、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_zeros`1桁の数字の前にゼロを付けるかどうかを制御します。 `true` `false`

注記

date_time型を扱う場合、 date_formatまたはtime_formatの少なくとも一方は、 no_dateまたはno_time以外の値を指定する必要があります。

日時フォーマットの例

Date
DateTime

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

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

下流ツールの統合

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

AI/BIダッシュボード ：ダッシュボードのデータセットと視覚化には、表示名とフォーマット仕様が自動的に入力され、ダッシュボードの読みやすさが向上します。
Genie spaces : Genieメトリクスビューから利用可能な寸法と測定値をよりよく検出および理解できるように、同義語が自動的にインポートされます。

完全な例

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

顧客セグメントは以下のように定義されます。

法人向け：10万ドル以上の注文
中規模市場：1万ドルから10万ドルの注文
中小企業：1万ドル未満のご注文

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

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

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

表示名​

同義語​

フォーマット仕様​

数値形式​

数値書式設定の例​

日付と時刻の形式​

日時フォーマットの例​

下流ツールの統合​

完全な例​