02智能体与API
只管要Metric，SQL交给我们。
通过REST或MCP发送Metric名称、维度和筛选条件。返回的数据行与其他任何工具一致。
{
"metrics": ["avg_order_value"],
"dimensions": [
"Customer.region",
{ "name": "ordered_at",
"entity": "Order",
"grain": "month" }
],
"filters": [
{ "dimension": "status",
"entity": "Order",
"op": "eq",
"value": "completed" }
],
"limit": 100
}SELECT c.region,
date_trunc('month', o.ordered_at)
AS ordered_at,
SUM(o.amount) / COUNT(o.id)
AS avg_order_value
FROM public.orders o
JOIN public.customers c
ON o.customer_id = c.id
WHERE o.status = 'completed'
GROUP BY 1, 2
LIMIT 100;| region | ordered_at | avg_order_value |
|---|---|---|
| EMEA | 2026-01-01 | 118.40 |
| EMEA | 2026-02-01 | 121.05 |
| NA | 2026-01-01 | 132.90 |
| NA | 2026-02-01 | 130.15 |
一个请求、它编译成的SQL，以及返回的数据行。
谁在提问
智能体、应用和BI发送同一种请求
无论谁在提问，JSON的结构只有一种。智能体还会拿到一份可供选择的目录。
- 智能体，通过MCP
- 通过OAuth登录，只能看到允许使用的Metric，并按名称提问。它们无法编造联接，也读不到隐藏的行。
- 应用，通过REST
- 只有一个端点。应用按名称请求Metric，而不是请求表。
- BI与分析师
- 使用与智能体相同的Metric名称，因此数字一致。
{
"name": "run_semantic_query",
"arguments": {
"metrics": ["revenue"],
"dimensions": [{
"name": "ordered_at",
"entity": "Order",
"grain": "quarter"
}]
}
}参考
输入8个字段，输出6种错误码
请求字段
- metrics
- 受控Metric名称，例如 "avg_order_value"。
- measures
- 底层原始Measure（度量）名称。仅在Explore模式下可用。
- dimensions
- 分组聚合维度，包括时间粒度划分。
- filters
- 筛选条件（eq、gt、in或contains等）。杜绝原始SQL。
- order
- 按所选的任意字段进行排序。
- view
- 限定仅在指定的精选View视图内查询。
- limit
- 返回行数上限。受成本配额统一约束。
- version
- 锁定模型版本号。默认指向最新发布版本。
错误码
| HTTP状态 | 错误代码 | 触发场景 |
|---|---|---|
| 400 | bad_request | 请求格式不合法 |
| 401 | unauthenticated | 缺少认证令牌或令牌无效 |
| 403 | forbidden | Governed密钥尝试请求原始Measure |
| 404 | not_found | 未找到指定的Metric或dimension |
| 429 | over_budget | 超出成本上限 |
| 503 | overloaded | 服务容量已达峰值 |
所有错误都是同一种结构：{ "error": { "code", "message" } }
可以依赖的承诺
同样的请求，同样的答案
联接自动完成
只需指定measure和dimension，联接由模型补全。
合计不会虚高
一对多联接也绝不会把一行算两次。
与财务一致的平均值
由合计计算得出，绝不对平均值再取平均。
换了数据仓库，请求不变
迁移数据仓库后，每个调用方仍发送同样的JSON。
重复的问题跳过扫描
短时结果缓存会直接回答重复的问题，无需访问数据仓库。可选的Rollup对最常见的问题起同样作用。
一个吵闹的调用方拖不慢其他人
限流器会明确返回429或503，而不是让所有人一起等待。
等有了基准测试，我们再公布速度数据。 密码如何留在您的网络内 →