查詢與工具
查詢 API
提供 allowlist 欄位查詢能力，適合固定契約資料提取與 explainability 驗證。
GET
/v2/queryOverview#
查詢 API 提供嚴格 allowlist 的欄位查詢能力，適合在固定契約下擷取跨資料主題欄位。
回應預設附帶 explainability metadata，可直接用於來源驗證與欄位審計。
- 以單一 issuer/index 抽取固定欄位，供策略與面板使用。
- 批次查詢多標的並取得共享 explainability metadata。
- 搭配 `/v2/query/fields` 先查 allowlist，再動態組裝查詢。
Request#
必填條件為 `entity_type`、`fields`，且必須提供 `entity_id` 或 `entity_ids[]` 其中之一。單次最多 10 個 entity。
Query Parameters#
| 欄位 | 型別 | Required | 說明 |
|---|---|---|---|
| entity_id | string | no | 單一實體識別（ticker 或 index code）。 |
| entity_ids | string | no | 逗號分隔的批次實體識別。 |
| entity_ids[] | string[] | no | 重複 query 參數的批次實體識別。 |
| entity_type | string | yes | issuer 或 index。 |
| fields | string | yes | 逗號分隔欄位清單。 |
| fields[] | string[] | no | 重複 query 參數欄位清單。 |
| as_of_date | string | no | 查詢基準日（YYYY-MM-DD）。 |
| minimal_fields | boolean | no | true 時省略 explainability payload。 |
Response Shape#
單筆模式回傳 `data + explainability`；批次模式回傳 `results + explainability_shared`。
dataset 固定為 `field_query`，不支援任意 SQL passthrough。
{
"api_version": "v2",
"endpoint": "/v2/query",
"request_id": "req_query_4e6a8c0d",
"plan_id": "developer",
"dataset": "field_query",
"entity_id": "2330",
"entity_type": "issuer",
"as_of_date": "2026-04-22",
"fields": [
"company_name",
"pe_ratio",
"revenue_yoy_pct"
],
"data": {
"company_name": "台灣積體電路製造股份有限公司",
"pe_ratio": 26.8,
"revenue_yoy_pct": 0.18
},
"explainability": {
"company_name": {
"source_topic": "issuer_profile",
"source_table_or_contract": "issuer_profiles",
"source_field": "company_name",
"attach_rule": "exact_entity_attach",
"formula": null,
"nullability_rule": "nullable_if_source_missing",
"freshness_basis": "latest_on_or_before(as_of_date)"
}
},
"errors": [],
"meta": {
"batch_mode": false,
"supported_entity_types": [
"index",
"issuer"
]
}
}Field 說明#
| 欄位路徑 | 型別 | 說明 |
|---|---|---|
| dataset | string | 固定為 field_query。 |
| entity_type | string | issuer 或 index。 |
| fields[] | string[] | 實際解析後欄位清單。 |
| data | object | 單筆模式欄位值映射。 |
| results[] | array | 批次模式結果列。 |
| explainability | object | 單筆模式欄位級解釋資訊。 |
| explainability_shared | object | 批次模式共享 explainability 區塊。 |
| errors[] | array | 欄位或請求錯誤資訊。 |
| meta.allowlist | array | 目前 entity_type 可用欄位列表。 |
Usage Notes / 使用建議#
- Companion endpoints：`/v2/query/fields`（欄位契約）與 `/v2/query/examples`（請求範例）。
- unsupported_field 會明確出現在 errors，不會默默忽略。
- Explainability 為 deterministic 映射，不包含 LLM 生成敘述。
Plan / Readiness#
- Status：productized capability（registry: field_query）
- Routes：/v2/query、/v2/query/fields、/v2/query/examples
- 實際 entitlement 以 API key 方案為準