查詢與工具
Explainability
說明欄位來源與掛接規則，供 query 流程做可追溯與契約驗證。
GET
/v2/query/fieldsOverview#
Explainability 在 backend 中不是獨立 `/v2/query/explain` endpoint，而是由 `/v2/query` 內嵌欄位解釋資訊，並由 `/v2/query/fields` 提供 machine-readable 欄位契約。
此頁聚焦 explainability 層的可用介面與資料結構，對齊 `search_query_explainability.py` 的 deterministic 規則。
- 在程式端先拉欄位契約，再組裝 query 請求。
- 把欄位來源、公式、attach rule 寫入審計與研究報表。
- 在 batch 模式重用 `explainability_shared` 降低重複 payload。
Request#
`/v2/query/fields` 可用 `entity_type` 篩選欄位；`/v2/query` 預設回傳 explainability（除非 `minimal_fields=true`）。
Query Parameters#
| 欄位 | 型別 | Required | 說明 |
|---|---|---|---|
| entity_type | string | no | issuer 或 index；不帶則回傳全部。 |
Response Shape#
`/v2/query/fields` 回傳欄位定義與 explainability metadata；`/v2/query` 回傳資料值時可附 explainability / explainability_shared。
Explainability payload key 固定為 source_topic、source_table_or_contract、source_field、attach_rule、formula、nullability_rule、freshness_basis。
{
"api_version": "v2",
"endpoint": "/v2/query/fields",
"request_id": "req_explain_2c4e6a8b",
"plan_id": "developer",
"entity_type": "issuer",
"fields": [
{
"entity_type": "issuer",
"field_name": "company_name",
"description": "Deterministic query field `company_name` for `issuer` entity_type.",
"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)",
"status": "active",
"exclusion_reason": null
}
],
"meta": {
"supported_entity_types": [
"index",
"issuer"
],
"active_field_count": 1,
"excluded_field_count": 0
}
}Field 說明#
| 欄位路徑 | 型別 | 說明 |
|---|---|---|
| fields[].entity_type | string | 欄位所屬實體類型。 |
| fields[].field_name | string | 可查詢欄位名稱。 |
| fields[].source_topic | string|null | 來源 topic 識別。 |
| fields[].source_table_or_contract | string|null | 來源 table/contract。 |
| fields[].attach_rule | string|null | 欄位掛接規則。 |
| fields[].formula | string|null | 公式描述（若有）。 |
| fields[].status | string | active 或 excluded。 |
| fields[].exclusion_reason | string|null | 排除原因。 |
| meta.active_field_count | integer | 可用欄位數量。 |
| meta.excluded_field_count | integer | 排除欄位數量。 |
Usage Notes / 使用建議#
- Explainability 層為 productized capability，但屬於 `/v2/query` 生態的一部分，不是獨立 dataset route。
- 不提供模型生成敘述；所有欄位說明均來自 deterministic registry。
- 可搭配 `/v2/query/examples` 作為客戶端快速接線樣板。
Plan / Readiness#
- Status：productized capability（embedded in field_query）
- Routes：/v2/query、/v2/query/fields、/v2/query/examples
- 不提供獨立 `/v2/query/explain` endpoint