tables

表格

在 API 中称为评分模型（scoring model）的表格，是一组包含类型化 列的行：

• 行来自表格的根立方体：即第一个流的立方体，因此公司表格的每一行对应一条 crm_companies 记录。存储自身 id 列的表格则保存自身的行。
• 列分为三种：
  • 外部列：从立方体成员实时读取。列包含 streamId（所属立方体）和 path（所属成员）。
  • 存储列：保存在 RevOS 中的值，由用户输入或由操作写入。这类列无需流。
  • 操作列：对每一行运行集成操作并保存结果。
• 流列出表格读取的立方体：根立方体对应 { "id": "<cube name>" }，其他立方体则还包含从根立方体到该立方体的路径 joinPath。流不保存其他内容：立方体本身知道其数据来源。
• 视图是表格的布局。默认视图还通过关联的分段或临时筛选条件决定显示哪些行。

你可以通过 RevOS MCP 服务的通用工具访问表格：

调用	作用
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>" }	获取表格的视图
api_write { "resource": "table-views", "id": "<VIEW id>", "data": { … } }	更新视图：segmentId、filter、columns
api_delete { "resource": "tables", "id": "<table id>" }	永久删除表格（参见删除）

记录始终放在 data 下。放在其他键下的请求正文可能会被忽略，且不会报错。api_details({ resource: "tables", operation: "update" }) 是列和流结构的权威说明。没有单独的列端点：列通过表格的 objectsColumns 数组变更。

需要牢记的三件事

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

• 未提供的列会从表和每个视图中移除。
• 只更新 name 是安全的部分更新。
• 发送 objectsColumns 而不发送 streams，会保留已存储的 streams。
• 某个 stream 会随读取它的最后一列一起消失（根 stream 会保留），因此除非要添加 stream，否则通常不需要发送 streams。
• 服务会整理存储的数据：根 stream 上的路径会被移除；发送时未带 joinPath 的非根 stream 会被存储为 <root>.<id>。读取表以查看实际保留的内容。

2. 表会编译为组织的语义模型。 RevOS 会根据表的 streams 和外部列，为每张表生成一个 Cube view：model_<id, - → _>；此外，还会通过表自身的 cube（model_stream_<id, - → _>___local，参见 columns.md）生成其已存储的列和 scores。服务在保存时不会检查这些内容。以下任一问题都会导致组织中的所有表、segment 和查询失效，直到问题修复：

• stream 的 id 不是一个 cube；
• joinPath 中的某一跳不是已声明的 join；
• 外部列的 path 不是其 stream 所属 cube 的成员；
• 默认视图上的 DYNAMIC segment，其 filter 指定了不存在的成员，或其 cubes 指定了不存在的跳转：其条件和 join 路径会被编译进视图；
• STATIC segment 的根或 primaryKeyDimension 有误：其 segment_… cube 会基于它们执行 join。

3. 每个根记录占一行。来自“一对多” cube 的字段不适用。 在添加来自根 cube 以外任意 cube 的列之前，先查明每条根记录对应多少条该 cube 的记录。查看两个 cube 之间的 join，两侧都要看，因为声明可能在任意一侧：

找到的 join	根记录有……	来自该 cube 的维度列
root → other：many_to_one 或 one_to_one	一条	可以
other → root：one_to_many	一条	可以
root → other：one_to_many	多条	不要添加
other → root：many_to_one（例如 crm_deals → crm_companies）	多条	不要添加

公司表中的“交易阶段”属于最后一行：每家公司有多笔交易，因此没有单一阶段可显示，该列还会造成行重复或错乱。不要添加该列，即使加上说明也不行。 停下来告诉用户原因，然后提供适用的方案：

• 将该 cube 中的聚合添加为度量列（measure: true）：例如计数、求和，或“已赢交易”这类筛选计数；前提是该 cube 已有此类度量，或已添加此类度量（参见 cubes 技能）；
• 在以该 cube 为根的表（Deals 表）中使用同一字段；
• 通过 segment 筛选行（“有已赢交易的公司”）。

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

1. 读取最新数据（写入前立即按 id 调用 api_read 读取表）。保留读取到的 objectsColumns 和 streams，它们可用于撤销更改。
2. 写入仅应用了你的更改的数组。
3. 立即验证：
   • api_read { "resource": "cubes", "method": "meta", "params": { "fields": "name", "pageSize": 100 } } 必须成功。发生错误意味着组织的模型无法再编译。立即恢复已保存的数组，然后告知用户。
   • 查询表的视图，检查你修改的列： api_read { "resource": "cubes", "method": "query", "body": { "query": { "dimensions": ["<view>.<column name>"], "limit": 3 } } }。 视图名称为 model_<table id with - replaced by _>，其成员即为列名。measure: true 列是该视图的度量：应将它放在 measures 中，而不是 dimensions 中，否则 Cube 会拒绝本身有效的列。错误信息会指出有问题的成员。
