Query Fields

Overview#

Explainability 在 backend 中不是獨立 `/v2/query/explain` endpoint，而是由 `/v2/query` 內嵌欄位解釋資訊，並由 `/v2/query/fields` 提供 machine-readable 欄位契約。

此頁聚焦 explainability 層的可用介面與資料結構，對齊 `search_query_explainability.py` 的 deterministic 規則。

此端點屬於查詢能力與欄位契約工具，不代表任何單一資料集本身的 3 年覆蓋或全市場覆蓋聲明。

• 在程式端先拉欄位契約，再組裝 query 請求。
• 把欄位來源、公式、attach rule 寫入審計與研究報表。
• 在 batch 模式重用 `explainability_shared` 降低重複 payload。

Request#

`/v2/query/fields` 可用 `entity_type` 篩選欄位；`/v2/query` 預設回傳 explainability（除非 `minimal_fields=true`）。

Query Parameters#

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 說明#

Usage Notes / 使用建議#

• Explainability 層為 productized capability，但屬於 `/v2/query` 生態的一部分，不是獨立 dataset route。
• 不提供模型生成敘述；所有欄位說明均來自 deterministic registry。
• 可搭配 `/v2/query/examples` 作為客戶端快速接線樣板。
• 實際資料覆蓋範圍仍以各資料集頁面的 coverage/limitation 註記與 API 回應為準。