cubes

多维数据集

多维数据集是组织语义模型中存储的一项定义：它读取哪个数据仓库表（sql_table）、用于分组和筛选的维度、用于聚合的度量，以及与其他多维数据集的联接。表、分段和所有语义模型查询都构建在这些定义之上。

你可以通过 RevOS MCP 服务在 cubes 资源上调用通用工具来访问它们：

调用	功能
api_read { "resource": "cubes", "params": { "fields": "id,name,updatedAt" } }	列出已存储的定义
api_read { "resource": "cubes", "id": "<cube id>" }	获取一项已存储的定义，位于 definition 下
api_read { "resource": "cubes", "method": "meta", "params": { "filter": "name == \"crm_deals\"" } }	获取组织可查询的已编译多维数据集
api_write { "resource": "cubes", "data": { "name", "definition" } }	创建
api_write { "resource": "cubes", "id": "<cube id>", "data": { "definition" } }	更新
api_delete { "resource": "cubes", "id": "<cube id>" }	删除

记录必须放在 data 下。放在其他键下的正文可能会被忽略，且不会报错。api_details({ resource: "cubes", operation: "create" }) 是定义 JSON 架构的权威来源。

需要牢记的一点

服务端会检查定义的结构，但不会检查它能否编译；而 Cube 会将组织的所有多维数据集一起编译。 未知的维度、度量和联接键会被拒绝，并返回注明名称的错误；但定义顶层的未知键（例如用 sqlTable 代替 sql_table）会被静默丢弃，可能导致多维数据集没有数据源。始终也要发送 definition.name：创建时它是可选的，但 Cube 会根据它进行编译。无法编译的定义不会导致保存失败。 它会导致整个组织的语义模型失效：在有人修复之前，所有表、分段和查询都会报错。常见原因包括联接到不存在的多维数据集、${…} 引用了不存在的成员，或删除了某个维度，但表列仍在使用它。列名错误或 SQL 有问题则不那么明显：模型可以编译，只有查询到该成员时才会失败。

因此，每次写入都遵循相同的流程：

1. 保留写入前的状态。 编辑时，保存刚读取到的完整 definition。创建时，记下新 ID。
2. 写入。
3. 立即使用按多维数据集名称筛选的 meta 进行验证。 如果这里报错，说明组织的模型已无法编译。立即还原：写回已保存的定义，或删除刚创建的多维数据集。然后告知用户发生了什么，并且不要在模型已损坏时继续编辑。错误本身只会显示“The RevOS API failed with status 500”——编译错误不会传递出来，因此不要向用户保证具体原因；请引导他们查看日志或 Cube Playground。如果 meta 仍显示旧版本，请等待几秒后重新读取；Cube 会轮询变更。
4. 验证 SQL。 使用一个包含你新增或更改的成员的小型查询进行验证： api_read { "resource": "cubes", "method": "query", "body": { "query": { "dimensions": ["crm_deals.stage"], "measures": ["crm_deals.count"], "limit": 3 } } }。 这里的错误会指出出问题的列或表达式。按相同方式修复。

写入需要 Developer（或 Admin）角色。403 表示已连接的用户没有相应角色，因此应直接说明，而不是重试。

首次写入前：两项检查

哪些是生成的，而不是存储的？ meta 会列出已存储的立方体，以及 RevOS 生成的内容：每个包含已存储列或评分的表对应一个立方体（model_stream_…___local，标题为 [Table] <name>），每个静态分段对应一个立方体（segment_…，标题为 [Segment] <name>），每个表对应一个视图（model_…）。这些生成内容还会为已存储的立方体添加联接，因此 meta 中某个立方体的 joins 可能包含其已存储定义中没有的联接。即使组织没有存储任何立方体，也会显示这些生成的内容；创建立方体只会在此基础上添加，不会移除任何内容。

这些立方体是否以代码管理？ 有些组织会通过代码库和 RevOS CLI（revos apply）发布立方体。在这里所做的编辑会在他们下次 apply 时被覆盖。如果用户提到代码库或 CLI，请引导他们到相应位置操作。

阅读

• 定义了什么，以及如何定义：使用 fields: "id,name,updatedAt" 列出，然后按 id 获取完整的 definition。列表的 filter 是针对 name 的 CEL（name == "crm_deals"、name.startsWith("hubspot_")）。
• 实际可查询的内容：meta。它与已存储列表不同：
  • 它是编译后的。成员名称完全限定，例如 crm_deals.amount，并使用 camelCase 键。
  • 它会加入 RevOS 自行生成的立方体，这些内容无需编写：
    • 每个包含已存储列或评分的表对应一个立方体，名称为 model_stream_…___local（只读取立方体的表不会生成立方体）；
    • 每个静态分段对应一个立方体，名称为 segment_…；
    • 每个表对应一个视图。

当用户询问某个立方体的定义时，展示已存储定义中的相关部分：表、带类型的维度、度量和联接。用通俗易懂的语言说明。不要直接输出 JSON。要回答关于数据的问题，请切换到 semantic-model。

依赖某个立方体的内容

重命名、移除或删除立方体前，先找出使用它的内容。任何对旧名称或成员的引用都会失效：

• 其他立方体：某个 joins 键与该立方体名称相同，或任何联接、维度或度量 SQL 中包含 ${name.…}。获取每个已存储定义并进行搜索。联接可以在任一侧声明。
• 表：使用以下命令列出： api_read { "resource": "tables", "params": { "fields": "id,name,streams,objectsColumns" } }。 每个表包含：
  • streams[].id（立方体名称）和 streams[].joinPath（以点分隔的立方体名称）；
  • objectsColumns[]：每个 external: true 项都有 streamId + path，指向立方体的某个维度，或者在 measure: true 时指向其度量。没有 joinPath 的流会按 <root>.<id> 进行联接。
• 分段：先列出，再按 id 获取每个分段。每个分段都包含 cubes[].joinPath 以及其 filter 中的 member。STATIC 分段还会在 cubes[0] 的 primaryKeyDimension 上联接其 segment_… 立方体。
• 仪表板卡片：使用以下命令列出： api_read { "resource": "dashboard-cards", "params": { "fields": "id,dashboardId,title,measure,breakdown,filter,joinPaths", "pageSize": 200 } }。 每张卡片都会在 measure、breakdown 和 filter 中引用成员，并在 joinPaths 中引用立方体。模型变更时不会检查卡片：卡片损坏不会阻止模型编译，只会在仪表板上显示为不可用——但仍值得告知用户。

执行操作前，先向用户报告查到的依赖项：“crm_deals 被 Deals 表（7 列）、2 个分段和 3 张仪表板卡片使用”。

创建、编辑、删除

每项操作都有各自的参考文档。写入前，先阅读所需文档：

• 新建立方体：references/create.md
• 更改立方体（添加或修复成员、联接、重命名）：references/edit.md
• 删除立方体：references/delete.md
• 定义语法（维度、度量、联接、SQL 引用）：references/definition.md

汇报结果

写入后，用两到三句话告诉用户：

• 改了什么，用用户的说法描述（“在 Deals 上添加了 Amount 作为求和度量”）；
• meta 已编译，并且运行了一条测试查询；
• 你做了哪些判断，例如某个联接的关系或某个维度的类型。

如果你必须还原，请明确说明，并告知导致还原的错误。