cube-run-query

对 Cube 执行查询

选择路径

下文中，Cube MCP 工具的写法为 cube:<tool>：它们来自此插件捆绑的 cube 服务。通过 Cube connector 使用时，相同的工具会使用 connector 的名称。

如果 Cube MCP 工具可用，请使用它们。 这些工具来自此插件的 cube 服务或 Cube connector——请查找 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 自带的 Agent。将其返回的 cubeChatUrl 提供给用户，以便他们继续在 Cube 中操作。
• 使用其他部署： 先调用 cube:listDeployments，然后传入其 deploymentId。
• 使用开发分支： 将相同的 branchName 传给 cube:searchDataModel 和 cube:runQuery，这样找到的成员就是查询可见的成员。
• 超过 100 行： 使用 offset 对 cube:runQuery 分页，直到 hasMore 为 false。

当 MCP 工具未连接时，或在脚本或 CI 作业中，请使用下方的 CLI 路径。解读结果适用于这两种路径。

CLI 路径

CLI 之外的查询步骤。cube api 绑定到 Cube 的控制台 API，无法访问部署的查询端点，因此查询需要先通过两次 CLI 调用获取 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 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——其中包含度量的显示名称和单位。

解读结果

• 先报告数值，再说明它的计算依据。 包括使用了哪个度量、哪个范围和哪些筛选条件。没有对应查询的数值无法核验。
• 空的 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"}	查询仍在运行——重复发送相同请求，直到返回数据。如果持续一两分钟以上，请告知用户