模型
概述
模型用于声明多个逻辑视图或可匹配数据对象在分析场景中的角色、根表、关联关系和可选计算字段。模型通过校验并发布后，可以按完整模型或智能推荐方式生成一个或多个逻辑视图。
本文以门店销售事实表 mysql8_test.tpcds.store_sales 和客户维度表 mysql8_test.tpcds.customer 为例，介绍从模型定义、逻辑视图映射、发布到创建模型视图的完整流程。
实际环境中的对象名称、行数、NDV 和推荐 SQL 以页面显示为准。
开始前准备
- 确认左侧导航中可以看到 数据整合 > 模型，并具备模型相关操作权限。
- 确认模型引用的 catalog、schema、表或视图真实存在，且当前用户可以访问。
- 确认关联字段存在并具有兼容的数据类型，同时明确关系基数，例如
MANY_TO_ONE。 - 准备创建模型视图时使用的视图路径，并确认该路径允许新建逻辑视图。
- 建议先从两张表和一条关系开始，校验成功后再逐步扩展。
模型定义 JSON 最大为 10 MB；模型名称最多 128 个字符，模型描述最多 300 个字符。
示例：门店销售与客户模型
本例将 store_sales 作为根表，并通过客户键关联 customer。一条销售记录最多对应一个客户，因此从销售事实表到客户维度表使用 MANY_TO_ONE。
| 模型角色 | 实际对象 | 关联字段 | 用途 |
|---|---|---|---|
store_sales |
mysql8_test.tpcds.store_sales |
ss_customer_sk |
销售事实、根表 |
customer |
mysql8_test.tpcds.customer |
c_customer_sk |
客户维度 |
使用以下模型定义：
{
"formatVersion": "1.0",
"modelName": "门店销售与客户模型",
"description": "关联门店销售事实与客户维度",
"defaultCatalog": "mysql8_test",
"rootTables": ["store_sales"],
"tables": [
{
"id": "store_sales",
"schema": ["tpcds"],
"name": "store_sales"
},
{
"id": "customer",
"schema": ["tpcds"],
"name": "customer"
}
],
"relationships": [
{
"id": "store_sales_to_customer",
"fromTable": "store_sales",
"toTable": "customer",
"joinType": "INNER",
"cardinality": "MANY_TO_ONE",
"keys": [
{
"fromColumn": "ss_customer_sk",
"toColumn": "c_customer_sk"
}
]
}
],
"calculatedFields": []
}
如果环境中不存在 mysql8_test.tpcds，请将 defaultCatalog、schema 和 name 替换为实际对象路径。模型中的每个 id 必须唯一。
使用步骤
步骤 1：进入模型列表
在左侧导航展开 数据整合，选择 模型。列表页显示模型名称、描述、状态、负责人、编辑人和更新时间，并支持按模型名称、负责人和状态筛选。
单击右上角 新建模型。
步骤 2：填写基本信息和模型定义
- 在 模型名称 中输入
门店销售与客户模型。 - 在 模型描述 中输入
关联门店销售事实表与客户维度表，用于客户销售分析。 - 将本文示例 JSON 粘贴到 模型定义 编辑器。
- 检查 JSON 语法是否完整，然后单击 下一步。
校验请求会直接使用编辑器中的 JSON，因此 JSON 内也应包含非空的
modelName。最终保存时，页面左侧填写的模型名称和描述会写入最终定义。
步骤 3：检查逻辑视图映射
校验完成后，页面按模型角色显示匹配视图、完整路径、表行数、NDV 和匹配状态。
- 确认
store_sales和customer均显示 匹配成功。 - 核对匹配对象的 catalog、schema 和名称是否正确。
- 核对表行数；统计值不可用或明显不准确时，可以手工修正为非负数。
- 核对 NDV。NDV 用于推荐和成本估算；显示
-表示当前没有取得统计值。
如果匹配失败，单击 上一步，修正 defaultCatalog、schema 或 name 后重新校验。
步骤 4：保存或发布模型
映射检查完成后，可以选择 保存 或 发布。
| 操作 | 结果 | 后续能力 | 适用场景 |
|---|---|---|---|
| 保存 | 形成未发布草稿 | 不能创建模型视图 | 仍需团队复核 |
| 发布 | 创建正式版本，首次通常为 V1 | 可以继续创建模型视图 | 定义和映射已确认 |
首次按本例操作时，建议确认两张表均匹配成功后直接发布。如果需要先让其他成员复核，可以先保存草稿，复核后再从列表或详情页发布。
步骤 5：查看模型详情和版本
单击列表中的模型名称进入详情页。
- 概览 页显示模型描述、模型定义、负责人、编辑人、最后编辑时间、状态和当前版本。
- 已发布模型显示正式版本，例如 V1；正式版本定义为只读，可以复制。
- 视图 页显示由当前模型创建的逻辑视图。
步骤 6：基于模型创建逻辑视图
在模型详情页切换到 视图，单击 创建视图。只有已发布模型可以执行此操作。
- 填写 视图路径，例如
demo.semantic_model。 - 选择生成方式：
- 全量生成：基于完整模型生成候选视图。
- 智能推荐：根据模型结构和分析场景推荐一个或多个候选视图。
- 逐个检查候选视图的名称、描述和推荐原因。候选名称必须有效且彼此唯一。
- 检查推荐 SQL。修改 SQL 后，单击 刷新解析 重新识别依赖视图；需要撤销修改时，单击 恢复推荐 SQL。
- 确认所有候选均为 已配置，然后单击右上角 创建。
切换 全量生成 和 智能推荐 会重新生成候选配置。如果当前候选已被修改，页面会提示切换后的修改不保留。
步骤 7：验证创建结果
- 返回模型详情的 视图 页，确认新视图出现在列表中。
- 打开目标视图，确认视图定义可以解析，依赖对象正确。
- 在工作簿或查询入口执行小范围查询，检查字段和关联结果是否符合预期。
- 记录本次模型版本、对象路径和验证结论，供后续维护使用。
完成标准如下：
- 模型状态为 已发布，当前版本可见。
- 模型详情的 视图 页出现目标逻辑视图。
- 小范围查询通过，字段和关联结果符合预期。
模型定义字段速查
| 字段 | 必填 | 说明 | 本例 |
|---|---|---|---|
formatVersion |
是 | 模型定义格式版本 | 1.0 |
modelName |
是 | JSON 内的模型名称，校验阶段不可为空 | 门店销售与客户模型 |
description |
否 | 模型说明 | 关联门店销售事实与客户维度 |
defaultCatalog |
是 | table 未单独指定 catalog 时使用 | mysql8_test |
rootTables |
是 | 至少一个根表角色，值必须来自 tables.id |
store_sales |
tables |
是 | 至少一项；id 唯一，schema 和 name 非空 |
store_sales、customer |
relationships |
否 | 表间关系；引用的角色必须存在 | store_sales_to_customer |
joinType |
关系中是 | 支持 INNER、LEFT、RIGHT |
INNER |
cardinality |
关系中是 | 支持 ONE_TO_ONE、ONE_TO_MANY、MANY_TO_ONE、MANY_TO_MANY |
MANY_TO_ONE |
keys |
关系中是 | 至少一组 fromColumn 和 toColumn |
ss_customer_sk → c_customer_sk |
calculatedFields |
否 | 计算字段列表，可以为空数组 | [] |
常见问题
“下一步”不可用
模型定义为空。先粘贴 JSON，并确认模型名称已经填写。
JSON 校验失败
检查 formatVersion、modelName、defaultCatalog、rootTables 和 tables，同时检查 JSON 中的逗号、引号和括号。
逻辑视图匹配失败
对象路径不存在或当前用户无访问权限。核对 catalog、schema 和 name，并确认引用的是当前环境中的真实对象。
无法创建模型视图
模型尚未发布。返回模型列表或详情页完成发布，再进入 视图 页。
“创建”按钮不可用
检查视图路径、候选名称和 SQL 是否为空。候选名称还必须合法且唯一，并且所有候选都需要处于 已配置 状态。
依赖视图解析失败
检查 SQL 语法和对象路径，然后单击 刷新解析。
统计信息缺失
可以在映射步骤手工补充表行数。NDV 缺失不会阻止阅读模型，但可能降低推荐或成本估算的置信度。
日常维护注意事项
- 列表支持按名称、负责人和发布状态筛选；未发布模型可从列表或详情发布，已发布模型显示正式版本。
- 删除模型会同步删除关联视图和投影。删除前必须确认下游依赖。
- 发布或源对象、字段发生变化后，应记录变更原因，并复核关系基数、连接字段、统计数据、候选 SQL 和模型映射。