semantic-model

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Semantic Model

语义模型

Answer business questions by querying the org's live semantic model over the
RevOS
MCP server and rendering the result directly in the chat.
The MCP server exposes a small set of generic tools; the semantic model is reached through one of them,
api_read
, against the
cubes
resource:
CallWhat you get
api_read({ resource: "cubes", method: "meta", params: {…} })
the compiled semantic model — every cube/view with its measures, dimensions, segments and joins
api_read({ resource: "cubes", method: "query", body: { query: {…} } })
rows
api_details({ resource: "cubes", operation: "query" })
returns the exact schema the endpoint enforces, read from its own OpenAPI document. When something here disagrees with
api_details
,
api_details
is right — reach for it whenever a call is rejected and the reason isn't obvious.
There is also
api_read({ resource: "cubes" })
with no
method
, which lists the stored cube definitions — the YAML someone authored. That is a different question from "what can I query"; for answering business questions you want
meta
, always.
通过
RevOS
MCP 服务器查询组织的实时语义模型,并直接在聊天中呈现结果。
MCP 服务器公开了一小组通用工具;语义模型通过其中一个工具
api_read
访问目标资源
cubes
:
调用返回内容
api_read({ resource: "cubes", method: "meta", params: {…} })
已编译的语义模型——包含每个 cube/view 及其 measures、dimensions、segments 和 joins
api_read({ resource: "cubes", method: "query", body: { query: {…} } })
数据行
api_details({ resource: "cubes", operation: "query" })
返回 endpoint 强制执行的精确 schema,该信息直接读取自其自己的 OpenAPI document。如果此处的内容与
api_details
不一致,以
api_details
为准;当调用被拒绝且原因不明显时,应调用它核实。
还有一个不带
method
的
api_read({ resource: "cubes" })
,它会列出已存储的 cube definitions——即某人所编写的 YAML。这与“我可以查询什么”是不同的问题;回答业务问题时始终应使用
meta
。

Step 1: Discover what's queryable

第 1 步:发现可查询的内容

