cube-explore-model

探索 Cube 语义模型

只读。这里的任何操作都不会更改状态，因此你永远不需要 dev-mode 分支—— 这也意味着，即使你还不知道该怎么做，也可以运行其中任何操作。

选择路径

下文中的 Cube MCP 工具写作 cube:<tool>：这是此插件捆绑的 cube 服务。 通过 Cube 连接器使用时，相同的工具会带有连接器的名称。

如果 Cube MCP 工具可用（此插件的 cube 服务或 Cube 连接器），请使用它们——无需安装，也无需登录：

问题	MCP 工具
我可以查询什么；哪个视图包含某个字段	cube:searchDataModel — 已编译的模型，按含义搜索。省略 query 可列出所有内容
有哪些文件；某个文件写了什么	cube:listDataModelFiles、cube:readDataModelFile
某个分支做了哪些更改	cube:getBranchDiff
有哪些部署	cube:listDeployments，然后传入 deploymentId

cube:searchDataModel 的作用相当于下文的 cube meta：它回答可用性问题 （“是否已公开”），而文件回答编写位置问题（“写在什么地方”）。这种区别 以及影响分析检查清单，在两种路径中都适用。

当 MCP 工具未连接、需要在一次请求中获取所有文件内容以便进行文本搜索， 或需要使用 file-hashes 时，请使用 CLI 路径。

预检（CLI）

在开始时运行一次。如果任一检查失败，请停止并报告；不要 猜测凭据或编造部署 ID。

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 的重要性超乎表面所见。拥有 staging 和 production 上下文的用户可能不会说明他们指的是哪一个，而下面的每条命令 都需要一个仅在租户内唯一的部署 ID。

选择部署

每条数据模型命令都需要部署 ID。

cube deployments list            # table: ID, NAME, URL, STEP
cube deployments list --json     # when you need to filter programmatically

如果恰好只有一个部署，就使用它。如果有多个部署，而用户没有说明选哪个， 请询问——不要默认使用最低的 ID。

查看模型结构

从文件树开始。这是了解项目结构最省力的方式，无需先阅读任何内容。

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

Cube 项目通常会将立方体与视图分开：

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

视图是业务用户应该查询的内容；立方体是其底层构建模块。有人询问“我可以查询什么”时， 答案通常是视图，而不是所有立方体。

读取文件

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

查找定义位置

CLI 不支持服务端搜索。基本做法是在一个请求中获取所有文件的 内容，然后在本地搜索：

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

接着在该 JSON 中搜索你要查找的度量、维度或 SQL 片段。只需一个请求，之后可随意搜索—— 不要对每个路径循环运行 cube data-model get，这样更慢，也会产生更多无关内容。

以下情况适合使用此工具：

• “revenue 定义在哪里” → 找到该度量，并报告其文件和立方体
• “哪个立方体包含客户邮箱” → 搜索维度名称
• “active_user 实际上是什么意思” → 读取该度量的 sql 并原样引用，而不是转述

查询已编译模型，而不是文件

文件是源内容。已编译模型才是实际可查询的内容——它会解析 extends、 joins 和视图公开配置。有人问“我现在可以查询什么”时，请查询已编译模型：

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

• type 为 cube（语义层）或 d3（分析层）。
• environment 是分支名称；对于已部署的模型，则为 production。 省略它即可获取默认值。

如果问题涉及编写内容（“写在什么地方”“我应该改什么”），请使用文件。如果问题涉及 可用性（“是否已公开”“这个视图实际有哪些字段”），请使用 cube meta。 字段可能存在于立方体中，却没有出现在任何视图里——仅靠文件无法得知这一点， 而 cube meta 可以。

变更前的影响分析

有人询问重命名或删除会导致什么问题时，三项都要检查——只检查第一项不能算回答：

1. 直接引用。 搜索 --content 转储，在各个立方体和视图中查找字段名称：连接、sql 表达式、视图 includes。
2. 视图暴露情况。 检查 cube:searchDataModel 或 cube meta，确认该字段是否出现在视图中。视图中暴露的字段可能有下游使用方，仅凭模型无法发现。
3. 已保存内容。 报告和工作簿按名称引用成员。判断重命名是否安全前，交由 cube-explore-content 检查已保存内容。

明确说明检查了以上哪几项。“模型文件中没有直接引用，但我没有检查已保存的报告”是有用的回答；不加说明地说“可以安全重命名”则不是。

分支

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

file-hashes 会返回服务端内容哈希——无需拉取所有文件，就能轻松查看某个分支是否已偏离默认分支。

约定

• 列表命令会输出表格；添加 --json 可获取机器可读的输出。获取命令始终输出 JSON。
• 读取操作默认使用部署的默认分支。用户谈及进行中的工作时，务必传入 --branch。
• 按原样报告文件路径和立方体名称。orders.yml 和 Orders 是不同的对象，用户需要知道自己能实际操作的是哪一个。

出错时

症状	原因
not logged in	未解析到凭据——重新运行预检，不要重试命令
session expired — run cube login	刷新令牌已失效；用户必须重新进行身份验证
部署返回 403	该账户无权访问此部署，并非 ID 错误
文件列表为空	这是实际结果，通常表示部署尚未构建或刚创建——说明这一点，不要重试

绝不要编造输出中未出现的立方体、度量或文件路径。 如果模型中没有用户询问的内容，就如实说明——这是检查结果，而且往往就是问题的答案。