Back to Details

cube-build-model

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build and change a Cube semantic model

构建和修改Cube语义模型

Writes state. The API rejects file writes on any branch that is not a dev-mode branch, so the branch dance below is not optional ceremony — skip it and every write fails.
会写入状态。API会拒绝非开发模式分支上的文件写入操作，因此以下的分支操作并非可选流程——跳过的话所有写入都会失败。

Preflight

预检

bash
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
bash
command -v cube >/dev/null || echo "Cube CLI未安装：curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "未认证。交互式方式：cube login。无界面方式：设置CUBE_API_URL + CUBE_API_KEY。"
cube context list   # 写入前确认租户信息

Read before you write

先读取再写入

Never author against an assumed model. Pull the current state first:
bash
cube data-model list <deployment> --content --json > /tmp/model.json
Match the project's existing conventions — file layout, naming, whether measures live on cubes or views, how joins are declared. A correct cube that looks nothing like its neighbours is a bad contribution.
切勿基于假设的模型进行编写。请先拉取当前状态：
bash
cube data-model list <deployment> --content --json > /tmp/model.json
遵循项目现有的约定——文件布局、命名规则、度量是放在立方体还是视图上、关联的声明方式等。一个语法正确但与其他文件风格迥异的立方体是不合格的贡献。

The dev-mode workflow

开发模式工作流

bash
undefined
bash
undefined

1. See what branches exist

1. 查看现有分支

cube data-model branches <deployment>
cube data-model branches <deployment>

2. Enter dev mode on a base branch. This forks a personal 
dev-…
branch

2. 在基础分支上进入开发模式。这会创建一个个人的
dev-…
分支

and PRINTS ITS NAME. Capture it — writes must target it.

并打印其名称。请记录该名称——写入操作必须指向此分支。

cube data-model dev-mode <deployment> main
cube data-model dev-mode <deployment> main

3. Write files to that branch

3. 向该分支写入文件

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
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> # 标准输入

4. Commit

4. 提交

cube data-model commit <deployment> -m "Add revenue view" --branch <dev-branch>
cube data-model commit <deployment> -m "Add revenue view" --branch <dev-branch>

5. Confirm it actually builds

5. 确认构建成功

cube deployments build-status <deployment> --branch <dev-branch>
cube deployments build-status <deployment> --branch <dev-branch>

6. Leave dev mode when done

6. 完成后退出开发模式

cube data-model exit-dev-mode <deployment>

`--branch` defaults to your active dev-mode branch, so once step 2 has run you
can usually omit it. Pass it explicitly anyway when you are working across
more than one deployment in a session — the default is per-user, not
per-command, and it is easy to write to the wrong place.

Other file operations, same branch rules:

```bash
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>
cube data-model exit-dev-mode <deployment>

`--branch`参数默认指向你当前的开发模式分支，因此完成步骤2后通常可以省略该参数。但如果在一个会话中同时处理多个部署，请显式传递该参数——默认值是按用户设置的，而非按命令，很容易写入错误的位置。

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

```bash
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>

Validation is a build, not a linter

验证是构建过程，而非代码检查

There is no offline validate command. The way to know a change is good is to commit it and read the build:
bash
cube deployments build-status <deployment> --branch <dev-branch>
A failing build is the real error message. Report it verbatim rather than guessing at the cause — Cube's model errors name the file and the member.
After a green build, confirm the change is actually queryable. A measure can compile and still not be exposed in any view:
bash
cube meta --selectors '[{"type":"cube","deploymentId":<id>,"environment":"<dev-branch>"}]'
Then hand off to 
cube-run-query
to check the number is right. Compiling is not the same as being correct, and a measure whose SQL is wrong builds perfectly.
没有离线验证命令。确认修改是否正确的方式是提交并查看构建结果：
bash
cube deployments build-status <deployment> --branch <dev-branch>
构建失败会返回真实的错误信息。请直接报告错误内容，不要猜测原因——Cube的模型错误会指明文件名和具体成员。
构建成功后，请确认修改内容可被查询。一个度量可能编译成功，但未在任何视图中开放：
bash
cube meta --selectors '[{"type":"cube","deploymentId":<id>,"environment":"<dev-branch>"}]'
之后可以使用
cube-run-query
确认数值是否正确。编译成功不代表内容正确，SQL错误的度量也能完美构建。

Deploying a local project instead

替代方案：部署本地项目

When the user has the project on disk rather than wanting file-by-file edits:
bash
cube deploy <deployment>   # uploads the local directory to the deployment and builds
This is a different workflow from the dev-mode one above — it replaces the project from local files. Do not mix the two in one task without saying so.
如果用户本地已有项目，而非需要逐文件编辑：
bash
cube deploy <deployment>   # 将本地目录上传到部署环境并构建
这与上述开发模式工作流不同——它会用本地文件替换项目内容。请勿在同一任务中混用两种工作流，除非明确说明。

Conventions

约定

  • Cubes are the physical layer; views are what users query. New business metrics usually belong on a view, or on a cube and then exposed via a view.
  • Keep one cube per file, named after the cube.
  • Quote the user's own definition back when you write a 
    sql
    expression. If they said "revenue excludes refunds", that belongs in the SQL and in a 
    description
    , not just in the chat.
  • 立方体是物理层；视图是用户查询的对象。新的业务指标通常应放在视图上，或先放在立方体上再通过视图开放。
  • 每个文件对应一个立方体，文件名与立方体名称一致。
  • 编写
    sql
    表达式时，请引用用户自己的定义。如果用户说“收入不包含退款”，这句话应出现在SQL和
    description
    中，而不只是聊天记录里。

When something fails

故障排查

SymptomCause
Write rejectedNot on a dev-mode branch — run 
cube data-model dev-mode
and use the branch it prints
not logged in
Rerun the preflight; do not retry the write
Build fails after commitReal model error — read the build status output and fix the named file
Change builds but is not queryableNot exposed in a view; check 
cube meta
症状原因
写入被拒绝未处于开发模式分支——运行
cube data-model dev-mode
并使用打印出的分支
not logged in
重新执行预检步骤；不要重试写入操作
提交后构建失败真实的模型错误——查看构建状态输出并修复指定文件
修改构建成功但无法查询未在视图中开放；检查
cube meta