cubes

Cubes

キューブは、組織のセマンティックモデルに保存されている定義の1つです。読み取るデータウェアハウステーブル（sql_table）、グループ化やフィルタリングに使うディメンション、集計するメジャー、ほかのキューブとの結合を定義します。テーブル、セグメント、セマンティックモデルのすべてのクエリは、これらを基盤に構築されます。

これらには、cubes リソース上の RevOS MCP サーバーの汎用ツールを通じてアクセスします。

呼び出し	内容
api_read { "resource": "cubes", "params": { "fields": "id,name,updatedAt" } }	保存されている定義を一覧表示します
api_read { "resource": "cubes", "id": "<cube id>" }	definition の下にある、1つの保存済み定義を取得します
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 の下に配置します。ほかのキーの下にある本文は、エラーにならず無視される場合があります。定義の JSON スキーマについては、api_details({ resource: "cubes", operation: "create" }) が正式な情報源です。

覚えておくべきこと

サーバーが検証するのは定義の形式であり、コンパイル可能かどうかではありません。また、Cube は組織内のすべてのキューブをまとめてコンパイルします。 不明なディメンション、メジャー、結合のキーは、名前付きエラーで拒否されます。一方、定義のトップレベルにある不明なキー（sql_table に対する sqlTable など）は、黙って破棄されるため、キューブにソースがなくなる場合があります。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 が返された場合、接続中のユーザーにそのロールがないことを意味するため、再試行せず、その旨を伝えてください。

最初に書き込む前の2つの確認

保存されずに生成されるものは何ですか？ meta には、保存されているキューブと RevOS が生成するものが表示されます。RevOS は、保存済みの列またはスコアがあるテーブルごとに1つのキューブ（model_stream_…___local、タイトルは [Table] <name>）、静的セグメントごとに1つ（segment_…、[Segment] <name>）、テーブルごとに1つのビュー（model_…）を生成します。これらは保存済みキューブにも結合を追加するため、meta のキューブの joins には、保存済みの定義にはない結合が含まれることがあります。保存済みキューブがない組織にも、生成されたキューブは表示されます。キューブを作成すると生成済みのものに追加され、既存のものは削除されません。

キューブはコードとして管理されていますか？ 一部の組織では、リポジトリから RevOS CLI（revos apply）を使ってキューブを配布しています。ここで行った編集は、次回の apply で上書きされます。ユーザーがリポジトリや CLI について言及した場合は、そちらを案内してください。

読み取り

• 何が、どのように定義されているか：fields: "id,name,updatedAt" を指定して一覧表示し、id を指定して get を実行すると、完全な definition を取得できます。一覧の filter は name に対する CEL です（name == "crm_deals"、name.startsWith("hubspot_")）。
• 実際にクエリ可能なもの：meta。保存済みの一覧とは異なります。
  • コンパイル済みです。メンバーは crm_deals.amount のように完全修飾され、キーには camelCase が使われます。
  • RevOS が自動生成するキューブも追加されます。これらを手動で記述することはありません。
    • 保存済みの列またはスコアがあるテーブルごとに1つのキューブ。名前は model_stream_…___local です（キューブだけを読み取るテーブルにはありません）。
    • 静的セグメントごとに1つのキューブ。名前は segment_… です。
    • テーブルごとに1つのビュー。

ユーザーがキューブの定義について尋ねた場合は、保存済み定義の関連部分（テーブル、型を含むディメンション、メジャー、結合）を示し、平易な言葉で説明してください。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 ごとに get を実行します。それぞれに 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

変更内容の報告

書き込み後、次の内容を2〜3文でユーザーに伝えます。

• 何を変更したかを、ユーザーの用語で説明します（「Dealsに合計メジャーとしてAmountを追加しました」など）。
• meta がコンパイルされ、テストクエリが実行されたこと。
• 結合のリレーションシップやディメンションの型など、判断した内容があれば伝えます。

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