tables

テーブル

API ではスコアリングモデルと呼ばれるテーブルは、型付きの列を持つ行の集合です。

• 行はテーブルのルートキューブ、つまり最初のストリームのキューブから取得されます。そのため、企業テーブルには crm_companies レコードごとに 1 行あります。独自の id 列を格納するテーブルは、代わりに独自の行を保持します。
• 列には次の 3 種類があります。
  • 外部：キューブのメンバーからリアルタイムで読み取ります。この列には、どのキューブかを示す 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>" }	1 つのテーブルを取得します：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 配列を通じて変更します。

覚えておくべき3つのこと

1. objectsColumns と streams は全体が置き換えられます。 更新では、保存済みの配列ではなく、送信した配列が保存されます。

• 省略した列はテーブルとすべてのビューから削除されます。
• name だけなら安全に部分更新できます。
• streams を指定せずに objectsColumns を送信すると、保存済みのストリームが維持されます。
• ストリームは、それを読み取る最後の列とともに自動的に消えるため（ルートは残ります）、通常は追加するとき以外に streams を送信する必要はありません。
• サーバーは保存時に内容を整えます。ルート上のパスは削除され、joinPath を指定せずに送信された非ルートストリームは <root>.<id> として保存されます。テーブルを読み戻して、何が保持されたか確認してください。

2. テーブルは組織のセマンティックモデルにコンパイルされます。 RevOS は各テーブルについて、ストリームと外部列に加え、保存済みの列と scores をテーブル独自の Cube（model_stream_<id, - → _>___local。columns.md を参照）経由で使用し、Cube ビュー model_<id, - → _> を生成します。サーバーは保存時にこれらを検証しません。次のいずれかがあると、修正されるまで組織内のすべてのテーブル、セグメント、クエリが機能しなくなります。

• Cube ではないストリームの id。
• 宣言されていない結合を指定する joinPath の経路。
• path がストリームの Cube のメンバーではない外部列。
• デフォルトビュー上の DYNAMIC セグメントで、フィルターが存在しないメンバーを指定している、または cubes が存在しない経路を指定している場合。条件と結合パスはビューにコンパイルされます。
• ルートまたは primaryKeyDimension が誤っている STATIC セグメント。その segment_… Cube はそれらを使って結合します。

3. ルートレコードごとに1行です。「many」側の Cube のフィールドは適合しません。 ルート以外の Cube から列を追加する前に、各ルートレコードにその Cube のレコードがいくつあるか確認してください。2つの Cube 間の結合を、両側から確認してください。どちら側で宣言されているかはわかりません。

見つかった結合	ルート側の件数…	その Cube のディメンション列
root → other: many_to_one または one_to_one	1件	問題ありません
other → root: one_to_many	1件	問題ありません
root → other: one_to_many	複数	追加しないでください
other → root: many_to_one（例：crm_deals → crm_companies）	複数	追加しないでください

会社テーブルの「商談ステージ」は、そのテーブルの最後の行になります。各会社には複数の商談があるため、表示できる単一のステージはなく、この列を追加すると行が重複したり、順序が乱れたりします。注意書きを添える場合でも追加しないでください。 そこで作業を止め、理由をユーザーに伝えてください。そのうえで、適切な代替案を提示します。

• その Cube の集計をメジャー列（measure: true）として使います。Cube に存在する、または追加する集計（cubes スキル）を使って、件数、合計、または「成約した商談」のような条件付き件数を指定できます。
• 同じフィールドを、その Cube をルートとするテーブル（商談テーブル）で使います。
• セグメントを使って行を絞り込みます（「成約した商談がある会社」）。

したがって、書き込みはすべて次の手順で行います。

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 の列はビューのメジャーなので、dimensions ではなく measures に指定してください。そうしないと Cube は問題のない列も拒否します。エラーには問題のあるメンバーが示されます。
4. テーブルを読み戻し、列が意図したとおりになっているか確認します。

テーブルを読む

テーブルを get し、ユーザーの用語で説明します。

