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