Before guessing member names, read the catalogue.
meta
is a list endpoint like any other, so project it down rather than pulling the whole document:
json
{
  "resource": "cubes",
  "method": "meta",
  "params": { "fields": "name,title,description", "pageSize": 100 }
}
That is the whole catalogue at a few kilobytes — cheap to read and choose from.
pageSize
defaults to 100 and goes up to 1000 for
meta
; if the response carries a
metadata.nextPageToken
, pass it back as
params.pageToken
for the rest.
The catalogue can surface internal, system-generated cubes alongside the business ones you'd expect — a helper cube backing a "latest scores" rollup, an internal segment cube, or similar plumbing that exists to support another cube's joins rather than to be queried directly. RevOS-generated ones are titled
[Table] …
or
[Segment] …
(names
model_stream_…___local
,
segment_…
), and views of tables are named
model_…
; others stand out by a sparse or missing description, or a mechanical-sounding name/title. When a search matches both a clean, business-named cube and one of these, describe and query the business one unless the question is specifically about the internal one.
Then pull the full definition of the cube(s) the question needs, by dropping
fields
and filtering to them:
json
{
  "resource": "cubes",
  "method": "meta",
  "params": { "filter": "name == \"gold_order_items_enriched\"" }
}
That returns the exact
measures
,
dimensions
(with time granularities where relevant),
segments
, and
joins
you can reference — always addressed as
<CubeName>.<member>
, e.g.
gold_order_items_enriched.count
or
gold_order_items_enriched.order_date
. See Step 2 for what
joins
gives you, and what it doesn't.
params.filter
is a CEL expression over
name
,
title
,
description
and
type
—
name.contains("invoice")
,
!name.endsWith("_local")
,
type == "view"
. Members are not filterable: you cannot search for a cube by the fields it carries, which is why the projected catalogue above is the way in.
If the user's question is purely about discovery — "what's in my semantic model", "what can I query", "list the cubes/datasets" — stop here: summarize the cubes (and their fields, if you pulled a full definition) in prose or a short table, and skip Steps 3–6. Don't run a query the user didn't ask for.
Never hardcode or guess a member name. If the question can't be answered from what
meta
returns, say so — don't invent a field.
Stay on the semantic model even when the question names a source system. A question like "how many distinct HubSpot owners have at least one contact" names HubSpot, but it's still an aggregate question — answer it from the semantic model (e.g. a
users
cube built from
gold_contacts
, already deduplicated and fully synced), not by reaching for a direct HubSpot/Zammad/Exact Online/other source connector, even if one is available and matches the question's wording better on a keyword search. A direct source connector typically paginates and returns a partial live snapshot rather than the full synced dataset — swapping to one mid-task can silently return an answer wrong by orders of magnitude, with no error surfaced, because the connector call itself succeeds fine; it's just not looking at the same data the semantic model would. Reserve a direct source connector for a point lookup of one already-identified record (e.g. "what's contact X's email", "who owns company Y in HubSpot") — never for a count, sum, or breakdown across the dataset.
在猜测 member 名称前,先读取 catalogue。
meta
和其他 list endpoint 一样,因此应通过字段投影缩减结果,而不是拉取整个 document:
json
{
  "resource": "cubes",
  "method": "meta",
  "params": { "fields": "name,title,description", "pageSize": 100 }
}
这是完整的 catalogue,只有几 KB——读取成本低且便于选择。
pageSize
默认为 100,
meta
最高可到 1000;如果 response 中带有
metadata.nextPageToken
,将其作为
params.pageToken
传回以获取后续页面。
catalogue 中可能同时出现内部、系统生成的 cube 和预期中的业务 cube——例如支撑“最新得分”汇总的 helper cube、内部 segment cube,或为支持其他 cube joins 而存在的 plumbing。RevOS 生成的 cube 标题为
[Table] …
或
[Segment] …
(名称为
model_stream_…___local
、
segment_…
),表的 views 名为
model_…
;其他 cube 通常会因 description 稀疏或缺失,或 name/title 听起来较为机械而显得突出。搜索同时匹配到命名清晰的业务 cube 和其中一种内部 cube 时,除非问题明确针对内部 cube,否则应描述并查询业务 cube。
随后,通过省略
fields
并筛选到所需 cube,拉取问题的完整 definition:
json
{
  "resource": "cubes",
  "method": "meta",
  "params": { "filter": "name == \\"gold_order_items_enriched\\"" }
}
这会返回可引用的精确
measures
、
dimensions
(相关维度还带 time granularities)、
segments
和
joins
——始终以
<CubeName>.<member>
形式寻址,例如
gold_order_items_enriched.count
或
gold_order_items_enriched.order_date
。第 2 步将说明
joins
能提供什么,以及不能提供什么。
params.filter
是针对
name
、
title
、
description
和
type
的 CEL expression——例如
name.contains("invoice")
、
!name.endsWith("_local")
、
type == "view"
。Members 不可筛选:无法根据 cube 携带的 fields 搜索 cube,因此应以上面的 projected catalogue 作为入口。
如果用户的问题纯粹关于发现——“我的语义模型里有什么”“我可以查询什么”“列出 cubes/datasets”——到这里就停止:用文字或简短表格总结 cubes(如果已拉取完整 definition,也总结其 fields),并跳过第 3–6 步。不要运行用户没有要求的 query。
绝不硬编码或猜测 member name。如果根据
meta
返回的内容无法回答问题,就直说——不要虚构 field。
即使问题指明源系统,也始终使用语义模型。
例如,“有多少个不同的 HubSpot owners 至少拥有一位 contact?”虽然提到了 HubSpot,但这仍是一个聚合问题——应从语义模型回答(例如使用由
gold_contacts
构建的
users
cube,它已经完成去重和全量同步),而不是改用直接的 HubSpot/Zammad/Exact Online 或其他 source connector,即使有可用的连接器,而且按关键词搜索时它看起来更符合问题的措辞。direct source connector 通常会进行分页并返回部分实时 snapshot,而不是完整的 synced dataset——任务进行到一半切换过去,可能会悄无声息地返回一个误差达数量级的答案,而且不会 surfaced error,因为 connector call 本身会成功;它只是没有查看与 semantic model 相同的数据。仅在对一个已识别记录进行点查时使用 direct source connector(例如“contact X 的 email 是什么”“HubSpot 中谁拥有 company Y”);绝不将其用于 dataset-wide 的 count、sum 或 breakdown。

Step 2: Crossing cubes — read
joins
, and know its two blind spots

第 2 步:跨 cube 查询——读取
joins
,并了解两个盲区

