Meilisearch filter+sort 组合报 invalid_search_sort

同一请求同时传 filter 和 sort 时，如果排序用的属性没有在索引 sortableAttributes 设置中声明，返回 HTTP 400，错误码 invalid_search_sort。filter 用的是 filterableAttributes、sort 用的是 sortableAttributes，两套列表相互独立——filter 正常不代表能 sort。解法：把排序属性加入 sortableAttributes（必要时与 filterable 同时声明），等设置任务完成后重搜。适用 Meilisearch 全版本。

Issue & Env（案发现场与环境）

• 业务场景：filterableAttributes 已声明 genres、release_date，不带 sort 的 filter 查询完全正常。在同一个请求加上 "sort": ["rating:desc"] 后，返回 400 Bad Request，错误码 invalid_search_sort。rating 只作为普通字段存在于文档里，从未加入任何 settings 列表。
• 环境：Meilisearch v1.54.3，curl / 任意 SDK 均可复现。
• 关键区分：filter 与 sort 的声明机制相互独立。报 invalid_search_sort 也可能来自 sort 语法错误或 rankingRules 缺 sort 规则，但最常见、最先要查的是排序属性未在 sortableAttributes 声明。
• 典型触发：电商/榜单类页面的“按评分排序”“按价格排序”下拉，用户点了排序后，后端在 filter 基础上拼上 sort 就返回 400——评分、价格这些字段明明存在于文档里，却从未进过任何 settings 列表。

StackTrace（堆栈日志）

错误码参考页对 invalid_search_sort 的触发条件描述原文：

This error occurs if:

• The syntax for the sort parameter is invalid
• The attribute used for sorting is not defined in the sortableAttributes list or the sort ranking rule is missing from the settings
• A reserved keyword like _geo, _geoDistance, _geoRadius, or _geoBoundingBox is used as a filter

官方规范（specs 0061）中 invalid_search_sort 的错误响应（“对不可排序属性排序”变体）：

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

sortableAttributes 为空时，message 有另一种变体：

{
    "message": "Attribute `rating` is not sortable. This index does not have configured sortable attributes.",
    "code": "invalid_search_sort",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#invalid_search_sort"
}

以上均为 HTTP 400 同步返回。

Reproduce（复现代码）

# 1. 只声明了 filterableAttributes，没声明 sortableAttributes
curl -X PATCH 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"filterableAttributes": ["genres", "release_date"]}'

# 2. filter + sort 组合搜索——报错
curl -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"q": "", "filter": "genres = Action", "sort": ["rating:desc"]}'

# 返回 400:
# {"message": "Attribute `rating` is not sortable. Available sortable attributes are: ``.", "code": "invalid_search_sort", ...}

Root Cause（根因分析）

filter 与 sort 是两套独立的前置声明

Meilisearch 的 filter 和 sort 各自要求属性进入对应设置列表，两者不互通。官方 combine filters and sort 指南原文：

Fields used in filter must be in filterableAttributes; fields used in sort must be in sortableAttributes.

sortableAttributes 默认是空数组，不声明任何排序属性时，任何带 sort 的请求都会报 invalid_search_sort。一个字段可以同时出现在两个列表（如 filterableAttributes: ["genres", "release_date"]、sortableAttributes: ["rating", "release_date"]），也可以只出现在其中一个。

“filter 与 sort 冲突”的常见误判

很多人以为加了 sort 导致 filter 失效，实际是 sort 侧的属性未声明，filter 本身没有问题。报错指向的是 sort 的校验，不是 filter。

声明是异步任务

sortableAttributes 的更新同样是异步的（返回 taskUid，type 为 settingsUpdate），并触发该索引全量重建。任务还在 enqueued/processing 时搜索，仍会报 not sortable。

为什么排序也必须提前声明

与 filter 同理，排序依赖为属性预建的内部数据结构：Meilisearch 在声明 sortableAttributes 后，为这些属性构建排序所需的列式索引，查询时直接读取，无法在搜索请求里临时为任意字段排序。把高成本操作前置到索引阶段，是 filter/sort/facet 三者的统一设计逻辑。

rankingRules 里的 sort 规则

默认 rankingRules 包含 sort 规则，sort 参数作为附加排名规则在文本相关度排序之后生效。若自定义 rankingRules 时把 sort 规则移除，即使属性声明正确，带 sort 的请求同样报 invalid_search_sort——这是同一错误码下第二常见的原因，且与属性声明无关，排查时别漏掉。

执行顺序

即使配置正确，也要注意：filter 先缩小结果集，再应用排序；与文本查询组合时，先按文本相关度 ranking rules 排序，sort 作为附加排名规则。

The Fix（解决方案）

第一步：把排序属性加入 sortableAttributes

curl -X PATCH 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{
    "filterableAttributes": ["genres", "release_date"],
    "sortableAttributes": ["rating", "release_date"]
  }'

也可用子路由单独设置：PUT /indexes/{uid}/settings/sortable-attributes，body 为字符串数组。

第二步：等设置任务完成

轮询 GET /tasks/{taskUid} 直到 status: succeeded，再搜索。

第三步：重发 filter + sort 请求

curl -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"q": "", "filter": "genres = Action", "sort": ["rating:desc"]}'

现在只返回 Action 电影，且按 rating 降序排列。

其他触发条件排查

• 先 GET /indexes/{uid}/settings/sortable-attributes 核对当前声明列表，避免凭记忆排查。
• sort 语法格式为 "属性名:asc|desc"（方向拼错属于语法错误，报错码相同）。
• 默认 rankingRules 已包含 sort 规则，一般不用动；若自定义了 rankingRules 把 sort 删掉，报错码也是 invalid_search_sort。
• 多属性排序：第二个属性作为 tiebreaker，如 ["rating:desc", "release_date:desc"]。
• 若同时需要过滤和排序同一字段，记得在 filterableAttributes 和 sortableAttributes 两个列表里都声明。

References（参考来源）

• Combine filters and sort — Meilisearch 官方文档meilisearch-docs
• Error codes — Meilisearch 官方文档meilisearch-docs
• Error Format and Definitions — Meilisearch 规范文档meilisearch-spec