cube-build-model

构建和修改 Cube 语义模型

会写入状态。API 会拒绝在任何非开发模式分支上写入文件，因此下面的分支操作并非可有可无的流程——跳过后，所有写入都会失败。

选择路径

下文将 Cube MCP 工具写作 cube:<tool>：这是此插件捆绑的 cube 服务。 通过 Cube connector 使用时，这些工具会使用 connector 的名称。

如果 Cube MCP 工具可用（此插件的 cube 服务或 Cube connector），请使用它们。操作流程如下：

1. cube:startDataModelEdit — 返回开发分支的 branchName。将其传递给下方的每次调用，并重复使用；再次调用会启动新的编辑会话。
2. cube:listDataModelFiles、cube:readDataModelFile — 先读取，再写入。
3. cube:writeDataModelFile — 整个文件替换。此操作会重新编译并返回 valid 和任何 validationError；修复后再次写入，直到验证通过。
4. cube:getDataModelChanges — 检查差异。
5. 使用相同的 branchName 调用 cube:searchDataModel 和 cube:runQuery — 确认新成员已公开，且返回正确的数值。
6. cube:commitDataModelChanges — 在运行此操作之前，其他人都看不到这些更改。请说明它报告的分支，并提供 cube:switchUserBranch。
7. cube:mergeToDefaultBranch — 仅在用户明确要求发布时使用。此操作会让所有人都能使用这些更改。

对于新的预聚合，先使用 cube:getPreAggregationStatus 检查，再使用 cube:buildPreAggregation 构建该汇总，并传入开发分支的 branchName。构建过程会对数据仓库运行实际查询。

如果 MCP 工具未连接，或要使用 cube deploy 部署整个本地项目，请使用 CLI 路径。先读取再写入，以及约定，对两种路径都适用。

预检（CLI）

command -v cube >/dev/null || echo "Cube CLI not installed: curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "Not authenticated. Interactive: cube login. Headless: set CUBE_API_URL + CUBE_API_KEY."
cube context list   # confirm the tenant before writing anything

先读取，再写入

切勿基于臆测的模型进行编写。请先获取当前状态——通过 MCP 使用 cube:listDataModelFiles 和 cube:readDataModelFile，或使用 CLI：

cube data-model list <deployment> --content --json > /tmp/model.json

遵循项目现有的约定——文件布局、命名方式、度量是定义在立方体还是视图上，以及连接的声明方式。正确的立方体如果与相邻内容的风格大相径庭，也不是好的贡献。

开发模式工作流

# 1. See what branches exist, and which one is the deploy branch
cube data-model branches <deployment>

# 2. Create a feature branch to work on
cube data-model create-branch <deployment> <feature-branch>

# 3. Enter dev mode on the feature branch. This forks a personal `dev-…`
#    branch and PRINTS ITS NAME. Capture it — writes must target it.
cube data-model dev-mode <deployment> <feature-branch>

# 4. Write files to the dev branch
cube data-model put <deployment> model/cubes/orders.yml --file ./orders.yml --branch <dev-branch>
cube data-model put <deployment> model/views/revenue.yml --content - --branch <dev-branch>   # stdin

# 5. Validate the uncommitted working copy; fix and repeat until it passes
cube validate <deployment> --dev-mode

# 6. Commit — this lands on <feature-branch>, not production
cube data-model commit <deployment> -m "Add revenue view" --branch <dev-branch>

# 7. Wait for the build; exits non-zero if it fails
cube deployments build-status <deployment> --branch <dev-branch> --wait

# 8. Leave dev mode when done
cube data-model exit-dev-mode <deployment>

切勿直接在部署分支上进入开发模式。 commit 会推送到开发模式分叉自的分支，因此，从部署分支创建的开发分支会直接提交到生产环境。第 2 步能确保更改可以经过审查。

发布是单独的一步，且仅在用户明确要求时执行：

cube data-model merge-to-default <deployment> --branch <feature-branch> -m "Add revenue view"

此操作会将更改合并到部署分支，让所有人都能使用，并删除功能分支，除非传入 --keep-branch。

--branch 默认为当前激活的开发模式分支，因此第 3 步运行后通常可以省略它。不过，若在同一会话中处理多个部署，仍应显式传入该参数——默认值按用户而非按命令生效，很容易写入错误的位置。

其他文件操作遵循相同的分支规则：

cube data-model rename <deployment> model/cubes/old.yml model/cubes/new.yml --branch <dev-branch>
cube data-model delete <deployment> model/cubes/dead.yml --branch <dev-branch>

提交前验证（CLI）

cube validate <deployment> --dev-mode            # your uncommitted working copy
cube validate <deployment> --branch <branch>     # any named branch

此操作会在该分支自己的运行时上编译模型，并在出错时以非零状态退出，同时按文件列出错误。请原样报告错误，不要猜测原因——Cube 的模型错误会指出文件和成员。提交后，cube deployments build-status --wait 会给出构建的最终结果。

构建成功后，请确认更改确实可以用于查询。度量可能编译成功，但仍未在任何视图中公开：

cube meta --selectors '[{"type":"cube","deploymentId":<id>,"environment":"<dev-branch>"}]'

然后交由 cube-run-query 检查数值是否正确。编译成功不代表结果正确，SQL 有误的度量也能顺利构建。

改为部署本地项目

当用户想直接使用磁盘上的项目，而不是逐个文件进行修改时：

cube deploy <deployment> -m "<message>"   # uploads the local directory and builds

这与上文的开发模式工作流不同——它会用本地文件替换项目。如果当前有活跃的开发模式分支，就会部署到该分支；否则会部署到 deploy 分支。除非传入 --keep-missing，否则远程文件中不在本地目录里的文件会被删除。运行前，先说明更改将部署到哪个分支；如果要在同一项任务中混用这两种工作流，也必须提前说明。

约定

• Cube 是物理层；用户查询的是视图。新的业务指标通常应添加到视图中，或者先添加到 Cube，再通过视图公开。
• 每个文件只放一个 Cube，文件名与 Cube 同名。
• 编写 sql 表达式时，引用用户自己的定义。如果用户说“收入不包括退款”，就应将其写入 SQL 和 description，而不只是写在聊天中。

出错时的处理

症状	原因
写入被拒绝	不在开发模式分支上——运行 cube data-model dev-mode，并使用它输出的分支
validate 失败	模型存在实际错误——修复指定文件，并在提交前重新验证
not logged in	重新运行预检；不要重试写入
提交后构建失败	模型存在实际错误——阅读构建状态输出，并修复指定文件
更改已构建，但无法查询	未在视图中公开；检查 cube meta