创建和管理语义模型

使用 Semantic Web UI 创建工作区，并添加、校验、发布语义模型 YAML 文件。普通仓库用户可以查看已发布的模型。修改模型或工作区需要仓库 admin 用户。

字段定义和 YAML 参考，请看语义模型概念。

开始之前

请确认你已具备：

• SelectDB Cloud 仓库的 MCP Connection URL。
• 仓库 admin 用户名和密码。
• 语义模型将要引用的物理表和列。
• 如果要用环比或同比指标，需要一张日历表。

创建并发布你的第一个模型

1. 打开工作区

1. 在 MCP Connection URL 后面追加 /web。例如， https://<warehouse-id>.<region>.<provider>.selectdb.cloud/mcp/web。
2. 使用仓库 admin 用户名和密码登录 Semantic Web UI。
3. 在顶栏的选择器中选择一个工作区。要创建工作区，点击 + New Workspace 并输入名称。

所选工作区的模型管理页面为 /mcp/web/models?workspace=<workspace-name>。页面左侧显示 Active Files，右侧显示 Staging。

注意：

workspace 名称必须以字母开头，只能包含字母、数字和下划线。例如 marketing 或 finance_v2。

2. 添加语义模型文件

在 Staging 面板标题栏点击 + New。输入 orders.yaml，粘贴以下定义，然后点击 Create：

---
semantic_model:
  name: orders
  db_table: dw.orders
  defaults:
    agg_time_dimension: order_date

  entities:
    - name: order_id
      type: primary
      expr: order_id

  dimensions:
    - name: order_date
      type: time
      type_params:
        time_granularity: day
    - name: channel
      type: categorical

  measures:
    - name: total_amount
      agg: sum
      expr: amount
    - name: order_count
      agg: count
      expr: order_id

你也可以点击 Staging 面板标题栏的 Upload 上传一个或多个 .yml 或 .yaml 文件。创建、上传、编辑或删除文件都会把待处理变更加入 Staging。这不会改变查询所使用的 Active 模型。

3. 添加时间配置

再次点击 Staging 面板标题栏的 + New。输入 project.yaml，添加日历配置，然后点击 Create：

---
time_config:
  calendar:
    - table: dw.dim_date
      column: date_id
      grain: day

日历表用于环比和同比指标。

4. 校验待处理的变更

回到模型管理页面。在右侧 Staging 面板标题栏点击 Validate。Validate、Commit 和 Discard 按钮只在工作区有待处理变更时显示。

校验检查内容：

• YAML 语法和命名规则。
• 引用的表和列是否存在。
• MetricFlow 语义规则。
• 跨模型的重复名称和依赖关系。

校验结果显示在 Staging 面板下方。如果校验失败，从模型管理页面打开对应的文件，修正后点击 Save，然后再次点击 Validate。

5. 提交已校验的变更

校验通过后，点击 Staging 面板标题栏中 Validate 旁边的 Commit。Commit 会把所有已校验的 Staging 变更提升为 Active，并自动触发引擎重载。你不需要重启 MCP 服务。

重载完成后：

1. 确认文件出现在 Active Files 下。
2. 让 AI Agent 运行 check_service_health，确认 workspace 状态为 healthy。
3. 让 AI Agent 运行 list_metrics 查看该 workspace，确认发布的指标。

警告：

如果当前 Staging 变更未通过校验，Commit 会被拒绝，并返回 Staging must be validated before commit。

理解 workspace 与模型存储

Workspace

workspace 是语义模型的隔离容器。每个 workspace 拥有独立的：

• 模型文件。
• 指标列表。list_metrics 只返回所选 workspace 的指标。
• MetricFlow 查询引擎实例。
• SelectDB Cloud 仓库连接池。

一个 workspace 中的指标在其他 workspace 中不可见。你可以用 workspace 隔离团队、项目或环境。

Workspace 状态

调用 check_service_health 查看每个 workspace 的运行状态：

状态	含义	产生原因
healthy	语义模型加载成功，指标可查询。	YAML 文件已提交、解析成功，MetricFlow 就绪。
no_models	workspace 没有任何已发布的模型文件。	workspace 是新创建的，或所有文件都被删除。
not_ready	存在模型文件，但无法编译为语义 manifest。	模型存在 YAML、表、列、项目配置或 MetricFlow 校验错误。

每次重载后，服务会记录版本号、指标数量和加载状态。用 check_service_health 返回的 metric_count 确认加载了多少指标。

Active 和 Staging 存储