meta
returns a
joins
array per cube —
{ name, relationship, sql }
for every other cube it connects to. Read it before writing a query that spans more than one cube: if a question needs
gold_order_items_enriched
and
gold_users_with_order_stats
together, pull one of them and check whether the other shows up in its
joins
. Don't infer a relationship just because two cubes each happen to have a similarly-named "account id"-shaped column.
Two blind spots, and both will bite you if you trust
joins
as a complete picture:
Only outgoing joins are listed. A cube reports the joins it declares, not the ones other cubes declare pointing at it. Joins in this codebase are written one-directionally —
deals
declares a join to
customers
, but
customers
declares none back — while Cube's planner walks such a join from either side. So a dimension-style cube that everything joins to can report zero joins while being joinable from a dozen places. Never read an empty or short
joins
array as "this cube doesn't connect to anything": check the other cube's
joins
too before concluding there is no path.
A fabricated
joinHints
path is not rejected.
joinHints
pins the route when more than one path connects two cubes: a list of paths, each an ordered array of cube names to route through — two for a direct join, more for a multi-hop — e.g.
[["gold_order_items_enriched", "gold_users_with_order_stats"]]
or
[["orders", "line_items", "products"]]
. A pair in that path with no declared join behind it does not produce an error: Cube falls back to auto-resolving the real path, and you get an answer computed over a route you did not choose. That is harmless when only one real path exists — Cube ignores the bogus hint and gets it right anyway — and silently wrong the moment the schema has a genuine fork between two valid paths, because the fabricated hint doesn't reliably pin either one. The query succeeding is not evidence the path was real.
So: set
joinHints
only when every consecutive pair in it is an edge you actually saw in some cube's
joins
— having checked both directions, per the first blind spot. When more than one plausible route exists — two paths to the same field, or a fact table that could reach a dimension both directly and through a third cube — don't silently pick one. State the ambiguity plainly and ask the user to confirm the intended relationship or grain — e.g. "revenue per order item" vs. "revenue per user" — before running the query. Whenever you do set
joinHints
, say so in your explanation afterward — which path you used and why — so the user can catch a wrong assumption. Prefer the simplest single-cube answer whenever the question doesn't actually require crossing cubes at all.
每个 cube 的
meta
都会返回
joins
array——即它所连接的每个其他 cube,格式为
{ name, relationship, sql }
。在编写跨越多个 cube 的 query 前应先读取它:如果问题需要同时使用
gold_order_items_enriched
和
gold_users_with_order_stats
,应拉取其中之一,并检查另一个是否出现在它的
joins
中。不要仅因为两个 cube 恰好都有名称相似的“account id”形列,就推断两者存在 relationship。
有两个盲区;如果完全信任
joins
作为完整视图,两者都会导致误判:
只列出 outgoing joins。 cube 报告的是它自己声明的 joins,而不是其他 cube 声明并指向它的 joins。本 codebase 中的 joins 是单向编写的——
deals
声明了到
customers
的 join,而
customers
并未反向声明——但 Cube 的 planner 可以从任一方向遍历这种 join。因此,一个被所有对象 join 的 dimension-style cube 可能报告 零个 joins,却实际上可以从十几个位置连接。绝不把空的或很短的
joins
array 理解为“此 cube 不与任何对象连接”:得出不存在 path 的结论前,还要检查另一个 cube 的
joins
。
虚构的
joinHints
path 不会被拒绝。
当两个 cube 之间有多条 path 时,
joinHints
可以锁定 route:它是一个 path 列表,每个 path 都是由 cube 名称组成的有序 array——直接 join 为两个,多跳则更多——例如
[["gold_order_items_enriched", "gold_users_with_order_stats"]]
或
[["orders", "line_items", "products"]]
。path 中某个相邻 pair 没有 declared join 作为支撑,并不会产生 error:Cube 会 fallback 到自动解析真实 path,于是你得到的 answer 是基于一条并未由你选择的 route 计算的。当仅有一条真实 path 存在时,这通常无害——Cube 会忽略 bogus hint 并正确解析——但当 schema 中确实存在两条有效 path 形成的分叉时,结果会静默出错,因为虚构的 hint 无法可靠锁定其中任何一条。query 成功并不能证明 path 是真实的。
因此:只有当
joinHints
中每一对相邻 cube 都是你确实在某��� cube 的
joins
中见过的 edge 时,才能设置
joinHints
——并且需要按照第一个盲区的要求检查两个方向。当存在多条合理 route 时——例如通往同一 field 的两条 path,或某个 fact table 既能直接到达某个 dimension,也能经由第三个 cube 到达——不要悄悄选择其中一条。应明确说明歧义,并请用户确认预期的 relationship 或 grain——例如“每个 order item 的 revenue”与“每个 user 的 revenue”——然后再运行 query。每当你设置
joinHints
时,都应在后续说明中讲清使用了哪条 path 以及原因,方便用户发现错误假设。如果问题并不需要跨 cube,优先采用最简单的 single-cube 答案。

