tables

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tables

表格

A table, called a scoring model in the API, is a set of rows with typed columns:

Rows come from the table's root cube: the cube of its first stream, so a companies table has one row per
```
crm_companies
```
record. A table that stores its own
```
id
```
column holds its own rows instead.
Columns are one of three kinds:
- external: read live from a cube member. The column has
```
streamId
```
  (which cube) and
```
path
```
  (which member).
- stored: values kept in RevOS itself, typed in or written by actions. These need no stream.
- action: runs an integration action per row and keeps the result.
Streams list the cubes the table reads, with how each is reached from the root (
```
joinPath
```
).
Views are layouts of the table. The default view also decides which rows show, through an attached segment or an ad-hoc filter.

You reach tables through the RevOS MCP server's generic tools:

Call	What it does
`api_read { "resource": "tables", "params": { "fields": "id,name,updatedAt" } }`	list tables
`api_read { "resource": "tables", "id": "<table id>" }`	one table: `objectsColumns` , `streams` , `views` , `scoringFeatures`
`api_write { "resource": "tables", "data": { "name": "…" } }`	create (name only)
`api_write { "resource": "tables", "id": "<table id>", "data": { … } }`	update `name` , `objectsColumns` , `streams`
`api_read { "resource": "table-views", "method": "list", "id": "<TABLE id>" }`	the table's views
`api_write { "resource": "table-views", "id": "<VIEW id>", "data": { … } }`	update a view: `segmentId` , `filter` , `columns`

The record always goes under

data

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

api_details({ resource: "tables", operation: "update" })

is the authority on the column and stream shapes. There is no column endpoint: columns change through the table's

objectsColumns

array, and tables can't be deleted from here (see Deleting below).

一个表格（在 API 中称为 scoring model）由一组带类型的行和列组成：

行来自表格的 root cube：即其第一个 stream 的 cube，因此 companies 表格中每条
```
crm_companies
```
记录对应一行。如果表格存储了自己的
```
id
```
列，则它保存的是自身的行，而不是 root cube 的行。
列分为三种：
- external：从 cube member 实时读取。该列包含
```
streamId
```
  （所属 cube）和
```
path
```
  （所属 member）。
- stored：值保存在 RevOS 本身中，由 action 输入或写入，不需要 stream。
- action：针对每一行运行 integration action，并保留结果。
Stream 列出表格读取的 cube，以及从 root 到达每个 cube 的方式（
```
joinPath
```
）。
View 是表格的布局。默认 view 还通过附加的 segment 或临时筛选（ad-hoc filter）决定显示哪些行。

通过 RevOS MCP server 的通用工具访问表格：

Call	What it does
`api_read { "resource": "tables", "params": { "fields": "id,name,updatedAt" } }`	列出表格
`api_read { "resource": "tables", "id": "<table id>" }`	单个表格： `objectsColumns` 、 `streams` 、 `views` 、 `scoringFeatures`
`api_write { "resource": "tables", "data": { "name": "…" } }`	创建（仅名称）
`api_write { "resource": "tables", "id": "<table id>", "data": { … } }`	更新 `name` 、 `objectsColumns` 、 `streams`
`api_read { "resource": "table-views", "method": "list", "id": "<TABLE id>" }`	表格的 views
`api_write { "resource": "table-views", "id": "<VIEW id>", "data": { … } }`	更新 view： `segmentId` 、 `filter` 、 `columns`

记录始终放在

data

下。放在其他键下的 body 可能会在无报错的情况下被忽略。

api_details({ resource: "tables", operation: "update" })

是 column 和 stream 结构形状的权威说明。这里没有 column endpoint：column 通过表格的

objectsColumns

数组进行修改，而且无法从此处删除表格（见下文删除）。

The three things to keep in mind

需要牢记的三件事

1.
objectsColumns
and
streams
are replaced whole. An update stores the array you send instead of the stored one:

A column you leave out is removed from the table and from every view.
```
name
```
alone is a safe partial update.
Sending
```
objectsColumns
```
without
```
streams
```
keeps the stored streams.
A stream disappears by itself with the last column that read it (the root stays), so you rarely send
```
streams
```
except to add one.

