cubes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cubes

A cube is one stored definition in the org's semantic model: which warehouse table it reads (

sql_table

), the dimensions you group and filter by, the measures you aggregate, and the joins to other cubes. Tables, segments, and every semantic-model query are built on top of these.

You reach them through the RevOS MCP server's generic tools on the

cubes

resource:

Call	What it does
`api_read { "resource": "cubes", "params": { "fields": "id,name,updatedAt" } }`	list the stored definitions
`api_read { "resource": "cubes", "id": "<cube id>" }`	one stored definition, under `definition`
`api_read { "resource": "cubes", "method": "meta", "params": { "filter": "name == \"crm_deals\"" } }`	the compiled cube as the org can query it
`api_write { "resource": "cubes", "data": { "name", "definition" } }`	create
`api_write { "resource": "cubes", "id": "<cube id>", "data": { "definition" } }`	update
`api_delete { "resource": "cubes", "id": "<cube id>" }`	delete

The record always goes under

data

. A body under any other key may be ignored without an error.

api_details({ resource: "cubes", operation: "create" })

is the authority on the definition's JSON schema.

cube 是组织语义模型中一个已存储的定义：它读取哪个 warehouse table（

sql_table

）、你用于分组和筛选的 dimensions、你进行聚合的 measures，以及它与其他 cubes 的 joins。Tables、segments 和所有 semantic-model 查询都构建在这些定义之上。

你通过 RevOS MCP server 的通用工具访问

cubes

resource：

调用	作用
`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\"" } }`	获取组织实际可查询的已编译 cube
`api_write { "resource": "cubes", "data": { "name", "definition" } }`	创建
`api_write { "resource": "cubes", "id": "<cube id>", "data": { "definition" } }`	更新
`api_delete { "resource": "cubes", "id": "<cube id>" }`	删除

记录必须始终放在

data

下。放在其他 key 下的 body 可能会被忽略，且不会报错。

api_details({ resource: "cubes", operation: "create" })

是 definition JSON schema 的权威参考。

The one thing to keep in mind

需要牢记的一点

The server stores whatever you send, and Cube compiles all of the org's cubes together. A definition that doesn't compile doesn't fail on save. It fails the whole org's semantic model: every table, segment, and query errors until someone fixes it. Common causes are a join to a cube that doesn't exist, a

${…}

reference to a member that isn't there, or a removed dimension that a table column still uses. A wrong column name or bad SQL is quieter: the model compiles, and only queries touching that member fail.

So every write follows the same loop:

Keep the before-state. For an edit, hold the full current
```
definition
```
you just read. For a create, remember the new id.
Write.
Verify at once with
```
meta
```
filtered to the cube's name. An error there means the org's model no longer compiles. Restore immediately: write the saved definition back, or delete the cube you just created. Then tell the user what happened, and don't keep editing on a broken model. If
```
meta
```
still shows the old version, wait a few seconds and read again; Cube polls for changes.

Prove the SQL with one small query over the members you added or changed:

api_read { "resource": "cubes", "method": "query", "body": { "query": { "dimensions": ["crm_deals.stage"], "measures": ["crm_deals.count"], "limit": 3 } } }

. An error here names the bad column or expression. Fix it the same way.

Writes need the Developer role. A 403 means the connected user doesn't have it, so say so rather than retrying.

服务器会原样存储你发送的内容，而 Cube 会将组织中的所有 cubes 一起编译。 无法编译的定义不会在保存时失败。相反，它会导致整个组织的语义模型失败：每个 table、segment 和 query 都会报错，直到有人修复它。常见原因包括：join 指向不存在的 cube、存在对不存在 member 的

${…}

引用，或已移除的 dimension 仍被某个 table column 使用。错误的 column name 或无效 SQL 往往更隐蔽：模型仍可编译，只有涉及该 member 的查询失败。

因此，每次写入都应遵循同一个流程：

保留变更前的状态。 对于编辑操作，保留你刚读取到的完整当前
```
definition
```
。对于创建操作，记住所用的新 id。
写入。
立即验证：使用按 cube 名称过滤的
```
meta
```
。如果这里出现错误，说明组织的模型已无法编译。立即恢复：将保存的 definition 写回，或删除刚创建的 cube。然后告知用户发生了什么，不要继续编辑已经损坏的模型。如果
```
meta
```
仍显示旧版本，请等待几秒后再次读取；Cube 会轮询变更。
用一次小查询验证 SQL，查询范围应覆盖你添加或修改的 members：
```
api_read { "resource": "cubes", "method": "query", "body": { "query": { "dimensions": ["crm_deals.stage"], "measures": ["crm_deals.count"], "limit": 3 } } }
```
。这里的错误会指出错误的 column 或 expression。以相同方式修复。

写入需要 Developer 角色。403 表示连接的用户没有该角色，因此应直接说明，不要重试。

Before the first write: two checks

首次写入前的两项检查

Is the org in cubes mode? If the stored list is empty but

meta

returns cubes, the org is still on the legacy, auto-generated model. Creating its first stored cube switches the org to cubes mode, and every auto-generated cube disappears with it. Don't create one. Tell the user it needs a deliberate migration in RevOS instead.

Are the cubes managed as code? Some orgs ship cubes from a repo with the RevOS CLI (

revos apply

). An edit made here is overwritten on their next apply. If the user mentions a repo or the CLI, point them there instead.

组织是否处于 cubes mode？ 如果已存储的列表为空，但

meta

返回了 cubes，说明组织仍使用旧版自动生成的模型。创建它的第一个已存储 cube 会将组织切换到 cubes mode，同时所有自动生成的 cubes 都会消失。不要执行创建。应告知用户，需要在 RevOS 中进行有意迁移。

