OpenSearch function_score 忘寫 query 返回全庫（match_all）

用 function_score 想給熱門電影加權，忘了寫頂層 query，結果請求把 movies 索引裡的文檔全返回了，每篇分數還都差不多。根因是 function_score 省略 query 時內部走 match_all，每篇文檔的 base score 都是 1。給 function_score 寫顯式 query，或外層套 bool 的 filter 把範圍卡住。適用 OpenSearch 3.x。

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

業務場景：接著從零跑通 OpenSearch 本地搜索服務的 movies 索引（5 條電影）。想「按年份越新排越前」，用 function_score 的 field_value_factor 對 year 加權，卻忘了寫 query。結果不僅 5 條全回來了，連本不該命中的 Deep Sea Chronicles、Windmill Valley 也躺進了結果裡。
環境：OpenSearch 3.x（Docker latest 鏡像），單節點，索引 movies，security 插件開啟。
關鍵區分：沒報錯、分數也算出來了，但「命中範圍」不對——本來只想對「匹配了關鍵詞的文檔」加權，結果變成對「整個索引」加權。

StackTrace（現象：全庫命中 + base score 為 1）

省略頂層 query 的返回體，total 是全部 5 條，每條 _score 都被 field_value_factor 從 base 1 重新算成接近 1 的值：

{
  "hits": {
    "total": { "value": 5, "relation": "eq" },
    "max_score": 2.021,
    "hits": [
      { "_id": "3", "_score": 2.021, "_source": { "title": "The Rise of Machines", "year": 2021, "genre": "scifi" } },
      { "_id": "1", "_score": 1.013, "_source": { "title": "Let the Wind Rise", "year": 2013, "genre": "drama" } },
      { "_id": "2", "_score": 0.939, "_source": { "title": "Gone with the Wind", "year": 1939, "genre": "drama" } }
    ]
  }
}

total 是 5，而不是「匹配了某個關鍵詞」的那幾條——因為這個請求壓根沒有關鍵詞過濾。

Reproduce（復現程式碼）

錯誤的寫法——function_score 裡只有 functions，沒有頂層 query：

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "function_score": {
        "functions": [
          { "field_value_factor": { "field": "year", "modifier": "log1p" } }
        ],
        "boost_mode": "multiply"
      }
    }
  }'

對照正確寫法——function_score 內補上 query：

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "function_score": {
        "query": { "match": { "title": "wind rise" } },
        "functions": [
          { "field_value_factor": { "field": "year", "modifier": "log1p" } }
        ],
        "boost_mode": "multiply"
      }
    }
  }'

判定標準：第一個請求 total 是 5（全庫）；第二個請求 total 是 3（只命中 wind rise 相關的三條），即說明 query 的作用。

Root Cause（根因分析）

function_score 省略 query 時，預設是 match_all

function_score 不是獨立的打分器，它是「一個查詢 + 一套改分函數」的包裝。它的頂層 query 決定了「哪些文檔先被命中」，functions 決定「命中的這些文檔分數怎麼改」。官方 Function score query 文檔寫得很直接：If you omit the top-level query parameter, function_score runs on match_all, so every document in the index matches and receives a base query score of 1.

於是省略 query 後，match_all 讓全庫每篇文檔都以 base score 1 進入 functions，再被你寫的 field_value_factor 統一重算——結果就是「全庫命中、分數全是 1.0 附近」。

這是「改怎麼排」還是「改返回哪些」的邊界被搞混了

function_score 的職責是「讓已命中的文檔重新排序」，不是「決定哪些文檔命中」。決定命中範圍的永遠是 query（或外層 bool）。把它當成了能自動限定範圍的工具，才會寫出只有 functions、沒有 query 的請求。

The Fix（解決方案）

方案一：function_score 內寫顯式 query（首選）

在 function_score 裡補上 query，讓「命中範圍」和「改分函數」各司其職：

curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "function_score": {
        "query": { "match": { "title": "wind rise" } },
        "functions": [
          { "field_value_factor": { "field": "year", "modifier": "log1p" } }
        ],
        "boost_mode": "multiply"
      }
    }
  }'

方案二：只對某類文檔加權，用 functions 裡的 filter

如果意圖是「只給滿足某條件的文檔加權、其他文檔分數不動」，就把條件寫進 functions 裡每個 function 的 filter——{ "filter": { "term": { "genre": "drama" } }, "weight": 2 }。這樣命中的文檔裡，drama 的被加權，非 drama 的走原分數。

注意事項

判斷請求有沒有「命中範圍」：看 query 是否顯式給了 match / bool / term 等。只有 functions 而沒有 query，就等同於 match_all。
加權的正確心智模型：query 定「哪些文檔進來」，functions 定「進來的文檔分數怎麼改」。先想清楚前者，再寫後者。
想同時「限定範圍 + 加權」，優先用 function_score { query + functions }；需要多個獨立改分規則時，再往 functions 的每個 function 里加 filter。
配合 explain API 看最終 _score 裡 match_all 的 base 分是 1，能一眼判斷出「是不是忘了寫 query」。

References（參考來源）

Function score query — OpenSearch 官方文檔opensearch-docs