semantic-model
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSemantic Model
语义模型
Answer business questions by querying the org's live semantic model over the
MCP server and rendering the result directly in the chat.
RevOSThe MCP server exposes a small set of generic tools; the semantic model is
reached through one of them, , against the resource:
api_readcubes| Call | What you get |
|---|---|
| the compiled semantic model — every cube/view with its measures, dimensions, segments and joins |
| rows |
api_details({ resource: "cubes", operation: "query" })api_detailsapi_detailsThere is also with no , 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
, always.
api_read({ resource: "cubes" })methodmeta通过 MCP 服务器查询组织的实时语义模型,并直接在聊天中呈现结果。
RevOSMCP 服务器公开了一小组通用工具;语义模型通过其中一个工具 访问目标资源 :
api_readcubes| 调用 | 返回内容 |
|---|---|
| 已编译的语义模型——包含每个 cube/view 及其 measures、dimensions、segments 和 joins |
| 数据行 |
api_details({ resource: "cubes", operation: "query" })api_detailsapi_details还有一个不带 的 ,它会列出已存储的 cube definitions——即某人所编写的 YAML。这与“我可以查询什么”是不同的问题;回答业务问题时始终应使用 。
methodapi_read({ resource: "cubes" })metaStep 1: Discover what's queryable
第 1 步:发现可查询的内容
Before guessing member names, read the catalogue. is a list endpoint
like any other, so project it down rather than pulling the whole document:
metajson
{
"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. defaults to 100 and goes up to 1000 for ; if the
response carries a
, pass it back as for the rest.
pageSizemetametadata.nextPageTokenparams.pageTokenThe 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 or
(names , ), and views of
tables are named ; 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.
[Table] …[Segment] …model_stream_…___localsegment_…model_…Then pull the full definition of the cube(s) the question needs, by dropping
and filtering to them:
fieldsjson
{
"resource": "cubes",
"method": "meta",
"params": { "filter": "name == \"gold_order_items_enriched\"" }
}That returns the exact , (with time granularities where
relevant), , and you can reference — always addressed as
, e.g. or
. See Step 2 for what gives you,
and what it doesn't.
measuresdimensionssegmentsjoins<CubeName>.<member>gold_order_items_enriched.countgold_order_items_enriched.order_datejoinsparams.filternametitledescriptiontypename.contains("invoice")!name.endsWith("_local")type == "view"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 returns, say so — don't invent a field.
metaStay 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 cube built from , 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.
usersgold_contacts在猜测 member 名称前,先读取 catalogue。 和其他 list endpoint 一样,因此应通过字段投影缩减结果,而不是拉取整个 document:
metajson
{
"resource": "cubes",
"method": "meta",
"params": { "fields": "name,title,description", "pageSize": 100 }
}这是完整的 catalogue,只有几 KB——读取成本低且便于选择。 默认为 100, 最高可到 1000;如果 response 中带有 ,将其作为 传回以获取后续页面。
pageSizemetametadata.nextPageTokenparams.pageTokencatalogue 中可能同时出现内部、系统生成的 cube 和预期中的业务 cube——例如支撑“最新得分”汇总的 helper cube、内部 segment cube,或为支持其他 cube joins 而存在的 plumbing。RevOS 生成的 cube 标题为 或 (名称为 、),表的 views 名为 ;其他 cube 通常会因 description 稀疏或缺失,或 name/title 听起来较为机械而显得突出。搜索同时匹配到命名清晰的业务 cube 和其中一种内部 cube 时,除非问题明确针对内部 cube,否则应描述并查询业务 cube。
[Table] …[Segment] …model_stream_…___localsegment_…model_…随后,通过省略 并筛选到所需 cube,拉取问题的完整 definition:
fieldsjson
{
"resource": "cubes",
"method": "meta",
"params": { "filter": "name == \\"gold_order_items_enriched\\"" }
}这会返回可引用的精确 、(相关维度还带 time granularities)、 和 ——始终以 形式寻址,例如 或 。第 2 步将说明 能提供什么,以及不能提供什么。
measuresdimensionssegmentsjoins<CubeName>.<member>gold_order_items_enriched.countgold_order_items_enriched.order_datejoinsparams.filternametitledescriptiontypename.contains("invoice")!name.endsWith("_local")type == "view"如果用户的问题纯粹关于发现——“我的语义模型里有什么”“我可以查询什么”“列出 cubes/datasets”——到这里就停止:用文字或简短表格总结 cubes(如果已拉取完整 definition,也总结其 fields),并跳过第 3–6 步。不要运行用户没有要求的 query。
绝不硬编码或猜测 member name。如果根据 返回的内容无法回答问题,就直说——不要虚构 field。
meta即使问题指明源系统,也始终使用语义模型。
例如,“有多少个不同的 HubSpot owners 至少拥有一位 contact?”虽然提到了 HubSpot,但这仍是一个聚合问题——应从语义模型回答(例如使用由 构建的 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。
gold_contactsusersStep 2: Crossing cubes — read joins
, and know its two blind spots
joins第 2 步:跨 cube 查询——读取 joins
,并了解两个盲区
joinsmetajoins{ name, relationship, sql }gold_order_items_enrichedgold_users_with_order_statsjoinsTwo blind spots, and both will bite you if you trust as a complete
picture:
joinsOnly 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 — declares a join to , but
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 array as "this cube doesn't connect to anything": check the
other cube's too before concluding there is no path.
dealscustomerscustomersjoinsjoinsA fabricated path is not rejected. 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.
or . 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.
joinHintsjoinHints[["gold_order_items_enriched", "gold_users_with_order_stats"]][["orders", "line_items", "products"]]So: set only when every consecutive pair in it is an edge you
actually saw in some cube's — 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 , 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.
joinHintsjoinsjoinHints每个 cube 的 都会返回 array——即它所连接的每个其他 cube,格式为 。在编写跨越多个 cube 的 query 前应先读取它:如果问题需要同时使用 和 ,应拉取其中之一,并检查另一个是否出现在它的 中。不要仅因为两个 cube 恰好都有名称相似的“account id”形列,就推断两者存在 relationship。
metajoins{ name, relationship, sql }gold_order_items_enrichedgold_users_with_order_statsjoins有两个盲区;如果完全信任 作为完整视图,两者都会导致误判:
joins只列出 outgoing joins。 cube 报告的是它自己声明的 joins,而不是其他 cube 声明并指向它的 joins。本 codebase 中的 joins 是单向编写的—— 声明了到 的 join,而 并未反向声明——但 Cube 的 planner 可以从任一方向遍历这种 join。因此,一个被所有对象 join 的 dimension-style cube 可能报告 零个 joins,却实际上可以从十几个位置连接。绝不把空的或很短的 array 理解为“此 cube 不与任何对象连接”:得出不存在 path 的结论前,还要检查另一个 cube 的 。
dealscustomerscustomersjoinsjoins虚构的 path 不会被拒绝。 当两个 cube 之间有多条 path 时, 可以锁定 route:它是一个 path 列表,每个 path 都是由 cube 名称组成的有序 array——直接 join 为两个,多跳则更多——例如 或 。path 中某个相邻 pair 没有 declared join 作为支撑,并不会产生 error:Cube 会 fallback 到自动解析真实 path,于是你得到的 answer 是基于一条并未由你选择的 route 计算的。当仅有一条真实 path 存在时,这通常无害——Cube 会忽略 bogus hint 并正确解析——但当 schema 中确实存在两条有效 path 形成的分叉时,结果会静默出错,因为虚构的 hint 无法可靠锁定其中任何一条。query 成功并不能证明 path 是真实的。
joinHintsjoinHints[["gold_order_items_enriched", "gold_users_with_order_stats"]][["orders", "line_items", "products"]]因此:只有当 中每一对相邻 cube 都是你确实在某��� cube 的 中见过的 edge 时,才能设置 ——并且需要按照第一个盲区的要求检查两个方向。当存在多条合理 route 时——例如通往同一 field 的两条 path,或某个 fact table 既能直接到达某个 dimension,也能经由第三个 cube 到达——不要悄悄选择其中一条。应明确说明歧义,并请用户确认预期的 relationship 或 grain——例如“每个 order item 的 revenue”与“每个 user 的 revenue”——然后再运行 query。每当你设置 时,都应在后续说明中讲清使用了哪条 path 以及原因,方便用户发现错误假设。如果问题并不需要跨 cube,优先采用最简单的 single-cube 答案。
joinHintsjoinsjoinHintsjoinHintsStep 3: Build the query
第 3 步:构建 query
The Cube.js query goes in — note the nesting; the body is
, not the query object itself.
body.query{ "query": { … } }| Field | Shape | Notes |
|---|---|---|
| | quantities to aggregate, e.g. |
| | attributes to group/break down by |
| | named filters from |
| | see below |
| see below | leaf conditions, optionally nested in |
| | either shape works — array of |
| | pins an ambiguous join path — each entry is an ordered path of cube names (two or more), see Step 2 |
| | see "Row limits" below |
| | for paging past |
| IANA string, e.g. | defaults to UTC |
| | also returns the total matching row count, ignoring |
| | 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[].granularitydayweekmonthquarteryearhourminutesecondtimeDimensions[].dateRange"last quarter""last 12 months""this month"["2026-01-01", "2026-03-31"]Period over period ("this month vs. last month") — run one query per
range, each with its own , and compare them yourself. Avoid
: 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.
dateRangecompareDateRangefilters- A condition: . Values are usually strings (
{ "member": "...", "operator": "...", "values": [...] }works fine even for numbers/dates), but numbers, booleans, and["100"]are accepted too. Operators:null,equals,notEquals,in,notIn,contains,notContains,startsWith,notStartsWith,endsWith,notEndsWith,gt,gte,lt,lte,inDateRange,notInDateRange,onTheDate,beforeDate,beforeOrOnDate,afterDate,afterOrOnDate.measureFilter/setcheck presence and take nonotSet.values - A group: or
{ "and": [...] }, where each entry is again a condition or a group (they can nest). Top-level entries in the{ "or": [...] }array are implicitly AND-combined; reach for an explicitfiltersgroup the moment a question needs "either of these" rather than "all of these" — mixing dimension and measure conditions inside the sameor/andgroup isn't supported, keep those separate.or
These are Cube's own filters, on , 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 CEL string from Step 1: that one filters the catalogue,
this one filters the data.
body.query.filtersparams.filterCube.js query 放在 中——注意嵌套层级;body 是 ,而不是 query 对象本身。
body.query{ "query": { … } }| 字段 | 形态 | 说明 |
|---|---|---|
| | 要聚合的度量值,例如 |
| | 用于分组或拆分的属性 |
| | |
| | 详见下文 |
| 见下文 | 叶子条件,可选择嵌套在 |
| | 两种形态都可用—— |
| | 固定有歧义的 join path——每项都是 cube 名称组成的有序 path(至少两个),参见第 2 步 |
| | 参见下文“行数限制” |
| | 用于翻页并越过 |
| IANA string,例如 | 默认为 UTC |
| | 同时返回忽略 |
| | 返回未经 dimensions 聚合的原始行,用于检查单条记录而不是汇总;行数限制仍然适用 |
此处未列出的 keys 会原样转发给 Cube,因此即使 API 没有命名的 Cube.js feature 仍然可以使用。
timeDimensions[].granularitydayweekmonthquarteryearhourminutesecondtimeDimensions[].dateRange"last quarter""last 12 months""this month"["2026-01-01", "2026-03-31"]环比(“本月与上月相比”)——针对每个范围分别运行一个 query,为其设置各自的 ,然后自行比较。应避免使用 :endpoint 会将 Cube 的结果当作一个普通 result 读取,而 compare query 并非这种结构,因此很可能只返回一个简单的 500 错误。
dateRangecompareDateRangefilters- 一个 condition:。Values 通常是 strings(即使目标为 numbers/dates,
{ "member": "...", "operator": "...", "values": [...] }也能正常工作),但也接受 numbers、booleans 和["100"]。Operators 包括:null、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": [...] },其中每一项又是一个 condition 或 group(可以嵌套)。{ "or": [...] }array 的顶层各项默认以 AND 组合;一旦问题需要“满足其中之一”而不是“同时满足全部”,就应立即使用显式的filtersgroup——不支持在同一个or/andgroup 中混合 dimension conditions 和 measure conditions,应将它们分开。or
这些是 Cube 自身的 filters,位于 ,会直接转发给 Cube,而不是在这里按 schema 验证——格式错误会返回 Cube 的 error,而不是整洁的参数错误提示。不要将它们与第 1 步中的 CEL string 混淆:后者筛选的是 catalogue,前者筛选的是 data。
body.query.filtersparams.filterRow limits
行数限制
limit- Always name the you actually want. An open-ended query with no
limitcan return thousands of rows straight into the conversation.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.
metadata.limit
limit- 始终明确写出你实际需要的 。 没有
limit的开放式 query 可能一次将数千行直接返回到对话中。limit - response 中的 才是权威值——它报告 Cube 实际应用的 limit;当你说明结果被截断时,应引用这个数字。
metadata.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 with
timeDimensions→ chart candidate over time.granularity - Multiple measures or multiple dimensions → table only; don't try to chart it.
- Always set explicitly for "top N" questions (
limit+ matchinglimit: N), and never rely on the default for an open-ended pull.order
最简单的 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→ 可生成时间序列 chart。timeDimensions - 多个 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 }- — the array of rows, each a flat object keyed by the same member names used in the query.
data - — how many rows came back.
metadata.rowCount - /
metadata.limit— what Cube actually applied.metadata.offset - — present only if the query set
metadata.total. It is the count of matching rows ignoring limit and offset, sototal: trueis how you tell there is another page. Without it, a page that fills exactly is indistinguishable from one ending on the last row — so setoffset + rowCount < totalwhenever you intend to say "showing 10 of N" or to offer paging.total: true - — when the underlying data was last refreshed. Worth mentioning if the user asks how current the numbers are.
metadata.lastRefreshTime - — Cube's own description of each member, grouped as
metadata.annotation/measures/dimensions/segmentsand keyed by the same fully qualified names the rows use, carrying at leasttimeDimensions,titleandshortTitle. The rows carry values only, so this is where human column headers and value types come from — usetypefor table headers instead of printing raw member names, andshortTitleto decide whether a column is a number to right-align and format.type
If the call errors, surface the message plainly. Common causes: a mistyped
member name (re-read ), a / used against a
dimension that isn't a time dimension, or a above Cube's maximum. Note
what is not in that list: a bogus path doesn't error (Step 2), so
a clean result never confirms the path was right. When a message isn't
self-explanatory, call
and check your shape against what the endpoint actually accepts.
metadateRangegranularitylimitjoinHintsapi_details({ resource: "cubes", operation: "query" })response 的格式为 :
{ data, metadata }- ——数据行数组,每一行都是一个扁平 object,其 keys 与 query 中使用的 member names 相同。
data - ——返回了多少行。
metadata.rowCount - /
metadata.limit——Cube 实际应用的 limit 和 offset。metadata.offset - ——仅当 query 设置了
metadata.total时存在。它是忽略 limit 和 offset 后的匹配行数,因此total: true表示还有下一页。如果不设置它,一个刚好填满的 page 与一个恰好结束于 last row 的 page 无法区分——当打算说明“显示 10 条,共 N 条”或提供翻页时,应设置offset + rowCount < total。total: true - ——底层数据最后一次刷新的时间。如果用户询问数字的时效性,值得提及。
metadata.lastRefreshTime - ——Cube 对每个 member 的说明,按
metadata.annotation/measures/dimensions/segments分组,并使用与 rows 相同的 fully qualified names 作为 keys,至少包含timeDimensions、title和shortTitle。Rows 仅携带 values,因此人类可读的 column headers 和 value types 来自这里——使用type作为 table headers,而不是打印原始 member names;使用shortTitle判断某列是否为数字,并据此右对齐和格式化。type
如果调用报错,应直接呈现错误消息。常见原因包括:member name 拼写错误(重新读取 )、在非 time dimension 上使用了 /,或 超过 Cube 的 maximum。注意,这个列表中不包含 bogus path——它不会报错(参见第 2 步),因此成功返回的结果绝不能证明 path 正确。当错误消息本身无法说明问题时,调用 ,并将请求结构与 endpoint 实际接受的内容进行核对。
metadateRangegranularitylimitjoinHintsapi_details({ resource: "cubes", operation: "query" })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 () 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.
metadata.annotationshortTitle---: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 中原生渲染,无需手动计算列宽。表头取自 中的 ,不要打印原始 member names。使用 header-separator syntax 将数值列右对齐。数字应添加千位分隔符;非整数四舍五入到 2 位小数。
metadata.annotationshortTitle---: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 first.
meta - 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 array as "no relationships": only outgoing joins are listed, so check the other cube too (see Step 2).
joins - Confirm every 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).
joinHints - 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 deliberately; the endpoint applies Cube's own default, which is far larger than a conversation wants.
limit - Set whenever you plan to report "N of M" or offer another page.
total: true - is the authority on what the endpoint accepts — use it when a call is rejected rather than guessing at the shape.
api_details - This is a read-only, in-chat skill — no file writes, no local project, no
YAML. Reading the semantic model uses only; the MCP server also exposes
api_readandapi_write, and this skill never calls them.api_delete - If returns no cubes, tell the user their organization doesn't appear to have a semantic model set up yet — don't guess why.
meta
- 绝不硬编码 cube 或 member names——始终先通过 确认。
meta - 即使问题指明源系统(HubSpot、Zammad、Exact Online 等),也应从 semantic model 回答聚合/分析问题——不要在任务进行中切换到 direct source connector;后者仅用于对一个已知记录进行点查,而不是 dataset-wide 的 counts(参见第 1 步)。
- 绝不悄悄解决有歧义的 multi-cube join——应询问用户(参见第 2 步)。
- 绝不把空的 array 理解为“没有 relationships”:只会列出 outgoing joins,因此还要检查另一个 cube(参见第 2 步)。
joins - 设置 前,逐一确认每个 hop 都存在 declared join。虚构的 pair 会被接受并返回答案,而不会遭到拒绝——query 成功完全不能说明 path 是否真实(参见第 2 步)。
joinHints - 当多个匹配项同时存在时,优先使用命名清晰的业务 cube,而不是内部/系统生成的 cube(参见第 1 步)。
- 始终渲染 table;仅在数据形态支持时渲染 chart。
- 始终有意地设置 ;endpoint 应用的 Cube default 远大于对话所需。
limit - 当计划报告“N 条,共 M 条”或提供下一页时,设置 。
total: true - 是判断 endpoint 接受内容的权威来源——当调用被拒绝时,应使用它而不是猜测请求结构。
api_details - 这是一个 read-only、in-chat skill——不写文件,不使用 local project,不编写 YAML。读取 semantic model 时仅使用 ;MCP server 还公开了
api_read和api_write,但此 skill 绝不调用它们。api_delete - 如果 没有返回任何 cubes,应告诉用户其组织似乎尚未设置 semantic model——不要猜测原因。",
meta