概述
本文介绍如何在 DataBuddy 中通过 YAML 编辑器创建一个语义模型。语义模型是业务分析的最小数据单元，对应一张或多张物理表的语义封装，是后续定义指标的基础。完成创建后，您可以发布模型，并在其上 定义指标与维度、授权给业务方消费。
前提条件
在开始本操作前，请确保满足以下条件：
已开通 DataBuddy 服务，并在目标工作空间中拥有本体建模的 Read Write 或 Read Write & Delete 功能权限。无功能权限时，模型管理 Tab 不可见或仅可查看；缺权限时请联系工作空间管理员申请。
拥有要引用的物理表的 Catalog Table.Select 权限。模型 YAML 中引用的每张表都需要您当前账号具备 Select 权限，否则发布时校验不通过。
使用限制
限制项 | 说明 |
创建权限 | 仅具备本体建模的 Read Write 及以上功能权限的用户可创建 |
编辑形态 | 当前仅支持 YAML 编辑器，或使用自然语言借助 Buddy 辅助创建 |
负责人 | 模型创建者默认为 负责人，每个模型只能有一个 负责人，可转交 |
操作步骤
步骤 1：进入本体建模 → 模型管理
在工作空间左侧导航中单击本体建模 ，进入关系模型 子菜单。该页面集中展示当前工作空间内所有您可见的模型。
每个模型卡片展示模型名称、负责人、所含表数与指标数、模型描述、英文标识符以及状态标签（已发布、已下线）。
步骤 2：发起新建
在页面右上角单击 + 新建模型（YAML） 。系统弹出 YAML 编辑面板，左侧为表选择器，右侧为代码编辑器。
说明：
如果您不确定 YAML 写法，可以单击右上角查看示例 调出官方示例片段，或借助 Hi Buddy 入口让 AI 助手协助生成模型 YAML。
步骤 3：选择引用的物理表
在左侧表选择器中选择数据来源，并可快捷选择插入要在 YAML 中引用的资源：
1. 数据目录：可选择来自 TC Catalog（原生）的数据目录、或来自直连数据源，比如 Doris、StarRocks 的 Catalog、Schema 表等。
2. 逻辑视图：可选择创建的逻辑视图以及逻辑视图内的字段
3. 关系模型：可选择关系模型、关系模型内引用的表、字段、以及关系模型内创建的指标、以及指标支持的分析维度等。
步骤 4：编写模型 YAML
在右侧编辑器中按以下结构编写 YAML：
# 版本：1.0============================================================# 【必填】配置文件版本号，固定为 1.0version: 1.0# ============================================================# 语义模型定义# type: DEF - 新建模型（需提供完整定义）# REF - 引用已有模型（只需 name + type）# ============================================================model:# 【必填】模型英文名，1-50字符，支持字母、数字、下划线、括号name: ecommerce_order_model# 【可选】模型别名列表，支持多个，不允许含逗号# 为空时默认使用 name；存入数据库时以逗号分隔存储label:- 电商订单模型- order_model_alias# 【可选】模型描述description: "电商业务订单主模型，关联用户表和商品表"# 【必填】模型类型：DEF(定义新模型) | REF(引用已有模型)type: DEF# 【DEF必填】主表数据源路径，格式：catalogName.databaseName.tableNamesource: default_catalog.ecommerce_db.orders# 【可选】关联表配置，支持嵌套 JOINjoins:- name: user_table # 关联表别名（必填）source: default_catalog.ecommerce_db.users # 关联表路径（必填）on: # 关联条件（必填，至少一个）- source.user_id = user_table.id# 嵌套关联（可选）joins:- name: user_addresssource: default_catalog.ecommerce_db.addresseson:- user_table.id = user_address.user_id- name: product_tablesource: default_catalog.ecommerce_db.productson:- source.product_id = product_table.id
YAML 关键字段说明：
字段 | 是否必填 | 说明 |
version | 是 | YAML schema 版本，当前固定为 1.0 |
model.name | 是 | 模型英文标识，仅支持小写字母 / 数字 / 下划线，工作空间内唯一 |
model.label | 是 | 模型别名，用于列表卡片与详情页展示 |
description | 否 | 模型描述，建议简述业务域与覆盖范围 |
model.type | 是 | 取值： DEF（新建模型，需提供完整定义）/ REF（引用已有模型，仅需 name + type） |
model.source | 是 | 模型主表的三段路径 catalog.schema.table |
model.joins | 多表必填 | 表与表的 Join 关系；当前仅在多表模型时必须声明 |
注意：
模型 YAML 中引用的每一张表都必须在当前账号下具备 Table.Select 权限。发布时系统会逐表校验，缺权限的表会在 YAML 编辑器中以警告提示，并阻断发布流程。
步骤 5：发布模型
模型 YAML 编辑完成后，单击左下角发布 ：
1. 系统先做语法校验，校验项包括：YAML 格式、字段必填、表 Select 权限、维度字段是否存在、Join 字段是否存在等。
2. 校验通过后弹出确认弹窗。
3. 单击确认后模型进入「已发布」状态，模型卡片显示绿色
已发布 标签。发布后，您可以：
在该模型上 定义指标与维度。
在模型详情页的「授权」Tab 给其他用户授予 Manage / CreateMetric 权限。
通过 Buddy 让 AI 协助创建指标。
步骤 6：转交 Owner（可选）
每个模型只能有一个 Owner，默认为创建者。如需转交：
1. 进入模型详情页 → 右侧抽屉「基本信息 > 负责人」→ 鼠标 hover 后，出现修改的小笔 ICON，单击后即可转交 Owner 。
2. 选择目标用户后提交，系统弹出二次确认。
3. 转交后原 Owner 失去删除模型与转交模型的权限；如仍需操作，可由新 Owner 授予 Manage 权限。
通过 Buddy 创建模型
支持在 Buddy 中用自然语言描述需求，由 AI 协助生成模型 YAML 并完成发布。常见对话示例：
帮我用 dlc.default_catalog.olist.orders 和 users 表建一个 Olist 电商销售模型，关联键是 user_idAgent 在执行写操作（创建、修改、发布、下线、删除）前会先校验权限：
若您没有「模型管理」的功能权限，Buddy 会拦截操作并提示：「您当前暂无创建语义模型的权限，可联系工作空间管理员 XXX 申请开通『语义模型 → 模型管理的读写删权限』后再操作；也可以直接提交需求，由语义层管理员 XXX 为您协助创建。」
若您有创建权限但缺少所需表的 Select 权限，Buddy 会列出缺权限的表名与对应表 负责人，引导您线下申请。
模型详情页
模型发布后，在「模型管理」列表页单击任一模型卡片即可进入模型详情页 。详情页是模型上线后进行结构查看、指标与维度管理、权限配置的主入口。
页面整体结构
详情页整体分为三个区域：
顶部栏 ：展示模型名，与状态标签（
已发布 / 已下线）；右侧按当前 Tab 上下文展示操作按钮，常驻有「编辑」和「下线」，进入「权限」Tab 时还会出现「授权」按钮。主内容区 ：以 Tab 形式提供四个视图，依次为「实体关系」（默认）、「关联指标」、「关联维度」、「权限」。
右侧信息栏 （「实体关系」Tab 下展示）：包含三组信息
基本信息 ：别名、描述、负责人、状态。
技术信息 ：创建时间、创建人、最近更新时间、变更人。
模型信息 ：关联表数、指标数、维度数。
实体关系 Tab
默认进入的 Tab，以画布 形式可视化展示模型内物理表之间的关联关系：
每张表对应一个表卡片，顶部展示表名（含
catalog.schema.table 三段路径），下方按字段顺序列出字段名、数据类型与中文说明；表与表之间的连线对应 YAML 中声明的
joins 关联关系；画布右上角提供放大、缩小、宽屏、全屏等视图控制，便于在多表、字段多的场景下浏览。
关联指标 Tab
以表格 形式列出该模型上已定义的全部指标：
列 | 说明 |
指标名 / 指标别名 | 指标的英文标识与中文标签 |
指标类型 | 原子指标 / 衍生指标 |
衍生类型 | 当指标类型为衍生指标时显示具体子类型（筛选型 / 累积计算型 / 同环比计算型 / 混合计算型 / 转化计算型） |
指标口径 | 指标的计算 SQL 摘要 |
来源表 | 指标所引用的物理表 |
负责人 | 指标 Owner |
最近修订时间 | 最近一次编辑或发布的时间 |
操作 | 单条「编辑」「下线」 |
表格上方提供批量授权按钮，勾选多个指标后可统一发起授权。
关联维度 Tab
以表格 形式列出该模型引用的全部维度：
列 | 说明 |
维度名 / 维度别名 | 维度的英文标识与中文标签 |
描述 | 维度的业务说明 |
维度类型 | 普通维度 / 时间维度 / 字典维度等 |
维度值信息 | 维度的取值特征，例如时间维度会显示「最小颗粒：日」 |
负责人 | 维度 Owner |
关联字段 | 维度在底层表上对应的物理字段路径 |
最近修订时间 | 维度的最近一次修订时间 |
权限 Tab
以表格 形式展示模型及其指标的授权情况：
列 | 说明 |
授权对象 | 被授权的用户 / 用户组 |
类型 | 用户 / 用户组 |
权限点 | Manage / Create Metric / Query 等具体权限点 |
表权限 | 授权对象是否对模型引用的所有物理表都具备 Table.Select 权限（齐全 / 缺失） |
维度 | 授权对象可查询的维度范围 |
维度值范围 | 授权对象可查询的维度值范围（行权限） |
过滤关系 | 多个维度值之前的关系 |
授予人 | 发起此次授权的用户 |
授权时间 | 授权生效时间 |
操作 | 「编辑」「回收」 |
表格上方支持按关键字搜索用户、用户组，并可按权限范围筛选；右上角单击授权，可发起新的授权任务，弹出模型授权弹窗（详见 模型授权）；表格内单条编辑按钮可对已有授权进行权限点变更，回收按钮可撤销已授予的权限。
模型授权
单击「权限」Tab 右上角的「授权 」按钮后，会弹出「模型授权 | <模型名> 」弹窗，用于把模型的某项或多项权限授予指定用户、用户组。
弹窗自上而下包含三块内容：
1. 授权主体（必填）
可选择：用户、用户组、标签2. 授权对象（必填）
如果授权主体选用户：此处展示选用户面板，支持搜索用户；至少添加 1 个
如果授权主体选用户组：此处展示选用户组面板，支持搜索用户组；至少添加 1 个
如果授权主体选标签：无需选择授权对象，仅需选下面的授权点即可
3. 授权点（必填，至少勾选 1 项）
字段标签：
授权点 *，下方为可勾选的权限点卡片，每个权限点包含「能力说明」与「适用范围」两行说明：权限点 | 能力说明 | 适用范围 |
Create Metric | 可基于该模型创建新指标 | 允许在该模型上定义原子指标 / 衍生指标，但不能修改模型本身 |
Manage | 可管理模型 | 允许编辑 / 发布 / 下线模型；删除模型仅 Owner 可操作 。并要求被授权用户对模型内所有底层表均拥有 Select 和 Browse 权限 ，否则授权成功后该用户实际操作底层表相关动作时会被拦截 |
Query All Metrics | 可查全部指标 | 快速给用户授予该模型下所有指标的查询权限。 |
三个权限点可同时勾选，也可只勾选其中之一。
校验规则 ：若未勾选任何权限点就单击确认授权，字段下方会红字提示请选择权限点 ，且不会发起授权请求。
4. 授权原因（选填）
字段标签：
授权原因。控件：多行文本输入框，占位提示为
请简要说明本次授权的业务背景…。用于审计与事后追溯，建议填写本次授权的业务目的或来源工单号；不填也可以提交。
5. 提交与生效
弹窗底部右侧提供两个按钮：取消 （关闭弹窗，丢弃已填内容）与确认授权 （提交授权任务）。
单击「确认授权」后：
1.1 系统对表单进行必填校验（授权对象、授权点），校验失败时在对应字段下方给出错误提示。
1.2 校验通过后写入授权记录，授权对象立即获得对应权限点；新授权会作为一条新行出现在「权限」Tab 表格中。
1.3 若被授权用户对模型底层表存在
Select / Browse 权限缺失，权限 Tab 中对应行的「表权限」列会显示「缺失」，但本次授权仍会生效。常见问题
Q1：模型创建后能修改引用的表吗？
可以。在模型详情页单击编辑 重新进入 YAML 编辑器，修改后重新发布即可让新结构生效。
Q2：模型发布后还能下线吗？
可以。在模型详情页单击下线 后模型状态回到「已下线」，下游对该模型的指标查询会立即失败。下线模型可重新发布。
Q3：删除模型会影响其上的指标吗？
会。删除模型前必须先删除该模型上所有指标，否则系统拦截删除操作。删除后模型不可恢复。
Q4：模型 Owner 与模型管理员（Manage）有什么区别？
Owner 拥有全部权限，包括转交 Owner 与删除模型；Manage 拥有除转交与删除外的全部权限。一个模型只能有一个 Owner，但可以同时存在多个 Manage 用户。
相关文档