2. A table compiles into the org's semantic model. RevOS generates a Cube view per table from its streams and external columns. The server doesn't check them on save. Any of these breaks every table, segment, and query in the org until it's fixed:

a stream
```
id
```
that isn't a cube;
a
```
joinPath
```
hop that isn't a declared join;
an external column whose
```
path
```
isn't a member of its stream's cube;
an empty table name.

3. One row per root record. A field from a "many" cube doesn't fit. Before you add a column from any cube other than the root, find out how many of that cube each root record has. Look at the join between the two cubes, from both sides, because it may be declared on either:

join found	root has…	a dimension column from it
root → other: `many_to_one` or `one_to_one`	one	fine
other → root: `one_to_many`	one	fine
root → other: `one_to_many`	many	don't add
other → root: `many_to_one` (e.g. `crm_deals → crm_companies` )	many	don't add

"Deal stage" on a companies table is the last row of that table: each company has many deals, so there is no single stage to show, and the column would repeat or scramble rows. Don't add it, even as a caveat. Stop and tell the user why. Then offer what does fit:

an aggregate from that cube as a measure column (
```
measure: true
```
): a count, a sum, or a filtered count such as "won deals", if the cube has one or one is added to it (the cubes skill);
the same field on a table rooted on that cube (the Deals table);
a filter on the rows through a segment ("companies with a won deal").

So every write follows the same loop:

Read fresh (
```
api_read
```
the table by id) right before writing. Keep the
```
objectsColumns
```
and
```
streams
```
you got. They are your undo.
Write the arrays with only your change applied.
Verify at once:
- ```
api_read { "resource": "cubes", "method": "meta", "params": { "fields": "name", "pageSize": 100 } }
```
  must succeed. An error means the org's model no longer compiles. Restore the saved arrays immediately, and then tell the user.
- Query the table's view over the columns you touched:
```
api_read { "resource": "cubes", "method": "query", "body": { "query": { "dimensions": ["<view>.<column name>"], "limit": 3 } } }
```
  . The view is named
```
model_<table id with - replaced by _>
```
  , and its members are the column names. An error names the bad member.
Read the table back and check that the columns are what you meant.

1.
objectsColumns
和
streams
会被整体替换。更新时会存储你发送的数组，而不是原有数组：

未包含在更新中的列会从表格及每个 view 中移除。
仅发送
```
name
```
是安全的部分更新。
发送
```
objectsColumns
```
而不发送
```
streams
```
，会保留已存储的 streams。
当最后一个读取某 stream 的列被移除时，该 stream 会自行消失（root 会保留），因此除了添加 stream 之外，很少需要发送
```
streams
```
。

2. 表格会编译为组织的 semantic model。 RevOS 会根据 streams 和 external columns 为每个表格生成一个 Cube view。服务器不会在保存时检查它们。以下任何问题都会破坏组织中的所有表格、segment 和 query，直到修复为止：

不是 cube 的 stream
```
id
```
；
不是已声明 join 的
```
joinPath
```
hop；
```
path
```
不是其 stream 所属 cube 的 member 的 external column；
空的表格名称。

3. 每条 root record 对应一行。来自“many”cube 的字段不适用。

在添加来自 root 以外任何 cube 的列之前，先确定每条 root record 对应多少条该 cube 的记录。要从两个方向查看两个 cube 之间的 join，因为 join 可能声明在其中任意一侧：

找到的 join	root 有…	来自该 cube 的 dimension column
root → other： `many_to_one` 或 `one_to_one`	one	可以
other → root： `one_to_many`	one	可以
root → other： `one_to_many`	many	不要添加
other → root： `many_to_one` （例如 `crm_deals → crm_companies` ）	many	不要添加

companies 表格中的“Deal stage”是该表格的最后一列：每家公司都有多笔交易，因此没有可显示的单一阶段，该列会重复或打乱各行。不要添加它，即使附带说明也不要添加。 请停止操作并告诉用户原因。然后提供以下合适方案：

