cube-run-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Run a query against Cube

对Cube运行查询

This is the one skill that 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.

这是唯一一个跳出CLI的技能。

cube api

绑定到Cube的控制台API，无法访问部署的查询端点，因此查询需要两步CLI调用：获取URL和令牌，然后直接向部署发起请求。

Preflight

预检

bash

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.

bash

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

。请检查是否已安装，若缺失请告知用户。

Get the endpoint and a token

获取端点和令牌

bash

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.

bash

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

cube deployments token

会单独打印Cube API令牌；如果需要包装对象，可以添加

--json

参数。令牌包含调用用户的安全上下文，因此行级安全控制与UI中完全一致——此处查询返回的内容是该用户被允许查看的，而非全部数据。

Know what you can query first

先了解可查询内容

Do not guess member names. Ask the compiled model:

bash

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

Members are

Cube.member

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.

不要猜测成员名称。请查询编译后的模型：

bash

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

成员格式为

Cube.member

或

View.member

。Cube上存在但未在视图中暴露的维度无法通过该视图查询——

cube meta

会告诉你哪些是可查询的。

Run it

运行查询

bash

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

—

dimension

plus

granularity

(

day

week

month

/…) and

dateRange

, 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.

bash

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
```
，其中
```
dateRange
```
接受自然语言范围（如
```
"Last 30 days"
```
）或明确的日期数组（如
```
["2026-01-01","2026-06-30"]
```
）。

filters

——格式示例：

[{"member":"Orders.status","operator":"equals","values":["paid"]}]

。

```
order
```
、
```
limit
```
。

响应包含

data

和

annotation

，其中

annotation

存储每个成员的可读标题和格式。展示结果时请使用

annotation

——度量值的显示名称和单位都在这里。

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
data
array 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.

先报告数值，再说明推导方式：包括使用的度量值、时间范围、筛选条件。没有查询上下文的数值无法被验证。
空的
data
数组是有效结果，而非错误：请说明查询成功但未返回任何行；不要擅自改用其他查询并展示结果却不告知用户。
切勿填充未获取到的值：如果查询失败，请报告错误信息。

Verifying a model change

验证模型变更

The common case after

cube-build-model

: query the new measure on the dev branch before merging. Point the environment at the branch when getting meta, and query the deployment the same way — the token and URL are per-deployment, not per-branch.

cube-build-model

后的常见场景：在合并前查询开发分支上的新度量值。获取元数据时将环境指向该分支，然后以相同方式查询部署——令牌和URL是针对部署的，而非分支。

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
Query hangs	A large uncached query; report it rather than silently retrying

症状	原因
`deploymentUrl` 为null	部署从未完成构建；请检查 `cube deployments build-status`
加载端点返回401	令牌过期——令牌有效期很短，重新生成一个即可
`Member not found`	名称错误或未在该视图中暴露——重新检查 `cube meta` ，不要猜测变体
查询挂起	未缓存的大型查询；请报告此情况，不要静默重试