OpenSearch 加了篩選條件後分面計數只剩一個：query 與 post_filter 的區別

搜索結果頁的分面計數突然只剩被選中的那一項，通常是把篩選條件寫進了 query：聚合的作用域就是 query 命中的文檔集，過濾完再統計，其他選項自然歸零。把同一個條件挪到 post_filter，聚合在過濾之前計算，hits 只剩 1 條而分面仍顯示 drama 3 / documentary 1。這是官方 faceted search 教程推薦的「保留分面選項」做法。適用 OpenSearch 2.x / 3.x，本文對 3.9.0 校驗。

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

業務場景：movies 索引裡有 5 條電影（drama 3、scifi 1、documentary 1），結果頁做了 genre 分面。用戶點選「scifi」之後，本來期望看到「drama 3、documentary 1」仍然可選，實際只剩一個 scifi: 1，等於失去了切換篩選的能力。
環境：OpenSearch 3.9.0，Docker 單節點，索引 movies（1 主分片、0 副本），genre 是 keyword。
關鍵區分：不是聚合寫錯了，也不是數據少了。兩次請求的 hits 都是 1 條，差別只在 aggregations 的桶——一個只剩 scifi，一個保留全集。

StackTrace（兩次響應對比）

同一份數據、同一個篩選條件，先寫進 query：

{
  "hits": { "total": { "value": 1, "relation": "eq" } },
  "aggregations": {
    "by_genre": {
      "buckets": [
        { "key": "scifi", "doc_count": 1 }
      ]
    }
  }
}

再寫進 post_filter：

{
  "hits": { "total": { "value": 1, "relation": "eq" } },
  "aggregations": {
    "by_genre": {
      "buckets": [
        { "key": "drama", "doc_count": 3 },
        { "key": "scifi", "doc_count": 1 },
        { "key": "documentary", "doc_count": 1 }
      ]
    }
  }
}

hits 一樣，分面一個塌了、一個沒塌。這就是全部現象。

Reproduce（復現程式碼）

前提：movies 索引已建好並導入 5 條文檔，步驟與示例值見從零跑通 OpenSearch 本地搜索服務。

把篩選寫進 query：

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "query": { "term": { "genre": "scifi" } },
    "aggs": { "by_genre": { "terms": { "field": "genre" } } }
  }'

回到 aggregations.by_genre.buckets 看：只有一個 scifi 桶。

換成 post_filter：

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "post_filter": { "term": { "genre": "scifi" } },
    "aggs": { "by_genre": { "terms": { "field": "genre" } } }
  }'

這次三個桶都在，drama 仍是 3。

判定標準：兩次請求的 hits.total.value 都是 1，但前者的桶只有 1 個、後者有 3 個，即復現成功。把 size 設成 0 是為了只看聚合；要同時看命中列表就去掉 size。

Root Cause（根因分析）

聚合的作用域是 query 命中的文檔集

一次 _search 的執行順序可以粗分為：先用 query 篩出文檔集 → 在這個集合上跑 aggs → 返回 hits 和 aggregations。篩選條件寫進 query，文檔集在聚合之前就被縮到 1 條，terms 只能在這個子集裡數數，其他類型的桶連生成的機會都沒有。

post_filter 是「最後一道閘」

post_filter 的位置在聚合之後、返回 hits 之前。官方 faceted search 教程對此的表述是：post_filter 在聚合計算完成之後再過濾搜索結果，因此分面反映的是未過濾的數據集。用它實現「選了紅色 T 恤，顏色分面仍顯示紅、藍、其他全部顏色」，正是結果頁需要的交互。

query 與 post_filter 的取捨

寫進 query：參與相關性打分，聚合跟著收窄。適合「這個條件就是搜索意圖的一部分」，比如用戶輸入的關鍵詞。
寫進 post_filter：不參與打分，只裁 hits。適合「用戶在結果頁上追加的篩選」，這樣分面才能保留全集計數。
想看「選中某個類型後，其他維度還剩多少」（例如選了 scifi，再看每個年份區間有幾部），用 filter 聚合：它生成一個獨立桶，桶內子聚合只在該子集上計算，不影響外層的其他分面。

The Fix（解決方案）

方案一：結果頁篩選一律走 post_filter

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "post_filter": { "term": { "genre": "scifi" } },
    "aggs": {
      "by_genre": { "terms": { "field": "genre" } },
      "by_year":  { "terms": { "field": "year" } }
    }
  }'

兩個分面都保持全集口徑，用戶在任何時候都能看到「切到別的類型還有多少條」。

方案二：需要「條件內統計」時用 filter 聚合

如果某個分面的數字本來就該跟著篩選變（比如「當前選中的類型下，各年份的分佈」），把它包進 filter 聚合，不要改全局 query：

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "aggs": {
      "all_genres": { "terms": { "field": "genre" } },
      "scifi_years": {
        "filter": { "term": { "genre": "scifi" } },
        "aggs": { "years": { "terms": { "field": "year" } } }
      }
    }
  }'

all_genres 是全集口徑，scifi_years 是子集口徑，一次請求拿到兩套數字。

注意事項

post_filter 隻影響 hits，不會讓 aggregations 變窄，也不會改變相關性得分。
關鍵詞搜索仍然寫在 query 裡；post_filter 是給結果頁追加的篩選留的位置，兩者可以同時存在。
每次請求都帶 size: 0 時看不到 hits，驗證分面時夠用；要看列表就設正常的 size。
filter 聚合與 post_filter 不是二選一：前者決定「哪些統計跟著子集走」，後者決定「列表要不要裁」。
聚合本身怎麼寫，見從零跑通 OpenSearch 聚合與分面。

References（參考來源）

Faceted search — OpenSearch 官方教程opensearch-docs
Filter aggregation — OpenSearch 官方文檔opensearch-docs
Aggregations — OpenSearch 官方文檔opensearch-docs