cube-build-model

Cube セマンティックモデルの構築と変更

状態を書き込みます。API は開発モードのブランチ以外へのファイル書き込みを拒否するため、以下のブランチ操作は省略できません。省略すると、すべての書き込みが失敗します。

パスを選択する

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

Cube MCP ツールを利用できる場合（このプラグインの cube サーバーまたは Cube コネクター）は、それらを使ってください。手順は次のとおりです。

1. cube:startDataModelEdit — 開発用の branchName が返されます。以下のすべての呼び出しにこの値を渡し、再利用してください。これを再度呼び出すと、新しい編集セッションが開始されます。
2. cube:listDataModelFiles、cube:readDataModelFile — 書き込む前に読み取ります。
3. cube:writeDataModelFile — ファイル全体を置き換えます。再コンパイルされ、valid と validationError（存在する場合）が返されます。有効になるまで修正して再度書き込みます。
4. cube:getDataModelChanges — 差分を確認します。
5. 同じ branchName を指定して cube:searchDataModel と cube:runQuery を実行し、新しいメンバーが公開され、正しい数値が返されることを確認します。
6. cube:commitDataModelChanges — これを実行するまで、ほかのユーザーは作業内容を確認できません。報告されたブランチ名を伝え、cube:switchUserBranch を案内してください。
7. cube:mergeToDefaultBranch — ユーザーが公開を明示的に依頼した場合に限り実行します。変更を全員が利用できる状態にします。

新しい事前集計を作成する場合は、cube:getPreAggregationStatus で確認してから、開発用の branchName を渡して、そのロールアップに対して cube:buildPreAggregation を実行します。ビルドでは、ウェアハウスに対して実際のクエリが実行されます。

MCP ツールが接続されていない場合、またはローカルプロジェクト全体を cube deploy でデプロイする場合は、CLI のパスを使ってください。事前に読み取る手順と規約は、どちらのパスにも適用されます。

事前確認（CLI）

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   # confirm the tenant before writing anything

書き込む前に読み取る

想定に基づいてモデルを作成しないでください。まず現在の状態を取得します。MCP では cube:listDataModelFiles と cube:readDataModelFile を使い、CLI では次のようにします。

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

プロジェクトに既存の規約（ファイルの配置、命名、メジャーをキューブとビューのどちらに置くか、結合の宣言方法など）を合わせてください。正しくても、周囲のモデルとまったく異なるキューブは、望ましい変更ではありません。

開発モードのワークフロー

# 1. See what branches exist, and which one is the deploy branch
cube data-model branches <deployment>

# 2. Create a feature branch to work on
cube data-model create-branch <deployment> <feature-branch>

# 3. Enter dev mode on the feature branch. This forks a personal `dev-…`
#    branch and PRINTS ITS NAME. Capture it — writes must target it.
cube data-model dev-mode <deployment> <feature-branch>

# 4. Write files to the dev branch
cube data-model put <deployment> model/cubes/orders.yml --file ./orders.yml --branch <dev-branch>
cube data-model put <deployment> model/views/revenue.yml --content - --branch <dev-branch>   # stdin

# 5. Validate the uncommitted working copy; fix and repeat until it passes
cube validate <deployment> --dev-mode

# 6. Commit — this lands on <feature-branch>, not production
cube data-model commit <deployment> -m "Add revenue view" --branch <dev-branch>

# 7. Wait for the build; exits non-zero if it fails
cube deployments build-status <deployment> --branch <dev-branch> --wait

# 8. Leave dev mode when done
cube data-model exit-dev-mode <deployment>

デプロイブランチで直接開発モードに入らないでください。 commit は開発モードの分岐元のブランチにプッシュするため、デプロイブランチから作成した開発ブランチは、そのまま本番環境にコミットされます。手順 2 によって、変更をレビュー可能な状態に保てます。

公開は別の手順です。ユーザーが明示的に依頼した場合に限り実行してください。

cube data-model merge-to-default <deployment> --branch <feature-branch> -m "Add revenue view"

デプロイブランチにマージされ、全員が利用できる状態になります。また、--keep-branch を指定しない限り、フィーチャーブランチは削除されます。

--branch のデフォルトは、現在の開発モードブランチです。そのため、通常は手順 3 の実行後に省略できます。それでも、1 つのセッションで複数のデプロイメントを扱う場合は、明示的に指定してください。デフォルトはコマンドごとではなくユーザーごとに設定されるため、誤った場所に書き込むおそれがあります。

ほかのファイル操作にも、同じブランチ規則が適用されます。

cube data-model rename <deployment> model/cubes/old.yml model/cubes/new.yml --branch <dev-branch>
cube data-model delete <deployment> model/cubes/dead.yml --branch <dev-branch>

コミット前に検証する（CLI）

cube validate <deployment> --dev-mode            # your uncommitted working copy
cube validate <deployment> --branch <branch>     # any named branch

そのブランチ専用のランタイムでモデルをコンパイルし、ファイルごとにエラーを一覧表示して、ゼロ以外の終了コードを返します。原因を推測せず、エラーをそのまま報告してください。Cube のモデルエラーには、ファイル名とメンバー名が記載されています。コミット後は、cube deployments build-status --wait の結果でビルドの状態を最終確認します。

ビルドが成功したら、変更に実際にクエリできることを確認します。メジャーのコンパイルが成功しても、どのビューにも公開されていない場合があります。

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

次に cube-run-query に引き継ぎ、数値が正しいことを確認します。コンパイルが成功しても、正しいとは限りません。SQL に誤りがあるメジャーでも、問題なくビルドされます。

ローカルプロジェクトを代わりにデプロイする

ユーザーがファイルごとの編集ではなく、プロジェクトをディスク上に持っている場合：

cube deploy <deployment> -m "<message>"   # uploads the local directory and builds

これは上記の開発モードとは異なるワークフローです。ローカルファイルでプロジェクトを置き換えます。開発モードのブランチがアクティブな場合はそのブランチに、そうでない場合はデプロイブランチにデプロイされます。また、--keep-missing を渡さない限り、ローカルディレクトリにないリモートファイルは削除されます。実行する前に、どのブランチに反映されるかを伝えてください。また、説明なしに1つのタスクで2つのワークフローを混在させないでください。

慣例

• キューブは物理レイヤーであり、ビューはユーザーがクエリする対象です。新しいビジネスメトリクスは通常、ビューに配置するか、キューブに配置してからビューを通じて公開します。
• 1ファイルにつきキューブは1つとし、キューブ名をファイル名にします。
• sql 式を書く際は、ユーザー自身の定義を引用してください。「収益には返金を含めない」と言われた場合、その定義はチャットだけでなく、SQL と description にも含めてください。

失敗した場合

症状	原因
書き込みが拒否される	開発モードのブランチではありません。cube data-model dev-mode を実行し、表示されたブランチを使用してください
validate が失敗する	モデルに実際のエラーがあります。指定されたファイルを修正し、コミットする前に再度検証してください
not logged in	事前チェックを再実行してください。書き込みを再試行しないでください
コミット後にビルドが失敗する	モデルに実際のエラーがあります。ビルドステータスの出力を確認し、指定されたファイルを修正してください
変更はビルドされるがクエリできない	ビューで公開されていません。cube meta を確認してください