cube-explore-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explore a Cube semantic model

探索Cube语义模型

Read-only. Nothing here changes state, so you never need a dev-mode branch — which also means you can run any of it before you know what you're doing.

只读操作。此处不会更改任何状态，因此您无需使用开发模式分支——这也意味着您可以在尚不明确操作内容的情况下运行任何命令。

Preflight

预检步骤

Run this once at the start. Stop and report if either check fails; do not guess at credentials or invent a deployment id.

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   # multi-tenant: confirm you are pointed at the right tenant

cube context list

matters more than it looks. A user with staging and production contexts will not mention which one they mean, and every command below takes a deployment id that is only unique within a tenant.

开始前先运行一次以下命令。如果任一检查失败，请停止操作并报告；不要猜测凭证或自行生成deployment id。

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   # 多租户场景：确认您指向的是正确的租户

cube context list

的重要性远超表面。同时拥有 staging 和 production 上下文的用户可能不会说明他们指的是哪一个，而以下所有命令都需要一个仅在租户内部唯一的deployment id。

Pick the deployment

选择deployment

Every data-model command needs a deployment id.

bash

cube deployments list            # table: id, name, status
cube deployments list --json     # when you need to filter programmatically

If exactly one deployment exists, use it. If several do and the user hasn't said which, ask — do not assume the lowest id.

每个数据模型命令都需要一个deployment id。

bash

cube deployments list            # 表格形式：id、名称、状态
cube deployments list --json     # 需要以编程方式筛选时使用

如果仅存在一个deployment，则直接使用它。如果存在多个且用户未指定，请询问用户——不要默认选择id最小的那个。

Map the model

映射模型

Start with the file tree. This is the cheapest way to see the shape of a project before reading anything.

bash

cube data-model list <deployment>
cube data-model list <deployment> --branch <branch>   # a specific branch

Cube projects conventionally separate cubes from views:

model/
  cubes/       one file per cube — the physical layer, joined to tables
  views/       one file per view — the curated layer users query

Views are what business users should be querying; cubes are the building blocks underneath. When someone asks "what can I query", the answer is usually the views, not every cube.

从文件树开始。这是在阅读具体内容前了解项目结构最快捷的方式。

bash

cube data-model list <deployment>
cube data-model list <deployment> --branch <branch>   # 指定分支

Cube项目通常将cubes和views分开存放：

model/
  cubes/       每个cube对应一个文件——物理层，与数据表关联
  views/       每个view对应一个文件——供用户查询的精选层

Views是业务用户应该查询的对象；cubes是底层的构建模块。当有人问“我可以查询什么”时，答案通常是views，而非所有cubes。

Read a file

读取文件

bash

cube data-model get <deployment> model/cubes/orders.yml
cube data-model get <deployment> model/views/revenue.yml --branch <branch>

bash

cube data-model get <deployment> model/cubes/orders.yml
cube data-model get <deployment> model/views/revenue.yml --branch <branch>

Find where something is defined

查找定义位置

There is no server-side search. The primitive is to pull every file's content in one request and search locally:

bash

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

Then search that JSON for the measure, dimension, or SQL fragment you're after. One request, then as many searches as you like — do not loop

cube data-model get

over every path, which is slower and noisier.

This is the right tool for:

"where is
```
revenue
```
defined" → find the measure, report its file and cube
"which cube has customer email" → search dimension names
"what does
```
active_user
```
actually mean" → read the
```
sql
```
of the measure and quote it back rather than paraphrasing

目前没有服务器端搜索功能。基本方法是一次性拉取所有文件内容，然后在本地搜索：

bash

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

然后在该JSON中搜索您要找的measure、dimension或SQL片段。只需一次请求，即可进行多次搜索——不要循环调用

cube data-model get

遍历每个路径，这种方式更慢且噪音更大。

这适用于以下场景：

“
```
revenue
```
定义在哪里” → 找到该measure，报告其所在文件和cube
“哪个cube包含客户邮箱” → 搜索dimension名称
“
```
active_user
```
实际含义是什么” → 读取该measure的
```
sql
```
内容并直接引用，而非转述

Ask the compiled model, not the files

查询编译后的模型，而非源文件

The files are the source. The compiled model is what is actually queryable — after extends, joins and view exposure are resolved. When the question is "what can I query right now", ask the compiled model:

bash

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

```
type
```
is
```
cube
```
(the semantic layer) or
```
d3
```
(the analytics layer).
```
environment
```
is a branch name, or
```
production
```
for the deployed model. Omit it to get the default.

