Painless 腳本語言 · Elasticsearch 5.4 中文文檔

# Painless 腳本語言原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/5.3/modules-scripting-painless.html](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/modules-scripting-painless.html) 譯文鏈接 : [http://www.apache.wiki/pages/viewpage.action?pageId=10027215](http://www.apache.wiki/pages/viewpage.action?pageId=10027215) 貢獻者 : [@琴劍藍天](http://www.apache.wiki/users/viewuserprofile.action?username=xujie)，[ApacheCN](/display/~apachecn)，[Apache中文網](/display/~apachechina) _Painless_ 腳本語言是新的，仍然被標記為實驗性語言。如果需要，語法或API可能會以非向后兼容的方式在將來更改。 _Painless_ 是默認情況下 _Elasticsearch_ 中提供的一種簡單，安全的腳本語言。它專門設計用于 _Elasticsearch_，可以安全地使用內聯和存儲的腳本，默認情況下啟用。? _Painless_ 語法類似于 [_Groovy_](http://groovy-lang.org/index.html)。您可以在任何地方使用 _Painless_ 來在 _Elasticsearch_ 中使用腳本。如果您不設置lang參數是默認值，但如果要顯式，則可以將lang參數設置為 _Painless_ 。 ## _Painless_ 功能 * 性能快：比替代品快幾倍。 * 安全：具有方法調用/字段粒度的細粒度白名單。有關可用類和方法的完整列表，請參見[附錄A“_Painless_ API參考”](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/painless-api-reference.html)。 * 可選輸入：變量和參數可以使用顯式類型或動態def類型。 * 語法：使用Groovy的子集擴展Java的語法，以方便使用。請參閱[語法概述](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/modules-scripting-painless-syntax.html)。 * 優化：專為 _Elasticsearch_ 腳本而設計。 ## _Painless_ 示例為了說明 _Painless_ 如何工作，我們將一些曲棍球統計數據加載到一個Elasticsearch索引中： ``` PUT hockey/player/_bulk?refresh {"index":{"_id":1}} {"first":"johnny","last":"gaudreau","goals":[9,27,1],"assists":[17,46,0],"gp":[26,82,1],"born":"1993/08/13"} {"index":{"_id":2}} {"first":"sean","last":"monohan","goals":[7,54,26],"assists":[11,26,13],"gp":[26,82,82],"born":"1994/10/12"} {"index":{"_id":3}} {"first":"jiri","last":"hudler","goals":[5,34,36],"assists":[11,62,42],"gp":[24,80,79],"born":"1984/01/04"} {"index":{"_id":4}} {"first":"micheal","last":"frolik","goals":[4,6,15],"assists":[8,23,15],"gp":[26,82,82],"born":"1988/02/17"} {"index":{"_id":5}} {"first":"sam","last":"bennett","goals":[5,0,0],"assists":[8,1,0],"gp":[26,1,0],"born":"1996/06/20"} {"index":{"_id":6}} {"first":"dennis","last":"wideman","goals":[0,26,15],"assists":[11,30,24],"gp":[26,81,82],"born":"1983/03/20"} {"index":{"_id":7}} {"first":"david","last":"jones","goals":[7,19,5],"assists":[3,17,4],"gp":[26,45,34],"born":"1984/08/10"} {"index":{"_id":8}} {"first":"tj","last":"brodie","goals":[2,14,7],"assists":[8,42,30],"gp":[26,82,82],"born":"1990/06/07"} {"index":{"_id":39}} {"first":"mark","last":"giordano","goals":[6,30,15],"assists":[3,30,24],"gp":[26,60,63],"born":"1983/10/03"} {"index":{"_id":10}} {"first":"mikael","last":"backlund","goals":[3,15,13],"assists":[6,24,18],"gp":[26,82,82],"born":"1989/03/17"} {"index":{"_id":11}} {"first":"joe","last":"colborne","goals":[3,18,13],"assists":[6,20,24],"gp":[26,67,82],"born":"1990/01/30"} ``` ## _使用 Painless 獲取文檔值 _ 可以以Map命名的文檔訪問文檔值。? 例如，以下腳本計算玩家的總目標。此示例使用強類型的int和for循環。 ``` GET hockey/_search { "query": { "function_score": { "script_score": { "script": { "lang": "painless", "inline": "int total = 0; for (int i = 0; i < doc['goals'].length; ++i) { total += doc['goals'][i]; } return total;" } } } } } ``` 或者，您可以使用腳本字段而不是功能分數來做同樣的事情： ``` GET hockey/_search { "query": { "match_all": {} }, "script_fields": { "total_goals": { "script": { "lang": "painless", "inline": "int total = 0; for (int i = 0; i < doc['goals'].length; ++i) { total += doc['goals'][i]; } return total;" } } } } ``` 以下示例使用 _Painless_ 腳本通過組合的名字和名字對播放器進行排序。使用 _doc ['first'].value_ 和 doc ['last'].value 訪問這些名稱。 ``` GET hockey/_search { "query": { "match_all": {} }, "sort": { "_script": { "type": "string", "order": "asc", "script": { "lang": "painless", "inline": "doc['first.keyword'].value + ' ' + doc['last.keyword'].value" } } } } ``` ### 用 _Painless 更新字段_ _您也可以輕松更新字段。您訪問一個字段的原始源為 `ctx._source.<field-name>`. _ _首先，我們通過提交以下請求來查看播放器的源數據：_ ``` GET hockey/_search { "stored_fields": [ "_id", "_source" ], "query": { "term": { "_id": 1 } } } ``` __要將玩家1的姓氏更改為曲棍球，只需將 `ctx._source.last` 設置為新值即可：__ ``` POST hockey/player/1/_update { "script": { "lang": "painless", "inline": "ctx._source.last = params.last", "params": { "last": "hockey" } } } ``` __您還可以向文檔添加字段。例如，此腳本添加了一個包含播放器昵稱，曲棍球的新字段__ ``` POST hockey/player/1/_update { "script": { "lang": "painless", "inline": "ctx._source.last = params.last; ctx._source.nick = params.nick", "params": { "last": "gaudreau", "nick": "hockey" } } } ``` ### 正則表達式日期與常規值有所不同。這是一個返回每個玩家誕生年份的例子： ``` GET hockey/_search { "script_fields": { "birth_year": { "script": { "inline": "doc.born.date.year" } } } } ``` 這里的關鍵是不能直接編入 _`doc.born`_，就像您正常的字段，你必須調用 _doc.born.date_ 來獲取一個 _ReadableDateTime_ 。從那里可以調用 _getYear_ 和 _getDayOfWeek_ 等方法。在上面的例子中，_getYear()_ 的一個快捷方式。? 如果日期字段是列表，那么日期將始終返回第一個日期。要訪問所有日期，請使用 _dates_ 而不是 _date_。 ### 正則表達式默認情況下，正則表達式被禁用，因為它們規避了 _Painless_ 對長時間運行和內存饑餓腳本的保護。更糟糕的是，即使 _Painless_ 的正則表達式也可以具有令人吃驚的性能和堆棧深度行為。它們仍然是一個驚人的強大工具，但是在默認情況下太可怕了。要使他們自己設置_script.painless.regex.enabled：true_ 在elasticsearch.yml中。我們非常希望有一個安全的替代實現，默認情況下可以啟用，所以檢查這個空間以備以后的開發！ Painless對正則表達式的本機支持具有語法結構： * / pattern /：模式文字創建模式。這是創造無痛模式的唯一途徑。 `/`中的模式只是[Java正則表達式](http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)。有關更多信息，請參閱“[模式標志](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/modules-scripting-painless-syntax.html#modules-scripting-painless-regex-flags)”一節。 * =?：find運算符返回一個布爾值，如果文本的子序列匹配則為true，否則為false。 * ==?：匹配運算符返回一個布爾值，如果文本匹配則返回true，否則返回false。 ?使用 _find_ 操作符（=?），您可以用“b”更新所有曲棍球選手： ``` POST hockey/player/_update_by_query { "script": { "lang": "painless", "inline": "if (ctx._source.last =~ /b/) {ctx._source.last += \"matched\"} else {ctx.op = 'noop'}" } } ``` 使用匹配運算符（==?），您可以更新名稱以輔音開頭的所有曲棍球運動員，并以元音結尾： ``` POST hockey/player/_update_by_query { "script": { "lang": "painless", "inline": "if (ctx._source.last ==~ /[^aeiou].*[aeiou]/) {ctx._source.last += \"matched\"} else {ctx.op = 'noop'}" } } ``` 您可以直接使用 _Pattern.matcher_ 獲取 _Matcher_ 實例，并刪除其所有姓氏中的所有元音： ``` POST hockey/player/_update_by_query { "script": { "lang": "painless", "inline": "ctx._source.last = /[aeiou]/.matcher(ctx._source.last).replaceAll('')" } } ``` _Matcher.replaceAll_ 只是調用 _Java Matcher replaceAll_ 方法，所以它支持 _$1_ 和 _\1_ 替換： ``` POST hockey/player/_update_by_query { "script": { "lang": "painless", "inline": "ctx._source.last = /n([aeiou])/.matcher(ctx._source.last).replaceAll('$1')" } } ``` 如果需要更多的替代控件，您可以使用構建替換的?_`Function<Matcher, String>`_ 調用 _CharAequence_ 上的 _replaceAll_ 。這不支持_$1_ 和 _\1_ 訪問替換，因為您已經有了匹配器的引用，可以使用 _m.group(1) 獲取它們。_ 在構建替換的函數內調用 Matcher.find 是粗魯的，并且可能會破壞替換過程。 _這將使曲棍球運動員姓氏中的所有元音大寫:_ ``` POST hockey/player/_update_by_query { "script": { "lang": "painless", "inline": "ctx._source.last = ctx._source.last.replaceAll(/[aeiou]/, m -> m.group().toUpperCase(Locale.ROOT))" } } ``` _或者您可以使用 CharSequence.replaceFirst 將其第一個元音以大寫字母表示：_ ``` POST hockey/player/_update_by_query { "script": { "lang": "painless", "inline": "ctx._source.last = ctx._source.last.replaceFirst(/[aeiou]/, m -> m.group().toUpperCase(Locale.ROOT))" } } ``` _注意：上面所有的 _update_by_query 示例可能真的可以用查詢來限制他們拉回的數據。雖然您可以使用腳本查詢，但它不會像使用任何其他查詢一樣有效，因為腳本查詢不能使用反向索引來限制他們必須檢查的文檔。_ ### ?_painless_ 調度功能 _Painless_ 使用接收器，名稱和方法進行方法調度。例如，通過首先獲取 _s_ 的類，然后用兩個參數查找方法 _foo_ 來解決 _s.foo(a,b)_ 。這與使用參數的[運行時類型](https://en.wikipedia.org/wiki/Multiple_dispatch)的Groovy和使用編譯時類型的參數的Java不同。? 這樣做的結果是，_Painless_ 不支持像Java這樣的重載方法，當從Java標準庫中將類列入白名單時，會導致一些麻煩。例如，在Java和Groovy中，Matcher有兩種方法：_group(int)_ 和 _group(String)_。_Painless_ 無法將這兩種方法列入白名單，因為它們具有相同的名稱和相同數量的參數。因此，它具有 _group__(int)_ 和 _namedGroup__(String)_。? 我們對這種不同的調度方法有幾個理由： ? 1. 它使 _def_ 類型的操作更簡單，可能更快。使用接收器，名稱和數量意味著當 _Painless_ 看到對def對象的調用時，它可以調度適當的方法，而不必對參數類型進行昂貴的比較。對于使用def類型參數的調用也是如此。 2. 它保持一致。如果涉及到def類型的參數和Java，否則 _Painless_ 的行為就像Groovy一樣真的很奇怪。它總是像Groovy一樣慢一點。 3. 它保持 _Painless_ 可維護。添加Java或Groovy的方法調度感覺就像添加了一大堆復雜性，使維護和其他改進更加困難。