cube-explore-model

Cube のセマンティックモデルを調べる

読み取り専用です。ここで状態が変わることはないため、dev-mode ブランチは必要ありません。 そのため、何をすればよいか分かる前でも、どの手順でも実行できます。

手順を選ぶ

以下では、Cube MCP ツールを cube:<tool> と表記します。このプラグインに バンドルされている cube サーバーです。Cube コネクター経由では、同じツールに コネクターの名前が付いています。

Cube MCP ツールを利用できる場合（このプラグインの cube サーバーまたは Cube コネクター）は、それらを使用してください。インストールもログインも不要です。

質問	MCP ツール
何をクエリできるか、どのビューにフィールドがあるか	cube:searchDataModel — コンパイル済みモデルを、意味に基づいて検索します。すべてを一覧表示するには query を省略します
どのファイルが存在するか、ファイルには何が書かれているか	cube:listDataModelFiles、cube:readDataModelFile
ブランチで何が変更されたか	cube:getBranchDiff
どのデプロイメントが存在するか	cube:listDeployments を実行し、その後 deploymentId を渡します

cube:searchDataModel は、以下の cube meta の役割を果たします。「利用可能か」 （「公開されているか」）に答え、ファイルは作成元（「どこに 記述されているか」）に答えます。この違いと影響分析のチェックリストは、どちらの 手順でも同じです。

MCP ツールが接続されていない場合、テキスト検索のためにすべてのファイルの内容を 1 回のリクエストで取得する必要がある場合、または file-hashes を使う場合は、CLI の手順を使用してください。

事前確認（CLI）

開始時に一度実行します。どちらかの確認に失敗した場合は、そこで中止して報告してください。認証情報を推測したり、デプロイメント ID を作り出したりしないでください。

command -v cube >/dev/null || echo "Cube CLI not installed: curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "Not authenticated. Interactive: cube login. Headless: set CUBE_API_URL + CUBE_API_KEY."
cube context list   # multi-tenant: confirm you are pointed at the right tenant

cube context list は、見た目以上に重要です。ステージング環境と 本番環境のコンテキストがあるユーザーは、どちらを指しているか明示しないことがあります。また、以下のすべてのコマンドで指定するデプロイメント ID は、テナント内でのみ一意です。

デプロイメントを選ぶ

データモデル関連のコマンドには、すべてデプロイメント ID が必要です。

cube deployments list            # table: ID, NAME, URL, STEP
cube deployments list --json     # when you need to filter programmatically

デプロイメントがちょうど 1 つの場合は、それを使用します。複数あるのにユーザーがどれを使うか指定していない場合は、確認してください。最小の ID を選んだものと決めつけないでください。

モデルの構成を把握する

まずファイルツリーを確認します。何かを読む前にプロジェクトの構成を把握できる、最も手軽な方法です。

cube data-model list <deployment>
cube data-model list <deployment> --branch <branch>   # a specific branch

Cube プロジェクトでは、一般にキューブとビューを分けて管理します。

model/
  cubes/       one file per cube — the physical layer, joined to tables
  views/       one file per view — the curated layer users query

ビジネスユーザーがクエリするべきなのはビューです。キューブはその基盤となる構成要素です。「何をクエリできますか」と聞かれた場合、通常の答えはすべてのキューブではなくビューです。

ファイルを読む

cube data-model get <deployment> model/cubes/orders.yml
cube data-model get <deployment> model/views/revenue.yml --branch <branch>

定義されている場所を探す

CLI にはサーバー側の検索機能がありません。基本となるのは、すべてのファイルの内容を 1 回のリクエストで取得し、ローカルで検索することです。

cube data-model list <deployment> --content --json > /tmp/model.json

次に、その JSON から目的のメジャー、ディメンション、または SQL フラグメントを検索します。リクエストは 1 回だけで、その後は何度でも検索できます。すべてのパスに対して cube data-model get を繰り返し実行しないでください。遅く、出力も煩雑になります。