Step 3: Build the query

第 3 步:构建 query

The Cube.js query goes in
body.query
— note the nesting; the body is
{ "query": { … } }
, not the query object itself.
FieldShapeNotes
measures
string[]
quantities to aggregate, e.g.
gold_order_items_enriched.count
dimensions
string[]
attributes to group/break down by
segments
string[]
named filters from
meta
, layered on top like an extra filter
timeDimensions
[{ dimension, granularity?, dateRange? }]
see below
filters
see belowleaf conditions, optionally nested in
and
/
or
groups
order
[[member, dir], …]
or
{ member: dir }
either shape works — array of
[member, "asc"|"desc"]
pairs, or an object map
joinHints
[[cube, …], …]
pins an ambiguous join path — each entry is an ordered path of cube names (two or more), see Step 2
limit
number
see "Row limits" below
offset
number
for paging past
limit
timezone
IANA string, e.g.
Europe/Amsterdam
defaults to UTC
total
boolean
also returns the total matching row count, ignoring
limit
/
offset
— useful for "(showing 10 of 842)"
ungrouped
boolean
returns raw rows without aggregating by the dimensions, for inspecting individual records rather than summarizing — the row limit still applies
Keys not listed here are forwarded to Cube unchanged, so a Cube.js feature the API does not name is still reachable.
timeDimensions[].granularity
— usually one of
day
,
week
,
month
,
quarter
,
year
(Cube also takes
hour
/
minute
/
second
, and custom granularities a dimension defines). Omit it entirely for a single total across the whole range instead of a series.
timeDimensions[].dateRange
— a relative string (
"last quarter"
,
"last 12 months"
,
"this month"
) or an explicit
["2026-01-01", "2026-03-31"]
pair of ISO dates.
Period over period ("this month vs. last month") — run one query per range, each with its own
dateRange
, and compare them yourself. Avoid
compareDateRange
: the endpoint reads Cube's answer as one regular result, which a compare query isn't, so it's likely to fail with a bare 500.
filters
is a list of conditions, each one of:
  • A condition:
    { "member": "...", "operator": "...", "values": [...] }
    . Values are usually strings (
    ["100"]
    works fine even for numbers/dates), but numbers, booleans, and
    null
    are accepted too. Operators:
    equals
    ,
    notEquals
    ,
    in
    ,
    notIn
    ,
    contains
    ,
    notContains
    ,
    startsWith
    ,
    notStartsWith
    ,
    endsWith
    ,
    notEndsWith
    ,
    gt
    ,
    gte
    ,
    lt
    ,
    lte
    ,
    inDateRange
    ,
    notInDateRange
    ,
    onTheDate
    ,
    beforeDate
    ,
    beforeOrOnDate
    ,
    afterDate
    ,
    afterOrOnDate
    ,
    measureFilter
    .
    set
    /
    notSet
    check presence and take no
    values
    .
  • A group:
    { "and": [...] }
    or
    { "or": [...] }
    , where each entry is again a condition or a group (they can nest). Top-level entries in the
    filters
    array are implicitly AND-combined; reach for an explicit
    or
    group the moment a question needs "either of these" rather than "all of these" — mixing dimension and measure conditions inside the same
    and
    /
    or
    group isn't supported, keep those separate.
