Meilisearch facets 請求後分面統計靜默缺失（不報錯）

搜索請求帶 facets 參數時，如果某個分面屬性沒有加入索引的 filterableAttributes 設置，Meilisearch 不報任何錯誤，只是靜默忽略它——該屬性不會出現在響應的 facetDistribution 物件中，前端表現為分面欄缺失或為空。這與 filter 參數的行為（未聲明屬性直接返回 400 invalid_search_filter）截然不同。解法：把要展示的分面屬性全部聲明為 filterable，等設置任務完成後重搜。適用 Meilisearch 全版本。

Issue & Env（案發現場與環境）

• 業務場景：文檔已索引成功，filterableAttributes 只聲明瞭 genres、language，但搜索時 facets 傳了 ["genres", "rating", "language"]（rating 未聲明）。請求返回 200，響應裡的 facetDistribution 卻只有 genres 和 language，rating 分面整個消失，前端下拉/複選框為空，且沒有任何一條報錯日誌。
• 環境：Meilisearch v1.54.3，curl / 任意 SDK 均可復現。
• 關鍵區分：這不是 facets 參數語法錯誤（facets 類型非法才會報 invalid_search_facets），也不是文檔缺少該字段，而是該屬性根本沒被聲明為可過濾——Meilisearch 有意為之的靜默行為。

StackTrace（堆疊日誌）

官方 build faceted navigation 指南對“靜默忽略”行為的原文：

If an attribute passed to facets has not been added to filterableAttributes, Meilisearch silently ignores it. No error is raised; the attribute simply will not appear in the facetDistribution response.

實際觀察到的響應（請求 {"q": "", "facets": ["genres", "rating", "language"]}，其中 rating 未聲明為 filterable）：

{
  "hits": [],
  "facetDistribution": {
    "genres": { "Classics": 12, "Fiction": 8, "Horror": 5 },
    "language": { "English": 18, "French": 7 }
  },
  "estimatedTotalHits": 25
}

對照：同樣的屬性用在 filter 參數裡會直接報錯（HTTP 400）：

{
    "message": "Attribute `rating` is not filterable. Available filterable attributes are: `genres, language`.",
    "code": "invalid_search_filter",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#invalid_search_filter"
}

facets 與 filter 的差別就在這裡：一個靜默、一個報錯。中文官方文檔同樣註明：“如果在 facets 中使用的屬性未添加到 filterableAttributes 列表中，則將被忽略。”

Reproduce（復現程式碼）

# 1. 声明 filterableAttributes（故意漏掉 rating）
curl -X PUT 'http://localhost:7700/indexes/books/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '["genres", "language"]'

# 2. 搜索时 facets 请求三个属性（rating 未声明）——不报错
curl -X POST 'http://localhost:7700/indexes/books/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"q": "", "facets": ["genres", "rating", "language"]}'

# 返回 200，但 facetDistribution 中没有 rating 键

Root Cause（根因分析）

分面與過濾共用一套聲明機制

Meilisearch 的分面統計和過濾依賴同一份 filterableAttributes 設置。官方 settings 文檔原文：Attributes in the filterableAttributes list can be used as filters or facets。引擎只為列表裡的屬性構建分面/過濾所需的內部數據結構；facets 參數裡出現的未知屬性不會觸發校驗，直接跳過，所以既不報錯也不返回統計。

為什麼 facets 寬容、filter 嚴格

搜索 API 對 facets 採用“盡力而為”的寬鬆語義——它支持通配符 ["*"]（請求所有 filterable 屬性）、"specs.*" 前綴匹配等 pattern。對每個 facets 條目做嚴格校驗會破壞這類用法；而 filter 是明確的布爾表達式，屬性解析不出來會直接影響結果正確性，所以必須報錯。

一個容易混淆的文檔差異

錯誤碼參考頁仍把 invalid_search_facets 的觸發條件之一寫成“分面屬性不在 filterableAttributes”。但 build_faceted_navigation / search-with-post / 中文官方文檔三個獨立來源一致說明當前實際行為是靜默忽略，invalid_search_facets 更對應 facets 參數本身類型非法（如傳了非陣列）。排查時以「靜默忽略」為準。

為什麼 UI 層最難排查

前端拿到 200 + 缺失的分面鍵，第一反應通常是查 CSS、渲染邏輯或數據格式，極少會想到 settings 聲明問題——這是該坑最高頻的原因。

The Fix（解決方案）

第一步：把缺失的分面屬性補進 filterableAttributes

curl -X PUT 'http://localhost:7700/indexes/books/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '["genres", "rating", "language"]'

第二步：等設置任務完成

設置更新是異步任務（返回 taskUid，type 為 settingsUpdate），會觸發該索引全量重建，耗時與數據量成正比。輪詢 GET /tasks/{taskUid} 直到 status: succeeded 再搜索，否則仍拿不到分面。

第三步：重發搜索請求

curl -X POST 'http://localhost:7700/indexes/books/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"q": "", "facets": ["genres", "rating", "language"]}'

現在 facetDistribution 中出現 rating（數值分面還會附帶 facetStats 的 min/max）。

排查順序建議

• 先 GET /indexes/{uid}/settings/filterable-attributes 核對聲明列表。
• 再核對 facets 請求裡的屬性拼寫（大小寫、嵌套字段點號如 specs.language）。
• 最後才是檢查前端渲染邏輯。
• 快速自檢技巧：facets 傳 ["*"] 請求全部 filterable 分面，能立刻區分“屬性沒聲明”還是“前端沒渲染”。
• 另一個“看起來缺失”的原因：facetDistribution 預設每個分面最多返回 100 個值（faceting.maxValuesPerFacet），值太多時 UI 會顯得不全，與靜默忽略無關。

References（參考來源）

• Build faceted navigation — Meilisearch 官方文檔meilisearch-docs
• Search with POST API — Meilisearch 官方文檔meilisearch-docs
• Search API — Meilisearch 中文官方文檔meilisearch-docs-cn