该 cube 的 aggregate，以 measure column（
```
measure: true
```
）形式使用：计数、求和或筛选计数，例如“won deals”；前提是 cube 中已有相应 measure，或已通过 cubes skill 添加一个；
以该 cube 为 root 的表格上的同一字段（Deals 表格）；
通过 segment 筛选行（“有 won deal 的 companies”）。

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

读取最新数据（按 id
```
api_read
```
表格），且就在写入前执行。保留获取到的
```
objectsColumns
```
和
```
streams
```
，它们可用作撤销依据。
写入数组，只应用你的更改。
立即验证：
- ```
api_read { "resource": "cubes", "method": "meta", "params": { "fields": "name", "pageSize": 100 } }
```
  必须成功。报错意味着组织的 model 已无法编译。立即恢复保存的数组，然后告知用户。
- 通过你修改过的 columns 查询表格的 view：
```
api_read { "resource": "cubes", "method": "query", "body": { "query": { "dimensions": ["<view>.<column name>"], "limit": 3 } } }
```
  。该 view 名为
```
model_<table id with - replaced by _>
```
  ，其 members 为列名称。报错会指出错误的 member。
回读表格，检查 columns 是否符合预期。

Reading a table

读取表格

get

the table and describe it in the user's terms:

what one row is (the root cube);
each column, with its display name, type, and where its value comes from (
```
cube.member
```
, stored in RevOS, or an action);
which segment or filter scopes the default view (
```
views[].segmentId
```
/
```
filter
```
);
whether the table is scored (
```
scoringFeatures
```
).

Don't dump the JSON. For the table's actual rows or aggregates, query its view or the underlying cubes (see query-semantic-model).

get

表格并用用户的语言描述它：

一行代表什么（root cube）；
每一列的显示名称、类型，以及值的来源（
```
cube.member
```
、存储在 RevOS 中或来自 action）；
默认 view 使用哪个 segment 或 filter 进行范围限定（
```
views[].segmentId
```
/
```
filter
```
）；
表格是否已评分（
```
scoringFeatures
```
）。

不要直接转储 JSON。若要获取表格的实际行或 aggregate，请查询其 view 或底层 cubes（见 query-semantic-model）。

Creating and editing

创建和编辑

Read the reference before writing:

New table: references/create.md
Change a table (add, change, remove, or hide columns; add a related cube; rename; scope its rows): references/edit.md
Column and stream rules (types, naming,
```
path
```
,
```
measure
```
, action columns, join paths): references/columns.md

The cubes behind a table are a separate thing. If the member a column needs doesn't exist yet, it has to be added to the cube first (the cubes skill). Audiences are a separate thing too: build a segment with the segments skill, then attach it here.

写入前请阅读参考文档：

新表格：references/create.md
修改表格（添加、修改、移除或隐藏 columns；添加相关 cube；重命名；限定行范围）：references/edit.md
Column 和 stream 规则（类型、命名、
```
path
```
、
```
measure
```
、action columns、join paths）：references/columns.md

表格背后的 cube 是另一回事。如果列所需的 member 尚不存在，必须先通过 cubes skill 将其添加到 cube 中。Audience 也是独立的：先使用 segments skill 构建 segment，然后在此处附加。

Deleting

删除

Tables can't be deleted through these tools, on purpose. Dropping a scoring model takes its stored values, scores, and action results with it. If the user wants a table gone, tell them to delete it in the RevOS UI. Don't call

api_delete

tables

; there is no such operation.

这些工具无法删除表格，这是有意为之。删除 scoring model 会同时移除其存储值、分数和 action 结果。如果用户希望移除表格，请告知他们在 RevOS UI 中删除。不要对

tables

调用

api_delete

；不存在此类操作。

Reporting back

回报结果

After a write, tell the user:

what changed, in their terms ("added Industry, read from the company");
that the model compiled and the view returned rows;
any judgment call you made, such as the join path or the column type.

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

写入后，告诉用户：

用用户能理解的语言说明变更内容（例如“添加了 Industry，读取自 company”）；
说明 model 已成功编译，并且 view 返回了行；
说明所做的判断，例如 join path 或 column type 的选择。

如果不得不恢复数据，请坦率说明，并附上报错信息。