These are Cube's own filters, on
body.query.filters
, and they are forwarded to Cube rather than validated against a schema here — a malformed one comes back as Cube's error, not a neat parameter complaint. Don't confuse them with the
params.filter
CEL string from Step 1: that one filters the catalogue, this one filters the data.
Cube.js query 放在
body.query
中——注意嵌套层级;body 是
{ "query": { … } }
,而不是 query 对象本身。
字段形态说明
measures
string[]
要聚合的度量值,例如
gold_order_items_enriched.count
dimensions
string[]
用于分组或拆分的属性
segments
string[]
meta
中的命名 filters,像额外过滤条件一样叠加
timeDimensions
[{ dimension, granularity?, dateRange? }]
详见下文
filters
见下文叶子条件,可选择嵌套在
and
/
or
groups 中
order
[[member, dir], …]
或
{ member: dir }
两种形态都可用——
[member, "asc"|"desc"]
pairs 的 array,或 object map
joinHints
[[cube, …], …]
固定有歧义的 join path——每项都是 cube 名称组成的有序 path(至少两个),参见第 2 步
limit
number
参见下文“行数限制”
offset
number
用于翻页并越过
limit
timezone
IANA string,例如
Europe/Amsterdam
默认为 UTC
total
boolean
同时返回忽略
limit
/
offset
的匹配行总数,适合“(显示 10 条,共 842 条)”这类场景
ungrouped
boolean
返回未经 dimensions 聚合的原始行,用于检查单条记录而不是汇总;行数限制仍然适用
此处未列出的 keys 会原样转发给 Cube,因此即使 API 没有命名的 Cube.js feature 仍然可以使用。
timeDimensions[].granularity
——通常为
day
、
week
、
month
、
quarter
、
year
(Cube 也接受
hour
/
minute
/
second
,以及 dimension 定义的自定义 granularities)。如果需要整个时间范围内的单一 total,应完全省略它,而不是生成 series。
timeDimensions[].dateRange
——相对时间字符串(
"last quarter"
、
"last 12 months"
、
"this month"
),或一对明确的 ISO 日期(
["2026-01-01", "2026-03-31"]
)。
环比(“本月与上月相比”)——针对每个范围分别运行一个 query,为其设置各自的
dateRange
,然后自行比较。应避免使用
compareDateRange
:endpoint 会将 Cube 的结果当作一个普通 result 读取,而 compare query 并非这种结构,因此很可能只返回一个简单的 500 错误。
filters
是一个 conditions 列表,每一项可以是:
  • 一个 condition:
    { "member": "...", "operator": "...", "values": [...] }
    。Values 通常是 strings(即使目标为 numbers/dates,
    ["100"]
    也能正常工作),但也接受 numbers、booleans 和
    null
    。Operators 包括:
    equals
    、
    notEquals
    、
    in
    、
    notIn
    、
    contains
    、
    notContains
    、
    startsWith
    、
    notStartsWith
    、
    endsWith
    、
    notEndsWith
    、
    gt
    、
    gte
    、
    lt
    、
    lte
    、
    inDateRange
    、
    notInDateRange
    、
    onTheDate
    、
    beforeDate
    、
    beforeOrOnDate
    、
    afterDate
    、
    afterOrOnDate
    、
    measureFilter
    。
    set
    /
    notSet
    用于检查值是否存在,且不接受
    values
    。
  • 一个 group:
    { "and": [...] }
    或
    { "or": [...] }
    ,其中每一项又是一个 condition 或 group(可以嵌套)。
    filters
    array 的顶层各项默认以 AND 组合;一旦问题需要“满足其中之一”而不是“同时满足全部”,就应立即使用显式的
    or
    group——不支持在同一个
    and
    /
    or
    group 中混合 dimension conditions 和 measure conditions,应将它们分开。
这些是 Cube 自身的 filters,位于
body.query.filters
,会直接转发给 Cube,而不是在这里按 schema 验证——格式错误会返回 Cube 的 error,而不是整洁的参数错误提示。不要将它们与第 1 步中的
params.filter
CEL string 混淆:后者筛选的是 catalogue,前者筛选的是 data。

Row limits

行数限制

limit
is passed through to Cube, which applies its own default when the query names none and rejects anything above its configured maximum. Those defaults are sized for a data warehouse, not a chat window. Two consequences:
  • Always name the
    limit
    you actually want.
    An open-ended query with no
    limit
    can return thousands of rows straight into the conversation.
  • metadata.limit
    in the response is the authority
    — it reports the limit Cube actually applied, which is the number to quote when you say a result was truncated.
limit
会直接传给 Cube;当 query 未指定 limit 时,Cube 会应用自己的 default,并拒绝任何高于其 configured maximum 的值。这些 default 是为 data warehouse 设计的,而不是为聊天窗口设计的。由此产生两个影响:
  • 始终明确写出你实际需要的
    limit
    。
    没有
    limit
    的开放式 query 可能一次将数千行直接返回到对话中。
  • response 中的
    metadata.limit
    才是权威值
    ——它报告 Cube 实际应用的 limit;当你说明结果被截断时,应引用这个数字。

Examples

示例

