cube-run-query

Cube に対してクエリを実行する

方法を選ぶ

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

Cube MCP ツールが利用できる場合は、それを使用してください。 このプラグインの cube サーバーまたは Cube コネクターから提供されます。cube:searchDataModel、cube:runQuery、cube:chat を探してください。インストールやログインの手順は不要で、すべての呼び出しはサインイン中のユーザーとして実行されるため、行レベルセキュリティが UI とまったく同じように適用されます。

• 特定の数値を調べる場合： cube:searchDataModel でビューと正確なメンバー名を見つけてから、Cube SQL を使って cube:runQuery を実行します — SELECT status, MEASURE(count) FROM orders_view GROUP BY 1。メンバー名を推測しないでください。
• 自由形式の質問の場合（「3月に登録者が減ったのはなぜか」など）：cube:chat を使用します。Cube 独自のエージェントが、ガバナンスが適用されたモデルと既存のレポートを使って実行します。返された cubeChatUrl をユーザーに伝えると、Cube で調査を続けられます。
• 別のデプロイの場合： cube:listDeployments を実行し、返された deploymentId を渡します。
• 開発ブランチの場合： 同じ branchName を cube:searchDataModel と cube:runQuery に渡します。これにより、見つけたメンバーがクエリでも使用されます。
• 100 行を超える場合： hasMore が false になるまで、offset を指定して cube:runQuery のページを取得します。

MCP ツールが接続されていない場合や、スクリプトまたは CI ジョブでは、以下の CLI 方法を使用してください。結果の解釈は、どちらの方法にも適用されます。

CLI を使う方法

CLI 以外でクエリを実行する手順です。cube api は Cube のコンソール API に紐付いており、デプロイのクエリエンドポイントにはアクセスできません。そのため、クエリには CLI を 2 回実行して URL とトークンを取得し、その後デプロイに直接リクエストを送る必要があります。

事前確認

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

このプラグインの他のすべてのスキルとは異なり、ここでは jq と curl も必要です。これらがあるか確認し、見つからない場合はその旨を伝えてください。

エンドポイントとトークンを取得する

DEPLOYMENT=<id>
URL=$(cube deployments get "$DEPLOYMENT" --json | jq -r .deploymentUrl)
TOKEN=$(cube deployments token "$DEPLOYMENT")

cube deployments token は Cube API トークンのみを出力します。ラッパーオブジェクトも必要な場合は --json を追加してください。このトークンには呼び出し元ユーザーのセキュリティコンテキストが含まれるため、行レベルセキュリティは UI とまったく同じように適用されます。つまり、ここでのクエリが返すのはすべてのデータではなく、そのユーザーに表示が許可されているデータです。

まずクエリ可能な内容を確認する

メンバー名を推測しないでください。コンパイル済みモデルを確認してください。

cube meta --selectors '[{"type":"cube","deploymentId":'"$DEPLOYMENT"',"environment":"production"}]'

メンバーは Cube.member または View.member の形式です。Cube に存在していてもビューに公開されていないディメンションは、そのビュー経由ではクエリできません。どちらに該当するかは cube meta で確認できます。

クエリを実行する

curl -s "$URL/cubejs-api/v1/load" \
  -H "Authorization: $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query":{
        "measures":["Orders.count","Orders.totalRevenue"],
        "dimensions":["Orders.status"],
        "timeDimensions":[{"dimension":"Orders.createdAt","granularity":"month","dateRange":"Last 6 months"}],
        "limit":100
      }}' | jq

通常必要となる順に、クエリの構造を示します。

• measures — 数値です。必ず完全修飾名を使用してください。
• dimensions — 内訳に使う項目です。
• timeDimensions — dimension に加え、granularity（day／week／month／…）と dateRange を指定します。"Last 30 days" のような自然言語の範囲や、["2026-01-01","2026-06-30"] のような明示的な範囲を指定できます。
• filters — [{"member":"Orders.status","operator":"equals","values":["paid"]}]。
• order、limit。

レスポンスには data と annotation が含まれます。annotation には各メンバーの表示用タイトルと形式が格納されています。結果を提示する際は annotation を使用してください。メジャーの表示名と単位はここに格納されています。

結果の解釈

• 数値を報告してから、その算出方法を説明します。 使用したメジャー、期間、フィルターを示してください。クエリがわからなければ、数値を検証できません。
• data 配列が空でも、それは結果でありエラーではありません。 クエリが成功し、行が返されなかったと伝えてください。別のクエリで再試行し、変更したことを伝えずにその結果を提示してはいけません。
• 受け取っていない値を補ってはいけません。 クエリが失敗した場合は、エラーを報告してください。

モデル変更の検証

cube-build-model の後によくあるケースは、マージ前に dev ブランチで新しいメジャーをクエリすることです。MCP 経由では、dev の branchName を cube:searchDataModel と cube:runQuery に渡します。CLI では、$URL/cubejs-api/v1/load は常に本番環境から応答します。dev ブランチには、同じデプロイ URL 配下に専用のエンドポイントがあり、 同じトークンを使用します。

cube deployments build-status "$DEPLOYMENT" --branch <dev-branch> --wait
curl -s "$URL/dev-mode/<dev-branch>/cubejs-api/v1/load" -H "Authorization: $TOKEN" ...

同じ方法で cube meta の対象をブランチに指定し、"environment":"<dev-branch>" を設定します。

問題が発生した場合

症状	原因
deploymentUrl が null	デプロイでビルドが一度も完了していません。cube deployments build-status を確認してください
load エンドポイントから 401 が返る	トークンの有効期限が切れています。トークンの有効期間は短いため、新しいものを発行してください
Member not found	名前が間違っているか、そのビューで公開されていません。cube meta を再確認し、別の候補を推測しないでください
{"error":"Continue wait"}	クエリはまだ実行中です。データが返るまで同じリクエストを再送してください。1〜2 分を過ぎても続く場合は、ユーザーに伝えてください