Use the files when the question is about authoring ("where is this written", "what should I change"). Use

cube meta

when the question is about availability ("is this exposed", "what fields does this view actually have"). A field can exist in a cube and still be absent from every view — the files will not tell you that on their own, and

cube meta

will.

源文件是原始内容。编译后的模型才是实际可查询的对象——已经解析了extends、joins和view exposure。当问题是“我现在可以查询什么”时，查询编译后的模型：

bash

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

```
type
```
可以是
```
cube
```
（语义层）或
```
d3
```
（分析层）。
```
environment
```
是分支名称，或已部署模型的
```
production
```
。省略则使用默认值。

当问题涉及创作（“这是在哪里编写的”、“我应该修改什么”）时，使用源文件。当问题涉及可用性（“这个是否已暴露”、“这个view实际有哪些字段”）时，使用

cube meta

。某个字段可能存在于cube中，但并未出现在任何view中——源文件无法单独告知您这一点，而

cube meta

可以。

Impact analysis before a change

变更前的影响分析

When asked what a rename or deletion would break, do all three — the first alone is not an answer:

Direct references. Search the
```
--content
```
dump for the field name across cubes and views: joins,
```
sql
```
expressions, view
```
includes
```
.
View exposure. Check
```
cube meta
```
for whether the field surfaces in a view. A field exposed in a view has downstream consumers you cannot see from the model alone.
Saved content. Reports and workbooks reference members by name. Hand off to
```
cube-explore-content
```
to check saved content before calling a rename safe.

Say plainly which of the three you checked. "No direct references in the model files, but I did not check saved reports" is a useful answer; "safe to rename" without that qualification is not.

当被问及重命名或删除操作会导致什么失效时，请完成以下三项检查——仅做第一项不足以构成完整答案：

直接引用：在
```
--content
```
导出的内容中搜索字段名称，覆盖cubes和views：joins、
```
sql
```
表达式、view
```
includes
```
。
View暴露情况：通过
```
cube meta
```
检查该字段是否在view中暴露。在view中暴露的字段会有无法从模型本身看到的下游消费者。
已保存内容：报表和工作簿通过名称引用成员。在确认重命名安全前，请转交
```
cube-explore-content
```
检查已保存内容。

明确说明您完成了哪三项检查。“模型文件中无直接引用，但未检查已保存报表”是有用的答案；未加限定的“可以安全重命名”则不是。

Branches

分支操作

bash

cube data-model branches <deployment>
cube data-model file-hashes <deployment> --branch <branch>

file-hashes

returns server-side content hashes — the cheap way to see whether a branch has diverged from the default without pulling every file.

bash

cube data-model branches <deployment>
cube data-model file-hashes <deployment> --branch <branch>

file-hashes

返回服务器端内容哈希值——无需拉取所有文件即可快速查看分支是否与默认分支存在差异。

Conventions

约定

List commands print tables; add
```
--json
```
for machine-readable output. Get commands always print JSON.
Reads default to the deployment's default branch. Pass
```
--branch
```
whenever the user is talking about work in progress.
Report file paths and cube names exactly as they appear.
```
orders.yml
```
and
```
Orders
```
are different things and the user needs the one they can act on.

列表命令默认输出表格；添加
```
--json
```
可获取机器可读格式。获取命令始终输出JSON。
读取操作默认使用deployment的默认分支。当用户提及正在进行的工作时，请传递
```
--branch
```
参数。
严格按照输出显示的内容报告文件路径和cube名称。
```
orders.yml
```
和
```
Orders
```
是不同的对象，用户需要能直接操作的那个。

When something fails

故障排查

Symptom	Cause
`not logged in`	No credentials resolved — rerun the preflight, don't retry the command
`session expired — run cube login`	Refresh token is dead; the user must re-authenticate
403 on a deployment	The account lacks access to that deployment, not a bad id
Empty file list	Real, and usually means an unbuilt or newly created deployment — say so rather than retrying

Never invent a cube, measure, or file path that you have not seen in output. If the model does not contain what the user is asking about, say that — it is a finding, and often the actual answer.

症状	原因
`not logged in`	未解析到凭证——重新运行预检步骤，不要重试命令
`session expired — run cube login`	刷新令牌已失效；用户必须重新认证
访问deployment时出现403错误	该账户无此deployment的访问权限，并非id错误
文件列表为空	真实情况，通常表示deployment未构建或刚创建——如实说明，不要重试

切勿编造未在输出中看到的cube、measure或文件路径。如果模型中没有用户询问的内容，请如实告知——这是一个有效的发现，往往就是实际答案。