Simplest possible:
json
{
  "resource": "cubes",
  "method": "query",
  "body": { "query": { "measures": ["gold_order_items_enriched.count"] } }
}
Top N by category:
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.count"],
      "dimensions": ["gold_order_items_enriched.traffic_source"],
      "order": [["gold_order_items_enriched.count", "desc"]],
      "limit": 10
    }
  }
}
Time series (the chart-friendliest shape):
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.revenue"],
      "timeDimensions": [
        {
          "dimension": "gold_order_items_enriched.order_date",
          "granularity": "month",
          "dateRange": "last 12 months"
        }
      ]
    }
  }
}
Filtered with OR logic ("either refunded or a test order"):
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.count"],
      "filters": [
        {
          "or": [
            { "member": "gold_order_items_enriched.is_refunded", "operator": "equals", "values": ["true"] },
            { "member": "gold_order_items_enriched.is_test_order", "operator": "equals", "values": ["true"] }
          ]
        }
      ]
    }
  }
}
Crossing cubes with a pinned join path (see Step 2):
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.revenue"],
      "dimensions": ["gold_users_with_order_stats.country"],
      "joinHints": [["gold_order_items_enriched", "gold_users_with_order_stats"]]
    }
  }
}
Rules of thumb:
  • One measure + one dimension → chart candidate by category.
  • One measure + one
    timeDimensions
    with
    granularity
    → chart candidate over time.
  • Multiple measures or multiple dimensions → table only; don't try to chart it.
  • Always set
    limit
    explicitly for "top N" questions (
    limit: N
    + matching
    order
    ), and never rely on the default for an open-ended pull.
最简单的 query:
json
{
  "resource": "cubes",
  "method": "query",
  "body": { "query": { "measures": ["gold_order_items_enriched.count"] } }
}
按 category 查询前 N 名:
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.count"],
      "dimensions": ["gold_order_items_enriched.traffic_source"],
      "order": [["gold_order_items_enriched.count", "desc"]],
      "limit": 10
    }
  }
}
时间序列(最适合 chart 的形态):
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.revenue"],
      "timeDimensions": [
        {
          "dimension": "gold_order_items_enriched.order_date",
          "granularity": "month",
          "dateRange": "last 12 months"
        }
      ]
    }
  }
}
使用 OR 逻辑筛选(“已退款或测试订单”):
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.count"],
      "filters": [
        {
          "or": [
            { "member": "gold_order_items_enriched.is_refunded", "operator": "equals", "values": ["true"] },
            { "member": "gold_order_items_enriched.is_test_order", "operator": "equals", "values": ["true"] }
          ]
        }
      ]
    }
  }
}
跨 cube 查询并固定 join path(参见第 2 步):
json
{
  "resource": "cubes",
  "method": "query",
  "body": {
    "query": {
      "measures": ["gold_order_items_enriched.revenue"],
      "dimensions": ["gold_users_with_order_stats.country"],
      "joinHints": [["gold_order_items_enriched", "gold_users_with_order_stats"]]
    }
  }
}
经验法则:
  • 一个 measure 加一个 dimension → 可生成按 category 展示的 chart。
  • 一个 measure 加一个带
    granularity
    的
    timeDimensions
    → 可生成时间序列 chart。
  • 多个 measures 或多个 dimensions → 仅使用 table;不要尝试生成 chart。
  • 对“前 N 名”问题,始终显式设置
    limit
    (
    limit: N
    并配上匹配的
    order
    ),绝不能依赖默认值执行开放式拉取。

Step 4: Run the query and read the response

第 4 步:运行 query 并读取 response

The response is
{ data, metadata }
:
  • data
    — the array of rows, each a flat object keyed by the same member names used in the query.
  • metadata.rowCount
    — how many rows came back.
  • metadata.limit
    /
    metadata.offset
    — what Cube actually applied.
  • metadata.total
    — present only if the query set
    total: true
    . It is the count of matching rows ignoring limit and offset, so
    offset + rowCount < total
    is how you tell there is another page. Without it, a page that fills exactly is indistinguishable from one ending on the last row — so set
    total: true
    whenever you intend to say "showing 10 of N" or to offer paging.
  • metadata.lastRefreshTime
    — when the underlying data was last refreshed. Worth mentioning if the user asks how current the numbers are.
  • metadata.annotation
    — Cube's own description of each member, grouped as
    measures
    /
    dimensions
    /
    segments
    /
    timeDimensions
    and keyed by the same fully qualified names the rows use, carrying at least
    title
    ,
    shortTitle
    and
    type
    . The rows carry values only, so this is where human column headers and value types come from — use
    shortTitle
    for table headers instead of printing raw member names, and
    type
    to decide whether a column is a number to right-align and format.
