概述
语义模型（Semantic Model）是 DataBuddy 在物理表与业务消费之间引入的语义层（Semantic Layer） 。它把分散在数据湖各张表中的字段，按业务视角抽象为三类语义对象——关系模型（Model）、指标（Metric）和维度（Dimension） ，为 Buddy（AI Agent）、报表与下游应用提供一份口径统一、权限可控的语义入口。
为什么需要语义层
在没有语义层的传统数仓中，常见的痛点是：
同一指标的口径不一致 ：不同部门的"GMV"可能各自指
SUM(order_amount)、SUM(pay_amount) 或 SUM(pay_amount) WHERE order_status='paid'，对账时反复扯皮。业务分析师严重依赖数据团队 ：每问一次「上海地区上周的客单价」都要重新写 SQL、申请底表权限。
底表权限与业务消费深度耦合 ：业务方为了用一个指标，不得不申请其依赖的所有底表 Select 权限，权限授予与回收都很重。
AI 取数难以自动化 ：自然语言问数若直接走 NL2SQL 路径，不仅幻觉率高，而且每次都要解决建表、关联、字段语义等问题。
语义层把这些问题集中在一处治理：
一次定义、随处消费——指标、维度成为一等公民，Buddy、报表等共用同一份口径。
权限独立、最小授权——业务消费指标完全不依赖底表权限。
行级安全可控——通过维度值范围授权实现「张三只看华东」。
设计原则
原则 | 说明 |
Owner + 权限点 | 每类语义资产（模型、指标）只有一个 Owner（可转交）；模型上 授予 Manage / CreateMetric 权限点，指标上 授予 Manage / Query 权限点 |
语义层独立于 Catalog | 创建模型时需要底层表 Select 权限；创建指标、查询指标数据完全不依赖 Catalog 权限 |
最小权限 | 创建指标无需看底层数据，只需引用模型；查询指标无需管理模型权限 |
关系模型 Model
关系模型是业务分析的最小数据单元，对应一张或多张物理表的语义封装。模型负责声明：
引用了哪些 Catalog 表（含 Catalog / Schema / Table 三段路径）；
表与表之间的关联（Join）关系；
一个模型可以被多个指标引用，模型一旦发布，其结构变更需要重新走发布流程。
指标 Metric
指标是业务上可被消费的「数字口径」，在模型之上定义。指标分为原子指标 与衍生指标 两大类：
原子指标（SIMPLE） ：指标体系的最小统计单元，对单一字段做聚合计算，如
SUM(OrderAmount) 表示「交易总金额」。原子指标不涉及衍生逻辑。衍生指标 ：在原子指标基础上按业务规则加工得到的指标，又细分为 5 种：
筛选型 ：在原子指标基础上按特定维度（如时间、地域、用户属性）筛选后得到，例如「线上渠道交易总金额」=
SUM(OrderAmount) 限定 渠道 = 线上。累积计算型 ：对原子、筛选型指标按时间窗口累加、汇总得到，例如「近 30 天线上渠道交易总金额」。
同环比计算型 ：以累积计算型指标为基础，与历史同期（同比）或上一周期（环比）数据对比的相对指标，例如「近 30 天线上渠道交易总金额环比增长率」。
混合计算型 ：结合两个及以上指标通过衍生计算规则（如加减乘除等）得到的复合指标，例如「平均交易流水金额」=
交易总金额 / 交易数量。转化计算型 ：基于不同环节的原子、筛选型指标，计算流程中「从 A 到 B」的转化效率，例如「注册-下单转化率」=
下单量 / 注册量。指标支持的聚合方式包括
SUM、COUNT、COUNT(DISTINCT)、MAX、MIN、AVG，以及自定义表达式。维度 Dimension
维度用于定义分析视角。按字段的业务语义，常见维度可分为以下几类：
时间维度 ：用于按时间窗口对指标进行切片的日期、时间类字段，支持按天、周、月、季、年等不同粒度聚合，是趋势分析（如同环比、近 N 天）的核心切片依据。
示例：
order_date（订单创建日期）、pay_time（支付完成时间），常按天、周、月切片。字典维度 ：值域固定、可枚举的维度字段，对应业务上的「类目」「品牌」等分类体系。其取值通常来自字典表或预设枚举，字段值域有限且稳定，便于做归一化与标准化管理。
示例：
category_name（商品类目）、brand（品牌）、gender（性别）。普通维度 ：用于描述业务实体属性的通用维度字段，没有特殊的时间或字典语义，常见为用户姓名、年龄、用户 ID 等属性
示例：
user_name（用户名）、age（年龄）、user_id（用户 ID）。维度是跨模型复用的全局维度（可在「维度管理」中统一定义）。
权限模型概览
语义层权限分为三大类：功能权限 、ACL 权限 、数据权限 ，均挂在工作空间 → 角色管理 → 语义建模菜单下：
权限类别 | 控制目标 | 配置位置 |
功能权限 | 用户能否进入「模型管理 / 指标管理 / 维度管理」 Tab，以及能否新建 / 修改 / 删除 | 工作空间 → 角色管理 → 语义建模菜单 |
ACL 权限（资产级） | 用户对单个模型的具体能力（Manage / CreateMetric）；对单个指标的具体能力（Manage / Query） | 模型详情页 → 权限 Tab 指标详情页 → 权限 Tab |
数据权限（行级） | 同一指标下，用户能查询到的维度值范围 | 指标授权时附带的「维度值范围」 |
模型 ACL 权限矩阵
操作 | Owner 身份 | Manage 权限点 | CreateMetric 权限点 |
查看模型结构 | ✅ | ✅ | ✅ |
编辑模型结构 | ✅ | ✅ | ❌ |
引用该模型创建指标 | ✅ | ✅ | ✅ |
发布 / 下线模型 | ✅ | ✅ | ❌ |
授权他人 | ✅ | ✅ | ❌ |
转交模型 Owner | ✅ | ❌ | ❌ |
删除模型 | ✅ | ❌ | ❌ |
指标 ACL 权限矩阵
操作 | Owner 身份 | Manage 权限点 | Query 权限点 |
查看指标元数据 | ✅ | ✅ | ✅ |
查询指标数据 | ✅ | ✅ | ✅（可被维度值限制） |
编辑指标口径 | ✅ | ✅ | ❌ |
发布 / 下线指标 | ✅ | ✅ | ❌ |
授权他人 | ✅ | ✅ | ❌ |
转交指标 Owner | ✅ | ❌ | ❌ |
删除指标 | ✅ | ❌ | ❌ |
Catalog 与语义层的协同
语义层的设计原则是「创建需 Catalog 权限，消费不需要 」：
场景 | 所需 Catalog 权限 | 所需语义层权限 |
创建模型 | Table.Select | 语义建模功能权限 |
管理模型（被授 Manage） | Table.Select + Table.Browse | 模型的 Manage 权限点 |
创建指标（被授 CreateMetric） | 不需要 | 模型的 CreateMetric 权限点 |
查询指标数据 | 不需要 | 指标的 Query 权限点 |
NL2SQL 直接查表 | Table.Select + Table.Browse | 不需要 |
提示
关于 Table.Browse ：
Browse 是 Catalog 层对底层表的「可预览」权限，独立于 Select 的全量读权限。模型 Manage 用户在编辑、发布、下线等需要触达底层表结构的环节，除了 Select 还必须拥有 Browse 权限，否则会被拦截。因此即使用户在 Catalog 中底表的 Select 权限被回收，只要用户有已发布指标的查询仍可正常执行，保障业务连续性。
相关文档
创建语义模型
语义模型应用
