cube-run-query
Run queries against a Cube deployment's semantic layer and interpret the results — through the Cube MCP tools when they are connected, or the Cube CLI from a terminal. Use whenever someone wants numbers out of Cube — pull a metric, check a total, compare periods, verify that a measure returns what it should, sanity-check a model change. Triggers on "how many", "what's the total", "show me revenue by month", "did that measure work", "what's our MoM growth", "pull the numbers for", and any request to verify a model change against real data. To find out what is queryable first use cube-explore-model; to change the model use cube-build-model; to save a result as a report or dashboard use cube-build-content.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-01
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- cube-run-query
- license
- Apache-2.0
- description
- Run queries against a Cube deployment's semantic layer and interpret the results — through the Cube MCP tools when they are connected, or the Cube CLI from a terminal. Use whenever someone wants numbers out of Cube — pull a metric, check a total, compare periods, verify that a measure returns what it should, sanity-check a model change. Triggers on "how many", "what's the total", "show me revenue by month", "did that measure work", "what's our MoM growth", "pull the numbers for", and any request to verify a model change against real data. To find out what is queryable first use cube-explore-model; to change the model use cube-build-model; to save a result as a report or dashboard use cube-build-content.
- compatibility
- Needs the Cube MCP server (bundled in the Cube plugin, or the Cube connector) or the Cube CLI, and network access to Cube Cloud.
03 SKILL.md 正文
Run a query against Cube
Choose the path
Cube MCP tools are written cube:<tool> below: the cube server this plugin
bundles. Through the Cube connector, the same tools carry the connector's name.
If the Cube MCP tools are available, use them. They come from this
plugin's cube server or the Cube connector — look for cube:searchDataModel,
cube:runQuery and cube:chat. They need no install or login step, and every call runs
as the signed-in user, so row-level security applies exactly as in the UI.
- A specific number:
cube:searchDataModelto find the view and the exact member names, thencube:runQuerywith Cube SQL —SELECT status, MEASURE(count) FROM orders_view GROUP BY 1. Never guess a member name. - An open-ended question ("why did signups drop in March"):
cube:chat, which runs Cube's own agent over the governed model and existing reports. Give the user thecubeChatUrlit returns so they can continue in Cube. - Another deployment:
cube:listDeployments, then pass itsdeploymentId. - A dev branch: pass the same
branchNametocube:searchDataModelandcube:runQuery, so the members you find are the ones the query sees. - More than 100 rows: page
cube:runQuerywithoffsetuntilhasMoreis false.
Use the CLI path below when the MCP tools are not connected, or in a script or CI job. Interpreting results applies to both paths.
CLI path
Querying steps outside the CLI. cube api is bound to Cube's console API
and cannot reach a deployment's query endpoint, so querying is two CLI calls
to get a URL and a token, then a direct request to the deployment.
Preflight
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 and curl are also required here, unlike every other skill in this
plugin. Check for them and say so if they are missing.
Get the endpoint and a token
DEPLOYMENT=<id>
URL=$(cube deployments get "$DEPLOYMENT" --json | jq -r .deploymentUrl)
TOKEN=$(cube deployments token "$DEPLOYMENT")
cube deployments token prints the Cube API token on its own; add --json
if you want the wrapping object. The token carries the calling user's
security context, so row-level security applies exactly as it would in the
UI — a query here returns what that user is allowed to see, not everything.
Know what you can query first
Do not guess member names. Ask the compiled model:
cube meta --selectors '[{"type":"cube","deploymentId":'"$DEPLOYMENT"',"environment":"production"}]'
Members are Cube.member or View.member. A dimension that exists on a cube
but is not exposed in a view is not queryable through that view — cube meta
is what tells you which is which.
Run it
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
Query shape, in the order you usually need it:
measures— the numbers. Always fully qualified.dimensions— what to break down by.timeDimensions—dimensionplusgranularity(day/week/month/…) anddateRange, which accepts natural ranges like"Last 30 days"or an explicit["2026-01-01","2026-06-30"].filters—[{"member":"Orders.status","operator":"equals","values":["paid"]}].order,limit.
The response carries data plus annotation, which holds the human titles
and formats for each member. Use annotation when presenting results — it is
where a measure's display name and unit live.
Interpreting results
- Report the number, then how it was derived. Which measure, which range, which filters. A number without its query is not checkable.
- An empty
dataarray is a result, not an error. Say the query succeeded and returned no rows; do not retry with a different query and present that instead without saying you changed it. - Never fill in a value you did not receive. If the query failed, report the error.
Verifying a model change
The common case after cube-build-model: query the new measure on the dev
branch before merging. Over MCP, pass the dev branchName to
cube:searchDataModel and cube:runQuery. With the CLI, $URL/cubejs-api/v1/load
always answers from production; a dev branch has its own endpoint under the
same deployment URL, used with the same token:
cube deployments build-status "$DEPLOYMENT" --branch <dev-branch> --wait
curl -s "$URL/dev-mode/<dev-branch>/cubejs-api/v1/load" -H "Authorization: $TOKEN" ...
Point cube meta at the branch the same way, with "environment":"<dev-branch>".
When something fails
| Symptom | Cause |
|---|---|
deploymentUrl is null |
The deployment has never finished a build; check cube deployments build-status |
| 401 from the load endpoint | Token expired — they are short-lived, just mint another |
Member not found |
Wrong name or not exposed in that view — re-check cube meta, do not guess a variant |
{"error":"Continue wait"} |
The query is still running — send the same request again until data comes back. Tell the user if it keeps going past a minute or two |
04 同仓库更多 Skills
cube-explore-model
Search and inspect a Cube semantic model — cubes, views, measures, dimensions, joins, and the files they live in — through the Cube MCP tools or the Cube CLI. Use whenever someone wants to know what data is available in Cube, where a metric is defined, which cube a field belongs to, how two cubes join, or what a change would affect. Triggers on "what can I query", "what measures do we have", "where is revenue defined", "show me the data model", "what's in this deployment", "which cube has customer email", and impact questions like "what breaks if I rename this". Read the model with this skill before changing it. To edit the model use cube-build-model; to run a query and get numbers back use cube-run-query; to browse workbooks, dashboards and reports use cube-explore-content.
cube-explore-content
Find and inspect saved content in a Cube workspace — workbooks, dashboards, reports, folders and scheduled notifications — using the Cube CLI, or the Cube MCP tools for content you already have a link to. Use whenever someone wants to know what already exists rather than build something new: locate a dashboard, list reports, see what a report queries, find who a notification goes to, or check what saved content references a model field before renaming it. Triggers on "what dashboards do we have", "find the revenue report", "where is that workbook", "what's in this folder", "who gets this scheduled report", "is anything using this field". To create or edit content use cube-build-content; to inspect the semantic model itself use cube-explore-model.
cube-embed
Set up and debug Cube embedded analytics — embed sessions, embed tokens, embeddable dashboards and embed tenants — using the Cube CLI. Use whenever someone is shipping Cube analytics inside their own product: mint a session for an end user, enable a dashboard for embedding, set up multi-tenant isolation so each customer sees only their data, or debug why an embedded view is empty or unauthorized. Triggers on "embed this dashboard", "embedded analytics", "our customers need to see", "multi-tenant analytics", "the iframe is blank", "embed token", "sign the embed URL", "customer-facing dashboard". For internal access control use cube-admin; for the dashboards themselves use cube-build-content.
cube-deploy
Manage Cube deployments and their lifecycle — create deployments, deploy a project, check build status, manage environments and environment variables, connect a GitHub repo, and tail logs — using the Cube CLI. Use whenever someone wants to ship, configure or debug a deployment rather than change the model inside one. Triggers on "deploy this", "did the build pass", "why did the build fail", "set an environment variable", "create a deployment", "connect our repo", "show me the logs", "what regions are available", "the deployment is down". To change model files use cube-build-model; for users and access use cube-admin.
cube-configure-agent
Inspect and tune Cube's in-product AI agent — its rules, certified queries and Agent Skills — by authoring markdown in the semantic model, through the Cube MCP tools or the Cube CLI. Use whenever someone wants the Cube agent to answer better: teach it a business definition, stop it making a recurring mistake, certify a trusted query, capture a repeatable workflow as a skill, or find out why it answered the way it did. Triggers on "the agent keeps getting X wrong", "teach the agent that", "make the agent always", "add a certified query", "create an agent skill", "why did the agent say that", "what rules does the agent have". To change the underlying model use cube-build-model; to explore what is queryable use cube-explore-model.
cube-build-model
Author and change a Cube semantic model — add or edit cubes, views, measures, dimensions, joins and pre-aggregations in YAML — on a dev-mode branch through the Cube MCP tools or the Cube CLI, then commit and build. Use whenever someone wants to add a metric, define a measure or dimension, create a cube or view, join two cubes, fix a model error, rename a field, or expose a field to business users. Triggers on "add a metric", "define revenue", "create a view for", "expose this field", "join orders to customers", "fix the model", "add a pre-aggregation". Read the model first with cube-explore-model. To run a query against the result use cube-run-query; to deploy or check build status use cube-deploy.