cubes 是否以 code 方式管理？ 一些组织会通过 RevOS CLI（

revos apply

）从 repo 部署 cubes。此处所做的编辑会在他们下次 apply 时被覆盖。如果用户提到 repo 或 CLI，应引导他们使用该方式。

Reading

读取

What's defined, and how: list with

fields: "id,name,updatedAt"

, then

get

by id for the full

definition

. The list's

filter

is CEL on

name

(

name == "crm_deals"

name.startsWith("hubspot_")

What's actually queryable:
```
meta
```
. It differs from the stored list:
- It is compiled. Members are fully qualified, such as
```
crm_deals.amount
```
  , and use camelCase keys.
- It adds the cubes RevOS generates itself, which you never write:
  - a cube per table, named
```
model_stream_…___local
```
    ;
  - a cube per static segment, named
```
segment_…
```
    ;
  - a view per table.

When the user asks how a cube is defined, show the relevant part of the stored definition: the table, the dimensions with their types, the measures, and the joins. Explain it in plain words. Don't dump the JSON. To answer questions about the data, switch to query-semantic-model.

定义了什么以及如何定义：使用
```
fields: "id,name,updatedAt"
```
列出，再通过 id 执行
```
get
```
获取完整的
```
definition
```
。列表的
```
filter
```
使用针对
```
name
```
的 CEL（
```
name == "crm_deals"
```
、
```
name.startsWith("hubspot_")
```
）。
实际可查询的内容：使用
```
meta
```
。它与已存储的列表不同：
- 它是已编译的。Members 使用完全限定名称，例如
```
crm_deals.amount
```
  ，并采用 camelCase keys。
- 它会添加 RevOS 自动生成且不应由你写入的 cubes：
  - 每个 table 对应一个 cube，名称为
```
model_stream_…___local
```
    ；
  - 每个 static segment 对应一个 cube，名称为
```
segment_…
```
    ；
  - 每个 table 对应一个 view。

当用户询问 cube 的定义时，展示已存储 definition 中相关的部分：table、带类型的 dimensions、measures 和 joins。用平实语言解释，不要直接倾倒 JSON。要回答关于数据本身的问题，请切换到 query-semantic-model。

Who depends on a cube

哪些对象依赖某个 cube

Before you rename or remove anything, or delete a cube, find its users. Each reference to the old name or member breaks:

Other cubes: a
```
joins
```
key equal to this cube's name, or
```
${name.…}
```
in any join, dimension, or measure SQL. Get each stored definition and search it. Joins are declared on either side.

Tables: list them with

api_read { "resource": "tables", "params": { "fields": "id,name,streams,objectsColumns" } }

. Each table has:

```
streams[].id
```
(a cube name) and
```
streams[].joinPath
```
(dotted cube names);
```
objectsColumns[]
```
, whose
```
streamId
```
+
```
path
```
point at a cube's dimension.

Segments: list them, then
```
get
```
each by id. Each has
```
cubes[].joinPath
```
and the
```
member
```
s in its
```
filter
```
.

Report what you found to the user before acting: "crm_deals is used by the Deals table (7 columns) and 2 segments".

在重命名或移除任何内容之前，或删除 cube 之前，找出其使用者。对旧名称或 member 的每处引用都会失效：

其他 cubes：
```
joins
```
key 等于该 cube 的名称，或任何 join、dimension 或 measure SQL 中存在
```
${name.…}
```
。获取每个已存储的 definition 并进行搜索。Joins 可以在任意一侧声明。
Tables：使用以下调用列出它们：
```
api_read { "resource": "tables", "params": { "fields": "id,name,streams,objectsColumns" } }
```
。每个 table 包含：
- ```
streams[].id
```
  （cube 名称）和
```
streams[].joinPath
```
  （以点分隔的 cube 名称）；
- ```
objectsColumns[]
```
  ，其中的
```
streamId
```
  和
```
path
```
  指向某个 cube 的 dimension。
Segments：先列出 segments，再通过 id 逐个执行
```
get
```
。每个 segment 包含
```
cubes[].joinPath
```
，其
```
filter
```
中包含
```
member
```
s。

执行操作前，向用户报告发现结果：“crm_deals 被 Deals table（7 个 columns）和 2 个 segments 使用”。

Creating, editing, deleting

创建、编辑和删除

Each has its own reference. Read the one you need before writing:

New cube: references/create.md
Change a cube (add or fix members, joins, rename): references/edit.md
Delete a cube: references/delete.md
Definition syntax (dimensions, measures, joins, SQL references): references/definition.md

每种操作都有自己的参考文档。写入前阅读所需文档：

新建 cube：references/create.md
修改 cube（添加或修复 members、joins、重命名）：references/edit.md
删除 cube：references/delete.md
定义语法（dimensions、measures、joins、SQL 引用）：references/definition.md

Reporting back

反馈结果

After a write, tell the user in two or three sentences:

what changed, in their terms ("added Amount as a sum measure on Deals");
that
```
meta
```
compiled and a test query ran;
any judgment call you made, such as a join's relationship or a dimension's type.

If you had to restore, say so plainly, along with the error that caused it.

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

用用户能理解的说法说明变更内容（“在 Deals 上将 Amount 添加为 sum measure”）；
说明
```
meta
```
已成功编译，并且已运行测试 query；
说明你做出的判断，例如 join 的 relationship 或 dimension 的 type。

如果你不得不执行恢复，应坦率说明，并附上导致问题的 error。