4. 重新读取表，检查列是否符合预期。

读取表格

get 表格，并使用用户熟悉的术语进行说明：

• 一行代表什么（根立方体）；
• 每一列，包括其显示名称、类型，以及值的来源 （cube.member、存储在 RevOS 中，或来自某项操作）；
• 默认视图受哪个细分或筛选条件限定：表格的 get 已包含 views[]，其中每项都包含其 segment（类型和状态）， 因此不需要列出 table-views；
• 表格是否已评分（scoringFeatures）。

不要倾倒 JSON。若要查询表格的实际行或聚合数据，请查询其视图或底层立方体（参见 semantic-model）。

创建和编辑

写入前请先阅读参考文档：

• 新建表格：references/create.md
• 更改表格（添加、更改、移除或隐藏列；添加关联立方体；重命名；限定其行范围）：references/edit.md
• 列和流规则（类型、命名、path、measure、操作列、联接路径）：references/columns.md

表格背后的立方体是独立的内容。如果列所需的成员尚不存在，则必须先将其添加到立方体中（使用 cubes skill）。 受众也是独立的内容：使用 segments skill 创建细分，然后在此处关联它。

删除

在 tables 上调用 api_delete 会永久删除表。不会软删除，也无法撤销。以下内容都会随之删除：

• 存储的列值和操作结果；
• 操作运行历史和操作列的计划；
• 评分和变更历史；
• 表的视图、语义模型中的视图，以及表自身的数据立方体。

因此，切勿在推理过程中删除。调用前：

1. 读取该表，并向用户复述表的信息：一行代表什么、共有多少列、哪些是存储列或操作列，以及是否已评分。

2. 检查哪些内容读取该表的数据立方体：它的视图 model_<id, - → _>，以及如果它有存储列或评分，还有它自身的数据立方体 model_stream_<id, - → _>___local。在以下位置查找任一名称：

   • 其他表的 streams、ids 和 joinPath （fields: "id,name,streams"）；

   • 分段的 cubes 和 filter（列出完整记录：它们不在 fields 中）；

   • 已存储数据立方体的 joins（对 cubes 调用 api_read， fields: "name,definition"）。

   • measure 或 breakdown 中引用了 model_<id…> 的仪表板卡片 （dashboard-cards，fields: "id,dashboardId,title,measure,breakdown"）： 它们不会导致模型出错，但会显示为不可用——请告知用户。

   这也涵盖了视图：其他表的视图筛选器只能引用该表所连接的数据立方体中的成员，因此会出现在它的 streams 中。删除表后，你找到的任何引用都会导致编译失败，并连带使整个组织的模型无法使用（规则 2）。报告这些引用并停止操作：必须先与用户一起通过相应的技能进行修改。

3. 说明随表删除的内容（见上面的列表），并明确询问用户是否同意删除这张表。删除一张表的批准不适用于其他表。

4. 然后调用 api_delete，并确认 meta 仍可编译，且该表已从 list 中消失。删除操作会依次删除多个存储，并非原子操作：如果出错或超时，请在重试前读取列表，并告知用户表的当前状态。

5. 如果删除后 meta 编译失败，则无法恢复：表已经不存在。不要随意尝试修复。读取错误信息，其中会指出缺失的数据立方体或成员；查找仍引用它的内容（第 2 步中的位置），并告知用户需要修改什么。只有得到用户同意后才能修改。

读取该表的数据立方体和分段仍会保留，连接的系统也一样：删除表不会向这些系统写入任何内容。你在失败尝试中自行创建的表也不例外：请说明这一点，并在删除前征得用户同意。

任何写入操作（创建、更新、删除或更新视图）返回 403，都表示用户的角色无法修改表；需要 Member 权限。Viewer 可以读取。

这些工具无法访问：操作列计划（操作列自行运行的计划）。请引导用户前往 RevOS UI 处理。

反馈

写入后，告知用户：

• 改动了什么，用用户熟悉的说法说明（例如“添加了 Industry，数据读取自 company”）；
• 模型已编译，且视图已返回行；
• 你做出的任何判断，例如连接路径或列类型。

如果你需要恢复，也要明确说明，并附上错误信息。