If the call errors, surface the message plainly. Common causes: a mistyped member name (re-read
meta
), a
dateRange
/
granularity
used against a dimension that isn't a time dimension, or a
limit
above Cube's maximum. Note what is not in that list: a bogus
joinHints
path doesn't error (Step 2), so a clean result never confirms the path was right. When a message isn't self-explanatory, call
api_details({ resource: "cubes", operation: "query" })
and check your shape against what the endpoint actually accepts.
response 的格式为
{ data, metadata }
:
  • data
    ——数据行数组,每一行都是一个扁平 object,其 keys 与 query 中使用的 member names 相同。
  • metadata.rowCount
    ——返回了多少行。
  • metadata.limit
    /
    metadata.offset
    ——Cube 实际应用的 limit 和 offset。
  • metadata.total
    ——仅当 query 设置了
    total: true
    时存在。它是忽略 limit 和 offset 后的匹配行数,因此
    offset + rowCount < total
    表示还有下一页。如果不设置它,一个刚好填满的 page 与一个恰好结束于 last row 的 page 无法区分——当打算说明“显示 10 条,共 N 条”或提供翻页时,应设置
    total: true
    。
  • metadata.lastRefreshTime
    ——底层数据最后一次刷新的时间。如果用户询问数字的时效性,值得提及。
  • metadata.annotation
    ——Cube 对每个 member 的说明,按
    measures
    /
    dimensions
    /
    segments
    /
    timeDimensions
    分组,并使用与 rows 相同的 fully qualified names 作为 keys,至少包含
    title
    、
    shortTitle
    和
    type
    。Rows 仅携带 values,因此人类可读的 column headers 和 value types 来自这里——使用
    shortTitle
    作为 table headers,而不是打印原始 member names;使用
    type
    判断某列是否为数字,并据此右对齐和格式化。
如果调用报错,应直接呈现错误消息。常见原因包括:member name 拼写错误(重新读取
meta
)、在非 time dimension 上使用了
dateRange
/
granularity
,或
limit
超过 Cube 的 maximum。注意,这个列表中不包含 bogus
joinHints
path——它不会报错(参见第 2 步),因此成功返回的结果绝不能证明 path 正确。当错误消息本身无法说明问题时,调用
api_details({ resource: "cubes", operation: "query" })
,并将请求结构与 endpoint 实际接受的内容进行核对。

Step 5: Render the result in chat

第 5 步:在聊天中呈现结果

5a. Table — always

5a. Table——始终呈现

Render every returned row as a standard Markdown table, not ASCII art — it renders natively in the chat UI and needs no manual column-width math. Take headers from
metadata.annotation
(
shortTitle
) rather than printing raw member names. Right-align numeric columns with the
---:
header-separator syntax. Format numbers with thousands separators; round to 2 decimals when not integral.
markdown
| Traffic Source | Count |
|---|---:|
| Search | 142,318 |
| Organic | 88,204 |
| Email | 41,907 |
| Facebook | 22,015 |
| Display | 9,471 |
将每个返回行渲染为标准 Markdown table,而不是 ASCII art——Markdown table 可以在聊天 UI 中原生渲染,无需手动计算列宽。表头取自
metadata.annotation
中的
shortTitle
,不要打印原始 member names。使用
---:
header-separator syntax 将数值列右对齐。数字应添加千位分隔符;非整数四舍五入到 2 位小数。
markdown
| Traffic Source | Count |
|---|---:|
| Search | 142,318 |
| Organic | 88,204 |
| Email | 41,907 |
| Facebook | 22,015 |
| Display | 9,471 |

5b. Chart — when the shape allows

5b. Chart——数据形态允许时

If the query returned exactly one measure plus exactly one dimension (categorical or time), also create an artifact with a real chart (bar chart for a category breakdown, line or bar chart for a time series) so it renders inline as an actual chart, not text art. A small self-contained SVG is usually the simplest and most portable choice — no external libraries or network access needed — but use whatever chart artifact fits the client best. Label the axes/categories and show the values; keep the color scheme simple.
If the current client doesn't support artifacts, skip the chart and rely on the table alone — don't fall back to drawing a chart out of text characters.
Skip the chart entirely when: the result set is empty, the query has 2+ measures, 2+ dimensions, a single scalar value (no dimension), or all measure values are zero or null. For a single scalar answer, state the number in prose followed by the one-row table — no chart.
如果 query 返回的恰好是一个 measure 加一个 dimension(categorical 或 time),还应创建一个包含真实 chart 的 artifact(category breakdown 使用 bar chart,time series 使用 line 或 bar chart),以便它作为真正的 chart 内联渲染,而不是文本字符画。小型 self-contained SVG 通常是最简单且可移植性最好的选择——不需要外部 library 或 network access——但应使用最适合 client 的 chart artifact。
如果当前 client 不支持 artifacts,则跳过 chart,仅依赖 table——不要退回到用文本字符绘制 chart。
出现以下情况时应完全跳过 chart:result set 为空;query 包含 2 个或更多 measures;包含 2 个或更多 dimensions;结果只有一个 scalar value(没有 dimension);或者所有 measure values 均为 zero 或 null。对于单个 scalar answer,应先用文字说明该数字,再附上一行的 table——不要生成 chart。