每个 workspace 有两层存储：

存储层	表	用途
Active Store	active_store_{workspace}	包含查询引擎使用的已提交模型。Active 文件是只读的。
Staging Store	staging_store_{workspace}	包含待处理的增删改。校验通过的变更在 Commit 后进入 Active。

完整的更新流程：

步骤	位置	操作	结果
1	Staging 面板标题栏或文件编辑器	点击 + New、Upload、Save 或 Delete	变更加入 Staging，不影响正在执行的查询
2	Staging 面板标题栏	点击 Validate	服务校验所有待处理变更
3	Staging 面板标题栏	校验通过后点击 Commit	校验通过的文件从 Staging 进入 Active
4	自动	等待引擎重载	服务编译 manifest 并更新工具路由

Semantic Web UI 参考

页面	URL	功能
登录	/mcp/web/login	用仓库用户名和密码登录。默认管理员用户名是 admin。
Semantic Web UI 首页	/mcp/web	选择、创建或删除工作区。
模型管理	/mcp/web/models?workspace=<workspace-name>	查看 Active 和 Staging 文件。添加待处理变更、校验并提交。
文件编辑器	/mcp/web/<filename>?workspace=<workspace-name>	编辑 YAML 文件并把变更保存到 Staging。

仓库 admin 用户可以使用以下模型管理操作：

按钮	位置	作用
+ New	Staging 面板标题栏	创建 YAML 文件。
Upload	Staging 面板标题栏	上传一个或多个 YAML 文件。
Validate	Staging 面板标题栏（存在待处理变更时）	校验所有 Staging 变更。
Commit	Staging 面板标题栏（存在待处理变更时）	发布已校验的 Staging 变更并触发引擎重载。
Discard	Staging 面板标题栏（存在待处理变更时）	丢弃所有待处理变更，保留当前 Active 版本。
Reload	顶栏	手动触发引擎重载。通常 Commit 后会自动重载。

权限模型

操作	仓库 admin 用户	普通仓库用户
查看语义模型	✅	✅
用 query_metric 查询指标	✅	✅
用 list_metrics 列出指标	✅	✅
上传、编辑或删除 YAML	✅	❌
校验、提交或丢弃变更	✅	❌
创建或删除工作区	✅	❌
用 execute_query 运行只读 SQL	✅	✅

部署示例 workspace

示例 workspace 是可选的，不会自动创建。在 Semantic Web UI 首页，仓库 admin 用户可以点击 Deploy example 创建示例数据和语义模型：

内容	说明
dw.orders	订单表，12 行示例数据。
dw.users	用户表，5 行示例数据。
dw.products	产品表，5 行示例数据。
dw.dim_date	用于时间线对齐和累计计算的日历表。
语义模型 YAML	example workspace 中的 orders.yaml、users.yaml、products.yaml 和 project.yaml。

示例指标包括 total_amount、order_count、avg_amount、unique_users 和 user_count。

部署在后台运行。完成后，example workspace 对 list_metrics 和 query_metric 可用。如果示例未部署，普通仓库用户仍然可以使用元数据发现和只读 SQL 查询。

校验失败排查

错误信息	原因	解决方法
Table xxx does not exist	db_table 引用的表不存在。	确认数据库和表名。
measure references missing column: dw.orders.xxx	度量引用了不存在的列。	确保 expr 与列名和大小写一致。
entity references missing column	实体引用了不存在的列。	检查 expr 中的列或 SQL 表达式。
Duplicate measure 'xxx' defined in 2 models	两个模型定义了同名度量。	重命名其中一个度量，使其全局唯一。
Duplicate semantic_model name	两个文件使用了相同的模型名称。	重命名其中一个语义模型。
Did not find exactly one project configuration	project.yaml 缺失或重复。	只保留一个包含 time_config 的 project.yaml。
'xxx' does not match '^(?!.*__)...$'	名称违反命名规则。	以小写字母开头，去掉双下划线，至少两个字符。
No staging changes to validate	workspace 没有待处理变更。	先创建、上传、编辑或删除一个 YAML 文件，再点击 Validate。

如果校验仍然失败：

1. 运行 DESCRIBE dw.orders 确认物理表存在。
2. 确认列名和大小写与 YAML 定义一致。
3. 检查 YAML 缩进。使用空格而不是制表符。
4. 确认所有模型、实体、维度、度量名称都符合命名规则。

下一步

• 语义模型概念：了解模型字段和高级指标定义。
• 快速开始：了解如何接入 AI 客户端并查询已发布的指标。