在指标视图中使用语义元数据

2025-10-21

重要

此功能目前以公共预览版提供。

本页介绍如何在指标视图中使用语义元数据来增强数据可视化效果并提高大型语言模型（LLM）的准确性。

注释

需要 Databricks Runtime 17.2 或更高版本。指标视图 YAML 定义必须使用规范版本 1.1 或更高版本。有关详细信息，请参阅版本规范更改日志。

什么是语义元数据？

语义元数据包括提供其他上下文的显示名称、格式规范和同义词。此元数据可帮助可视化工具（如 AI/BI 仪表板）和自然语言工具（如 Genie 空格）更有效地解释和处理数据。语义元数据在指标视图的 YAML 定义中定义。

注释

使用规范版本 1.1 创建或更改指标视图时，保存定义时会删除 YAML 定义中使用 #表示的任何单行注释。有关升级现有 YAML 定义时的选项和建议，请参阅将 YAML 升级到 1.1 。

可以包括以下类型的元数据：

显示名称

显示名称提供可视化工具中显示的人工可读标签，而不是技术列名。显示名称限制为 255 个字符。

以下示例显示了在order_date维度和total_revenue度量上定义的显示名称。

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'

Synonyms

同义词通过提供替代名称帮助 LLM 工具（如 AI/BI Genie）通过用户输入发现维度和度量值。可以使用块样式或流样式 YAML 定义同义词。每个维度或度量值最多可以有 10 个同义词。每个同义词限制为 255 个字符。

以下示例显示了在 order_date 维度上定义的同义词：

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`

数字格式示例

编号

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

货币

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

百分比

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

日期和时间格式

下表说明如何使用日期和时间格式。

格式类型	必需选项	可选选项
日期：对具有各种显示选项的日期值使用日期格式。	`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`：控制单个数字是否要在前面加零以显示 `true` `false`
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`：控制是否以零开头的单个数字 `true` `false`

注释

使用类型 date_time 时，date_format 和 time_format 中至少有一个必须指定一个值，且该值不能为 no_date 或 no_time。

日期/时间格式示例

日期

format:
  type: date
  date_format: year_month_day
  leading_zeros: true

日期/时间

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

完整示例

以下示例显示了包含所有语义元数据类型的指标视图定义：

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