Query Fields

Overview#

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#

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` 作為客戶端快速接線樣板。