# Function Score 查詢 原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/5.0/query-dsl-function-score-query.html](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/query-dsl-function-score-query.html) 譯文鏈接 : [http://www.apache.wiki/pages/viewpage.action?pageId=4882904](http://www.apache.wiki/pages/viewpage.action?pageId=4882904) 貢獻者 : [藍色飛揚](/display/~lixiaoqing) [<<?**Dis Max Query**](http://www.apache.wiki/pages/viewpage.action?pageId=4882902)**?? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ???[Boosting Query >>](http://www.apache.wiki/pages/viewpage.action?pageId=4882906)** * * * ## Function Score Query **function_score** 允許你修改一個查詢檢索文檔的分數。舉例來講，當得分函數計算代價高昂并且足以在經過濾的文檔集合上計算得分，這種查詢是有用的。 使用 **function_score** ，用戶需要定義一個查詢和一個或多個功能，即計算用于由查詢返回的每個文檔的新得分。 **function_score**? 當只有一個功能函數時可參考如下使用： ``` GET /_search { "query": { "function_score": { "query": { "match_all": {} }, "boost": "5", "random_score": {},//注釋1 "boost_mode":"multiply" } } } ``` ``` 注釋1:見 function_score 查詢有關支持的函數列表 ``` 此外，可以組合幾個函數使用。 假如要這樣使用，當且僅當文檔匹配給定的過濾查詢時可以根據需要選擇應用此函數。 ``` GET /_search { "query": { "function_score": { "query": { "match_all": {} }, "boost": "5", //注釋1 "functions": [ { "filter": { "match": { "test": "bar" } }, "random_score": {}, //注釋2 "weight": 23 }, { "filter": { "match": { "test": "cat" } }, "weight": 42 } ], "max_boost": 42, "score_mode": "max", "boost_mode": "multiply", "min_score" : 42 } } } ``` ``` 注釋1：意為整個查詢 ``` * * * 注釋2:見?**function_score**?查詢有關支持的函數列表 每個函數的過濾查詢產生的分數無關緊要。 如果函數中沒有給定濾器，這是等同于指定給"**_match_all_**": {} 首先，每個文檔由定義的函數打分。 參數?_**score_mode?**_規定計算的分數如何組合： | multiply | 分數相乘（默認） | | sum | 得分相加 | | avg | 平均分數 | | first | 使用具有匹配過濾器的第一個函數 | | max | 最大得分 | | min | 最小分數 | 因為分數可以在不同的尺度（例如使用除了?**field_value_factor?**之外的0和1的遞減函數 ），并且有時候函數的得分產生的不同影響正是所期望的，每個函數的分數可以由用戶定義的 **_weight_** 參數來調整，_**weight**_ 可以定義在每一個?**functions?**陣列（上面的例子）的功能,以此乘以由相應函數計算的分數。如果其他任何功能的聲明中沒有提到權重， **weight** 只是簡單的用于充當返回 **weight** 的函數 。 假如 **_score_mode_** 設為 **avg** 個人得分將由加權平均進行組合。 例如，如果兩個函數返回得分1和2以及它們各自的權重是3和4，那么他們的分數將被組合為(1*3+2*4)/(3+4)而不是 (1*3+2*4)/2 。 新得分通過設置 **max_boost** 參數可以不超過某一限值。**max_boost?**默認值是 **FLT_MAX**。 新計算的分數與查詢的分數相組合，參數 **boost_mode**?定義其組合方式： | **multiply** | 查詢得分和函數得分相乘（默認） | | **replace** | 僅使用函數得分，忽略查詢得分 | | **sum** | 查詢得分和函數得分相加 | | **avg** | 取平均值 | | **max** | 查詢得分和函數得分的最大值 | | **min** | 查詢得分和函數得分的最小值 | 默認情況下，修改分數不會改變文檔的匹配結果。 為了排除不滿足一定的分數閾值的文檔，可用**min_score**參數設置所期望的得分閾值。 **?function_score?**查詢提供的幾種函數分數的類型 * script_score * weight * random_score * field_value_factor * decay functions: gauss, linear, exp ## script_score **?script_score** 功能允許您包裝另一個查詢，即隨意定制用腳本表達式在doc其他數字字段的值派生的計算的得分。 下面是一個簡單的示例： ``` "script_score" : { "script" : { "lang": "painless", "inline": "_score * doc['my_numeric_field'].value" } } ``` 在上面這些不同的腳本字段值和表達式中，**_score** 腳本參數可被用于檢索基于該包裝查詢的分數。 腳本被緩存得以更快地執行。 如果腳本包含需要考慮的參數，則最好重復使用相同的腳本，并向其提供參數： ``` "script_score": { "script": { "lang": "painless", "params": { "param1": value1, "param2": value2 }, "inline": "_score * doc['my_numeric_field'].value / Math.pow(params.param1, params.param2)" } } ``` 需要注意的是與 **custom_score**?查詢不同，該查詢的評分是與腳本得分相乘的結果。如果要禁止此類用戶可增加設置"**boost_mode**": "**replace**" ## weight **weight?**得分即用分數乘以設置的?**weight ?**參數,當對特定查詢設置的提升值被標準化時，可使用此參數，但此參數對 **score function**?無效。其數值類型為**float**。 ``` "weight" : number ``` ## Random **?random_score** 根據 **__**ui**d_** 字段進行 **hash** 計算生成分數，可根據 **seed** 發生改變，如果 **_seed_** 未指定，當前時間被使用。 使用此功能將加載用于現場數據 **_uid** ，它的值唯一，適合在內存操作頻繁的情況下使用。 ``` "random_score": { "seed" : number } ``` ## field_value_factor **field_value_factor** 功能允許您使用從文檔獲取的字段影響得分。 它類似于使用 **script_score**?**function**，但是，它避免了腳本的開銷。 如果在多值字段上使用，則只有字段的第一個值用于計算。 舉個例子，假設你有一個在 **popularity** 域建有數字索引的文檔，并希望以此域影響該文檔的分數，通常采用如下方法： ``` "field_value_factor": { "field": "popularity", "factor": 1.2, "modifier": "sqrt", "missing": 1 } ``` 這將會轉換為以下公式來計算得分： sqrt(1.2 * doc['popularity'].value) 有以下一系列可選參數用于**field_value_factor** 功能 | field | 要從文檔中提取的字段。 | | factor | 與字段值相乘的可選系數，默認為1?。 | | modifier | 修改適用于該字段的值，可以是以下之一：?none?，?log?，?log1p?，?log2p?，?ln?，?ln1p?，ln2p?，?square?，?sqrt?，還是reciprocal?。?默認為none?。 | | 修飾符 | 含義 | | none | 不要對字段值使用任何乘數 | | log | 取字段值的[對數](https://en.wikipedia.org/wiki/Logarithm)[](https://translate.googleusercontent.com/translate_c?depth=1&hl=zh-CN&rurl=translate.google.com.hk&sl=en&tl=zh-CN&u=https://en.wikipedia.org/wiki/Logarithm&usg=ALkJrhh3MUvWC89n1nR7Lo0hKyZsLxwcHw) | | log1p | 字段值加1，并取對數 | | log2p | 字段值加2，并取對數 | | ln | 取字段值的[自然對數](https://en.wikipedia.org/wiki/Natural_logarithm) | | ln1p | 字段值加1，并取自然對數 | | ln2p | 字段值加2，并取自然對數 | | square | 字段值的平方（乘以它自身） | | sqrt | 字段值的[平方根](https://en.wikipedia.org/wiki/Square_root) | | reciprocal | 字段值的[Reciprocate](https://en.wikipedia.org/wiki/Multiplicative_inverse)形式，例如1/x?，其中x是該字段的值 | **missing** 如果文檔沒有該字段，則使用此值。 修飾符和因子也使用此值，如同從文檔中讀取的字段一樣使用。 記住，取log()為0，或者負數的平方根 是一個非法操作，程序會拋出異常。 一定要使用范圍過濾器限制此字段取值來避免這種情況，或使用`log1p`和 `ln1p`。 ## Decay functions **Decay functions** 對 最初用戶已給定了數字字段值的距離衰減函數的文檔進行計分。 這類似于**range query**，但具有滑動窗口而不是定值。 在具有數字字段的查詢使用 **distance scoring**，用戶應為每個字段定義 **origin** 和 **scale?**。 **origin ?**需要定義從該計算距離的“中心點”，而 **scale** 來定義衰減程度。 **decay function** 指定用法為: ``` "DECAY_FUNCTION": { //注釋1 "FIELD_NAME": { //注釋2 "origin": "11, 12", "scale": "2km", "offset": "0km", "decay": 0.33 } } ``` | ``` 注釋1 ``` | DECAY_FUNCTION應從linear?，?exp?，gauss?中取值。 | | ``` 注釋2 ``` | 指定的字段值必須是數字，date或?geo-point | 在上面的例子中，該字段取值 **geo_point** 并且可初始化為地理區域的格式。在這種情況下，**scale** 和 **offset** 必須指定一個單位。 如果你的領域是一個 **date** ，您可以設置 **scale** 和 **offset** 為天、周，依此類推。 例： ``` "gauss": { "date": { "origin": "2013-09-17", //注釋1 "scale": "10d", "offset": "5d", //注釋2 "decay" : 0.5 //注釋3 } } ``` | ``` 注釋1 ``` | date format 的初始定義取決于在映射定義的 format。?如果不給定初始值，則使用當前時間。 | | ``` 注釋2 ``` | **offset** 和 **decay** 參數是可選參數。 | | ``` 注釋3 ``` | | **_origin_** | 用于計算距離的初始值。?必須按照數字字段存放數字，日期字段存放日期和 地理位置字段存放地理位置的方式指定。?必需包含 geo 和 numeric。?對于 date 默認為now?。?日期初始化可以使用算術形式（例如now-1h）。 | | **scale** | 需要給定所有類型。?定義從**origin** + **offset** 開始計算等于 **decay** 的分數的距離。 ?對于geo：可以定義為number+unit（1km，12m，...）。?默認單位為米。 ?對于date：可以定義為number+unit（“1h”，“10d”，...）。?默認單位為 毫秒。?對于numeric：任意數字 | | **_offset_** | 如果定義了**offset**，則將使用比 **offset ?**更大的距離來計算文檔的衰變函數。默認值為0。 | | **_decay_** | **decay** 參數定義了根據 **scale** 給定的距離如何給文檔打分?。?如果沒有定義 **decay** ，文件計算距離時 **scale** 取值0.5。 | | 在第一個示例中，您的文檔可能代表酒店，并包含地理位置字段。 您想根據酒店距離給定位置的距離計算衰減函數。 您可能不會立即看到為gauss function選擇的scale，但您可以說：“在距離所需位置2公里處，分數應該減少到三分之一。 然后參數“scale”將自動調整以確保score function針對距離期望位置2km的酒店計算得分0.33。? 在第二個示例中，字段值介于2013-09-12和2013-09-22之間的文檔將獲得1.0的權重，并且從該日期起15天的文檔的權重為0.5。 ## Supported decay functions ?DECAY_FUNCTION 決定了衰減的形狀： **_gauss_** 正常衰減，計算公式為：  在這里 用于計算以確保該得分采用值 _**decay**_ 是 _**scale**_ 與 **_origin_** + - **_offset_** 的距離  見 [Normal decay ,關鍵字 gauss](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/query-dsl-function-score-query.html#gauss-decay) 的圖表展示了生成的曲線 _**gauss function**_。 **_exp_** 指數衰減，計算公式為：  再次指出參數用于計算以確保該得分采用值?_**decay**?_是?_**scale**?_與?**_origin_?**+ -?**_offset_?**的距離  見 [exponential decay ,關鍵字 exp](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/query-dsl-function-score-query.html#exp-decay) 為圖展示了生成的曲線 _**exp function**_。 **linear** 線性衰減，計算公式為：  在這里參數s用于計算以確保該得分采用值?_**decay**?_是?_**scale**?_與?**_origin_?**+ -?**_offset_?**的距離  與normal decay 和exponential decay ，如果字段值超過用戶給定的scale 值的兩倍，則此函數實際將分數設置為0 對于單個函數，三個decay functions及其參數的可視化形式如這樣（在該示例中的字段“age”）： **__** ## Multi-values fields 如果用于計算 **decay** 的字段包含多個值，則默認情況下選擇最接近原點的值以確定距離。 這可以通過設置 **_multi_value_mode_** 來改變 | min | 最小距離 | | max | 最大距離 | | avg | 平均距離 | | sum | 所有距離的總和 | 例： ``` “DECAY_FUNCTION”：{ “FIELD_NAME”：{ “origin”：...， “scale”：... }， “multi_value_mode”：“avg” }} ``` ## Detailed example 假設您正在搜索某個城鎮的酒店。 您的預算有限。 此外，您希望酒店靠近市中心，所以酒店距離所需的位置越遠，您就越不可能辦理入住手續。 您希望與您的標準（例如，“hotel，Nancy，non-smoker”）匹配的查詢結果相對于與市中心的距離以及價格進行評分。 直覺上，你想定義市中心為原點，也許你愿意從酒店步行2公里到市中心。 在這種情況下，您的 **scale** 字段初始值是市中心 ?2公里。 如果你的預算低，你可能更喜歡在昂貴的東西以上的東西。 對于價格，初始值是0歐元或者scale 取決于你愿意付出多少，例如20歐元。 在該示例中，字段可以被稱為酒店的價格的“price”和該酒店的坐標的“location”。 price函數在這種場景下定義為： ``` "gauss": { //注釋1 "price": { "origin": "0", "scale": "20" } } ``` 注釋1：此時?**decay function** 也可以使用 **linear** 或 **exp** **location** 定義為: ``` "gauss": { //注釋1 "location": { "origin": "11, 12", "scale": "2km" } } ``` 注釋1：此時?**decay function**?也可以使用?**linear**?或?**exp** 假設你想在原始分數上乘以這兩個函數，請求將如下所示: ``` GET /_search { "query": { "function_score": { "functions": [ { "gauss": { "price": { "origin": "0", "scale": "20" } } }, { "gauss": { "location": { "origin": "11, 12", "scale": "2km" } } } ], "query": { "match": { "properties": "balcony" } }, "score_mode": "multiply" } } } ``` 接下來，我們將展示三種可能衰變函數中的每一種的計算得分如何。 ## **Normal decay, keyword** gauss 當上面的例子中選擇 **gauss** 作為 **decay function**，乘法器的輪廓和表面積如下所示：   假設您的最初搜索結果與下面三家酒店相符： * "Backback Nap" * "Drink n Drive" * "BnB Bellevue". "Drink n Drive"距離你定義的位置（近2公里），不是太便宜（約13歐元），所以它得到一個低因素為0.56的因素。 “BnB Bellevue”和“Backback Nap”都非常接近定義的位置，但“BnB Bellevue”更便宜，所以它的乘數為0.86，而“Backpack Nap”的值為0.66 ## **Exponential decay, keyword** exp 當上面的例子中選擇 **exp** 作為 **decay function** ，乘法器的輪廓和表面積如下所示：   ## **Linear decay, keyword** linear 當上面的例子中選擇 **linear** 作為 **decay function** ，乘法器的輪廓和表面積如下所示：   ## 衰減函數支持的范圍 僅支持數字，日期和地理位置字段。 ## 缺少字段時如何處理？ 如果文檔中缺少數字字段，函數將返回1。 * * * [<<?**Dis Max Query**](http://www.apache.wiki/pages/viewpage.action?pageId=4882902) **[Boosting Query >>](http://www.apache.wiki/pages/viewpage.action?pageId=4882906)**