02エージェントとAPI
Metricを頼むだけ。SQLは私たちが書く。
Metric名、ディメンション、フィルタをRESTまたはMCPで送ります。返ってくる行は、ほかのどのツールとも一致します。
{
"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
- 「avg_order_value」などの統制されたMetric名。
- measures
- 未加工のMeasure（集計値）名。Exploreモードでのみ使用可能。
- dimensions
- 時間バケットを含む、グルーピング対象の属性。
- filters
- eq、gt、in、containsなどの条件。raw 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を指定するだけ。結合はモデルが補います。
合計が膨らまない
1対多の結合でも、行を二重に数えません。
財務と一致する平均
平均は合計から計算します。平均の平均はとりません。
ウェアハウスが変わってもリクエストは同じ
ウェアハウスを移行しても、呼び出し側は同じJSONを送り続けられます。
同じ質問はスキャンを省く
短期間の結果キャッシュが、同じ質問にウェアハウスを読まずに答えます。頻出の質問には、オプトインのRollupが同じ役割を果たします。
ひとつの呼び出し元が全体を遅くしない
レート制限が、全員を待たせる代わりに、429または503をはっきり返します。
速度の数値は、ベンチマークができてから公開します。 パスワードがお客様のネットワークに留まる仕組み →