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