• 1 行が何を表すか（ルートキューブ）。
• 各列の表示名、型、値の取得元（cube.member、RevOS に保存された値、またはアクション）。
• デフォルトビューの範囲を指定するセグメントまたはフィルター。テーブルの get には、それぞれ segment（タイプとステータスを含む）を持つ views[] がすでに含まれているため、table-views の一覧は不要です。
• テーブルにスコアが付けられているかどうか（scoringFeatures）。

JSON をそのまま出力しないでください。テーブルの実際の行や集計については、そのビューまたは基盤となるキューブに問い合わせてください（semantic-model を参照）。

作成と編集

書き込む前に、リファレンスを読んでください。

• 新しいテーブル：references/create.md
• テーブルの変更（列の追加、変更、削除、非表示；関連キューブの追加；名前変更；行の範囲指定）：references/edit.md
• 列とストリームのルール（型、命名、path、measure、アクション列、結合パス）：references/columns.md

テーブルの基盤となるキューブは別のものです。列に必要なメンバーがまだ存在しない場合は、まずキューブに追加する必要があります（cubes スキル）。オーディエンスも別のものです。segments スキルでセグメントを作成してから、ここに関連付けてください。

削除

tables の api_delete は、テーブルを完全に削除します。ソフト削除ではなく、元に戻すこともできません。削除すると、次のものも失われます。

• 保存済みの列の値とアクションの実行結果。
• アクションの実行履歴と、アクション列のスケジュール。
• スコアと変更履歴。
• テーブルのビュー、セマンティックモデル内のビュー、テーブル独自のキューブ。

そのため、推論時に削除してはいけません。呼び出す前に、次の手順を行います。

1. テーブルを読み取り、ユーザーにその内容を確認します。行が何を表すか、列の数、保存列かアクション列か、スコアリング済みかを伝えます。

2. テーブルのキューブを参照しているものを確認します。ビュー model_<id, - → _> と、保存列またはスコアがある場合はテーブル独自のキューブ model_stream_<id, - → _>___local を確認します。次の場所で、どちらかの名前を探します。

   • 他のテーブルの streams、id、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. 削除に伴って失われるもの（上記の一覧）を伝え、このテーブルの削除について明示的な許可を求めます。1 つのテーブルの削除許可が、他のテーブルの削除に適用されることはありません。

4. その後、api_delete を実行し、meta が引き続きコンパイルできることと、list からテーブルがなくなっていることを確認します。削除では複数のストアが順番に削除され、アトミックではありません。エラーまたはタイムアウトが発生した場合は、再試行する前に list を読み取り、テーブルの状態をユーザーに伝えます。

5. 削除後に meta が失敗しても、復元する方法はありません。テーブルはすでに削除されています。手当たり次第に修正を試みてはいけません。エラーを読み取って、欠落しているキューブまたはメンバーを特定し、まだそれを参照している場所（手順 2 の場所）を確認して、何を変更する必要があるかをユーザーに伝えます。変更するのは、ユーザーの許可を得てからに限ります。

テーブルが読み取っていたキューブとセグメントは残り、接続されているシステムもそのままです。テーブルを削除しても、それらのシステムには何も書き戻されません。失敗した試行で自分が作成したテーブルも例外ではありません。そのことを伝え、削除する前に許可を求めます。

書き込み操作（作成、更新、削除、ビューの更新）のいずれかで 403 が発生した場合、ユーザーのロールではテーブルを変更できません。Member ロールが必要です。Viewer ロールでは読み取りが可能です。

これらのツールでは操作できない項目：アクション列のスケジュール（アクション列を単独で実行するタイミング）。該当する場合は、ユーザーに RevOS UI を案内してください。

結果の報告

書き込み後、ユーザーには次の内容を伝えます。

• 何を変更したか（ユーザーにとってわかりやすい言葉で、「Industry を追加し、会社から読み取りました」など）。
• モデルがコンパイルでき、ビューが行を返したこと。
• 結合パスや列の型など、判断を要した内容。

復元が必要だった場合は、発生したエラーとともに、その旨を明確に伝えます。