databricks-metric-views

Unity Catalog 指标视图

使用 YAML 定义可复用、受治理的业务指标，将度量定义与维度分组分离，以便灵活查询。

适用场景

在以下情况下使用此技能：

• 定义标准化业务指标（收入、订单数、转化率）
• 构建供仪表板、Genie 和 SQL 查询共享的 KPI 层
• 创建具有复杂聚合的指标（比率、去重计数、筛选度量）
• 定义窗口度量（移动平均值、累计总和、环比、年初至今）
• 在指标定义中使用联接对星型或雪花型模式进行建模
• 启用物化，预先计算指标聚合

首先：这能作为指标视图吗？（决策关卡）

编写前，请确认该度量能在查询时重新聚合。 可加的 SUM/COUNT、会按单元格重新计算的 COUNT(DISTINCT)、MEASURE() 比率（最后再相除），以及受支持的窗口度量（向前滚动 / 累积 / 环比 — 模式 8）都能正确重新聚合，可作为有效的指标视图度量；此列表并非穷举。以下关卡用于排除不适合的形态 — 如果符合以下任意一项，它就不是指标视图：应改为编写受治理的 Unity Catalog SQL 函数（使用 databricks-dbsql 构建），并将其作为可信的已注册 SQL 函数提供给 Genie（设计优先级表面 #11），而不是强行放入视图或预聚合辅助视图中：

• 在查询粒度上不可加 — 跨维度汇总会导致重复计数。实体计数是典型陷阱：一个实体出现在两个属性值下，仍是一个实体，而不是两个，因此不得跨任意多属性交叉汇总各单元格的去重计数。
• 先按实体计算，再聚合，且按实体计算的步骤不是求和 / 计数 / 和之比 — 例如，按实体计算两个期间的最小值 / 最大值，或按实体去重计数是否超过阈值。
• 依赖于筛选选择 — 结果会随用户筛选而重新分配（例如每个单元格都会变化的“所有其他项”分组）。
• 迭代计算 — 重复计算直至收敛（例如面板重新加权）。
• 返回一组表，而非单一度量（例如源×目标矩阵加上各行净值）。

一个度量可以大部分用指标视图实现，仅将其中一部分提取到函数中（渗透率 = 可加买家数 ÷ 基数，最后再相除 — 但短窗口修正，或任意多属性交叉 / 按实体阈值，应放入函数）。将复杂步骤预计算到基础 / 辅助视图中，仅适用于定义固定的情况 — 这是一项性能选择，针对所有切片统一确定。如果度量必须响应 Genie 中用户的运行时选择（任意交叉、参数或变化的分母），就必须即时计算，无法预计算 — 需要使用参数化的受治理 SQL 函数，而非预聚合视图。完整规则和两个示例（渗透率、品牌转换增益与损失）：metric-view-advisor.md §何时不应使用指标视图。在对 Genie 路由到复现外部方法的函数进行基准测试前，请验证其与参考结果达到 N 位小数的一致性 — 请参阅 databricks-genie-agents 技能。

前提条件

• Databricks Runtime 17.2+（适用于 YAML 1.1 版）；语义元数据（synonyms / display_name / format）需要 17.3+
• 具有 CAN USE 权限的 SQL 仓库
• 对源表具有 SELECT 权限，并在目标架构中具有 CREATE TABLE + USE SCHEMA 权限

指标视图生命周期

任务	参考资料	加载时机
创建	metric-view-advisor.md	任何创建任务——顾问负责完整工作流（分析架构、分析数据源、提出建议、部署）。同时加载 create-patterns.md，将其作为 YAML 规范和模式参考。
YAML 规范 / 模式	create-patterns.md	模式 1–12、完整 YAML 字段参考、格式注意事项、部署错误、快速参考。作为顾问的配套资料；也可直接加载以查找模式。
查询	query-patterns.md	针对指标视图编写 SQL——MEASURE() 基础知识、筛选条件、联接汇总、窗口度量、规则 1–3。
Genie 集成	metric-view-advisor.md §Genie Design Rules	单事实数据源规则、基础视图、领域组织、命名。Agent 元数据字段（comment、synonyms、display_name、format）参见 create-patterns.md §YAML Field Reference。

典型流程：顾问 → 创建 → 查询/验证 → Genie 集成（如果要添加到 Genie Agent）。

使用 Declarative Automation Bundles 进行源代码管理部署

若要对指标视图进行源代码管理，请提交其完整 SQL 定义，并通过由 bundle 管理的 SQL 作业执行。DAB 没有原生的指标视图资源，但由 bundle 管理的 SQL 作业可以应用已提交的定义：

# databricks.yml
bundle:
  name: orders_metrics

variables:
  catalog: { default: main }
  schema:  { default: default }
  warehouse_id: { default: "" }

resources:
  jobs:
    deploy_orders_metrics:
      name: deploy_orders_metrics
      parameters:
        - name: catalog
          default: ${var.catalog}
        - name: schema
          default: ${var.schema}
      tasks:
        - task_key: create_metric_view
          sql_task:
            warehouse_id: ${var.warehouse_id}
            file:
              path: ../src/orders_metrics.metric_view.sql

部署并运行：

databricks bundle deploy --target <TARGET> --profile <PROFILE>
databricks bundle run deploy_orders_metrics --target <TARGET> --profile <PROFILE>

请参阅官方的指标视图 bundle 示例。

相关技能

• databricks-genie-agents — 创建、管理和验证使用此处构建的指标视图的 Genie Agent。Genie 的指标视图设计规则参见顾问 §Genie Design Rules；查询规则参见 query-patterns.md。
• databricks-aibi-dashboards — 基于指标视图构建 AI/BI 仪表板。
• databricks-data-discovery — 在创建指标视图前探索数据；回答有关工作区的问题。
• databricks-dabs — 通过由 bundle 管理的作业对指标视图 SQL 定义进行源代码管理和部署。

资源

• 指标视图文档
• YAML 语法参考
• 联接
• 窗口度量
• 物化
• MEASURE() 函数