次のような用途に適したツールです。

• 「revenue はどこで定義されていますか」→ メジャーを見つけ、そのファイルとキューブを報告します
• 「顧客のメールアドレスを持つキューブはどれですか」→ ディメンション名を検索します
• 「active_user は実際には何を意味しますか」→ メジャーの sql を読み、言い換えずに引用します

ファイルではなく、コンパイル済みモデルに問い合わせる

ファイルはソースです。実際にクエリできるのは、extends、結合、ビューへの公開が解決された後のコンパイル済みモデルです。「今、何をクエリできますか」という質問には、コンパイル済みモデルに問い合わせてください。

cube meta --selectors '[{"type":"cube","deploymentId":<id>,"environment":"production"}]'

• type は cube（セマンティックレイヤー）または d3（分析レイヤー）です。
• environment はブランチ名、またはデプロイ済みモデルの場合は production です。デフォルトを使用するには省略します。

作成に関する質問（「これはどこに記述されていますか」「何を変更すべきですか」）にはファイルを使います。利用可能性に関する質問（「公開されていますか」「このビューには実際にどのフィールドがありますか」）には cube meta を使います。キューブにフィールドが存在していても、どのビューにも含まれていないことがあります。ファイルだけではそのことは分かりませんが、cube meta なら分かります。

変更前の影響分析

名前の変更や削除によって何が壊れるか尋ねられた場合は、次の3つすべてを確認してください。最初の確認だけでは不十分です。

1. 直接参照。 --content ダンプを検索し、キューブやビューをまたいでフィールド名を確認します。対象には、結合、sql 式、ビューの includes が含まれます。
2. ビューへの公開。 cube:searchDataModel または cube meta で、そのフィールドがビューに表示されるか確認します。ビューに公開されているフィールドには、モデルだけでは確認できない下流の利用者がいます。
3. 保存済みコンテンツ。 レポートやワークブックでは、メンバーを名前で参照します。名前の変更を安全と判断する前に、cube-explore-content に引き継いで、保存済みコンテンツを確認してください。

3つのうちどれを確認したか、明確に伝えてください。「モデルファイルに直接参照はありませんが、保存済みレポートは確認していません」は有用な回答です。一方、その但し書きなしに「名前を変更しても安全です」と答えるのは適切ではありません。

ブランチ

cube data-model branches <deployment>
cube data-model file-hashes <deployment> --branch <branch>

file-hashes はサーバー側のコンテンツハッシュを返します。すべてのファイルを取得せずに、ブランチがデフォルトブランチから乖離しているかを確認する簡単な方法です。

規約

• 一覧表示コマンドは表を出力します。機械可読な出力にするには --json を追加してください。取得コマンドは常に JSON を出力します。
• 読み取りでは、デフォルトでデプロイのデフォルトブランチを使用します。ユーザーが作業中の内容について話している場合は、必ず --branch を指定してください。
• ファイルパスとキューブ名は、表示されたとおりに正確に伝えてください。orders.yml と Orders は別物であり、ユーザーには操作対象を正しく伝える必要があります。

問題が発生した場合

症状	原因
not logged in	認証情報を解決できませんでした。コマンドを再実行せず、事前確認をやり直してください
session expired — run cube login	更新トークンが無効です。ユーザーが再認証する必要があります
デプロイで 403	アカウントにそのデプロイへのアクセス権がありません。IDが間違っているわけではありません
ファイル一覧が空	実際にあり得る状態で、通常は未ビルドまたは新規作成されたデプロイを意味します。再試行せず、その旨を伝えてください

出力で確認していないキューブ、メジャー、ファイルパスを決して作り上げないでください。 ユーザーが尋ねている内容がモデルに含まれていない場合は、その旨を伝えてください。それ自体が確認結果であり、多くの場合、それが実際の答えです。