Step 6: Explain the result briefly

第 6 步:简要解释结果

After the rendered output, add 1–3 short sentences in plain English: what was measured, the highest/lowest bucket, and any obvious anomaly visible in the table (e.g. a missing period, a single category dominating the total) — don't speculate about causes not visible in the data. Suggest exactly one concrete follow-up query the user could ask next.
在渲染输出后,添加 1–3 句简明说明:测量了什么、最高和最低的 bucket(分组)是什么,以及 table 中可见的明显异常(例如缺失某个 period,或某一个 category 占据绝大多数)——不要推测数据中不可见的原因。建议恰好 一个 用户接下来可以提出的具体 follow-up query。

Rules

规则

  • Never hardcode cube or member names — always confirm against
    meta
    first.
  • Answer aggregate/analytical questions from the semantic model even when the question names a source system (HubSpot, Zammad, Exact Online, …) — don't switch to a direct source connector mid-task; that's for point lookups of one already-known record, not dataset-wide counts (see Step 1).
  • Never silently resolve an ambiguous multi-cube join — ask the user (see Step 2).
  • Never read an empty
    joins
    array as "no relationships": only outgoing joins are listed, so check the other cube too (see Step 2).
  • Confirm every
    joinHints
    hop against a declared join before setting it. A fabricated pair is accepted and answered, not rejected — the query succeeding tells you nothing about whether the path was real (see Step 2).
  • Prefer clearly business-named cubes over internal/system-generated ones when several match a search (see Step 1).
  • Always render the table; render the chart only when the data shape supports it.
  • Always set
    limit
    deliberately; the endpoint applies Cube's own default, which is far larger than a conversation wants.
  • Set
    total: true
    whenever you plan to report "N of M" or offer another page.
  • api_details
    is the authority on what the endpoint accepts — use it when a call is rejected rather than guessing at the shape.
  • This is a read-only, in-chat skill — no file writes, no local project, no YAML. Reading the semantic model uses
    api_read
    only; the MCP server also exposes
    api_write
    and
    api_delete
    , and this skill never calls them.
  • If
    meta
    returns no cubes, tell the user their organization doesn't appear to have a semantic model set up yet — don't guess why.
  • 绝不硬编码 cube 或 member names——始终先通过
    meta
    确认。
  • 即使问题指明源系统(HubSpot、Zammad、Exact Online 等),也应从 semantic model 回答聚合/分析问题——不要在任务进行中切换到 direct source connector;后者仅用于对一个已知记录进行点查,而不是 dataset-wide 的 counts(参见第 1 步)。
  • 绝不悄悄解决有歧义的 multi-cube join——应询问用户(参见第 2 步)。
  • 绝不把空的
    joins
    array 理解为“没有 relationships”:只会列出 outgoing joins,因此还要检查另一个 cube(参见第 2 步)。
  • 设置
    joinHints
    前,逐一确认每个 hop 都存在 declared join。虚构的 pair 会被接受并返回答案,而不会遭到拒绝——query 成功完全不能说明 path 是否真实(参见第 2 步)。
  • 当多个匹配项同时存在时,优先使用命名清晰的业务 cube,而不是内部/系统生成的 cube(参见第 1 步)。
  • 始终渲染 table;仅在数据形态支持时渲染 chart。
  • 始终有意地设置
    limit
    ;endpoint 应用的 Cube default 远大于对话所需。
  • 当计划报告“N 条,共 M 条”或提供下一页时,设置
    total: true
    。
  • api_details
    是判断 endpoint 接受内容的权威来源——当调用被拒绝时,应使用它而不是猜测请求结构。
  • 这是一个 read-only、in-chat skill——不写文件,不使用 local project,不编写 YAML。读取 semantic model 时仅使用
    api_read
    ;MCP server 还公开了
    api_write
    和
    api_delete
    ,但此 skill 绝不调用它们。
  • 如果
    meta
    没有返回任何 cubes,应告诉用户其组织似乎尚未设置 semantic model——不要猜测原因。",