Search 模板 · Elasticsearch 5.4 中文文檔

# Search 模板原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/5.0/search-template.html](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/search-template.html) 譯文鏈接 : [http://www.apache.wiki/display/Elasticsearch](http://www.apache.wiki/display/Elasticsearch) 貢獻者 : @Josh **/_search/template endpoint?**允許我們在執行搜索請求和使用模板參數填充現有模板之前，能夠使用?**mustache**?語言預先呈現搜索請求。 ``` GET /_search/template { "inline" : { "query": { "match" : { "{{my_field}}" : "{{my_value}}" } }, "size" : "{{my_size}}" }, "params" : { "my_field" : "foo", "my_value" : "bar", "my_size" : 5 } } ``` 關于 **Mustache templating** 以及你可以使用哪種模板，請參考 [mustache 項目在線文檔](http://mustache.github.io/mustache.5.html)。 **NOTE:** 在 **elasticsearch** 中實現的 **mustache** 語言是作為一種沙箱(**sandboxed**) 腳本語言，因此它遵守相關設置，這些設置可能是為了啟用或禁用 [腳本文檔](http://apache.wiki/display/Elasticsearch/Scripting)?中描述的每個語言、源和操作。 ## 更多的模板案例 ### 使用單個值填充查詢字符串 ``` GET /_search/template { "inline": { "query": { "match": { "title": "{{query_string}}" } } }, "params": { "query_string": "search for these words" } } ``` ### 將參數轉換為 **JSON** **{{#toJson}}parameter{{/toJson}} **函數可以用來轉換參數（比如 maps 和 array）為它們的 JSON 形式。 ``` GET /_search/template { "inline": "{ \"query\": { \"terms\": { \"status\": {{#toJson}}status{{/toJson}} }}}", "params": { "status": [ "pending", "published" ] } } ``` 其呈現為： ``` { "query": { "terms": { "status": [ "pending", "published" ] } } } ``` 更復雜的例子代替一個 **JSON** 對象數組： ``` { "inline": "{\"query\":{\"bool\":{\"must\": {{#toJson}}clauses{{/toJson}} }}}", "params": { "clauses": [ { "term": "foo" }, { "term": "bar" } ] } } ``` 呈現為： ``` { "query" : { "bool" : { "must" : [ { "term" : "foo" }, { "term" : "bar" } ] } } } ``` ### 連接值的數組 **{{#join}}array{{/join}}** 函數能用來將數組的值連接為以逗號分隔的字符串： ``` GET /_search/template { "inline": { "query": { "match": { "emails": "{{#join}}emails{{/join}}" } } }, "params": { "emails": [ "username@email.com", "lastname@email.com" ] } } ``` 其呈現為： ``` { "query" : { "match" : { "emails" : "username@email.com,lastname@email.com" } } } ``` 該函數還可以接受一個自定義分隔符： ``` GET /_search/template { "inline": { "query": { "range": { "born": { "gte" : "{{date.min}}", "lte" : "{{date.max}}", "format": "{{#join delimiter='||'}}date.formats{{/join delimiter='||'}}" } } } }, "params": { "date": { "min": "2016", "max": "31/12/2017", "formats": ["dd/MM/yyyy", "yyyy"] } } } ``` 呈現為： ``` { "query" : { "range" : { "born" : { "gte" : "2016", "lte" : "31/12/2017", "format" : "dd/MM/yyyy||yyyy" } } } } ``` ### 默認值默認值被寫成 **{{var}}{{^var}}default{{/var}}** 比如： ``` { "inline": { "query": { "range": { "line_no": { "gte": "{{start}}", "lte": "{{end}}{{^end}}20{{/end}}" } } } }, "params": { ... } } ``` 此時 **params** 是**{ "start": 10, "end": 15 }** ，該查詢可以呈現為： ``` { "range": { "line_no": { "gte": "10", "lte": "15" } } } ``` 但是，當 **params** 是**{ "start": 10 }** 時，該查詢就會使用默認值作為 **end** : ``` { "range": { "line_no": { "gte": "10", "lte": "20" } } } ``` ### 條件語句條件語句不能使用模板的 **JSON** 形式表示。相反，模板必須作為字符串傳遞。例如，假設我們想在 **line** 字段上運行 **match** 查詢，并且可以選擇用行號過濾其中 **start** 和 **end** 是可選的。參數（params）會像這樣： ``` { "params": { "text": "words to search for", "line_no": { ① "start": 10, ② "end": 20 ③ } } } ``` ① 所有這三個元素都是可選的。 ②? ③ 查詢語句我們可以是： ``` { "query": { "bool": { "must": { "match": { "line": "{{text}}" ① } }, "filter": { {{#line_no}} ② "range": { "line_no": { {{#start}} ③ "gte": "{{start}}" ④ {{#end}},{{/end}} ⑤ {{/start}} ⑥ {{#end}} ⑦ "lte": "{{end}}" ⑧ {{/end}} ⑨ } } {{/line_no}} ⑩ } } } } ``` ① 填充 **text** 參數值。 ② 僅當指定 **line_no**?時才能包含 **range** 過濾器。 ③ 僅當指定了**line_no.start** 時才能包含 **gte** 子句。 ④ 填充 **line_no.start** 參數值。 ⑤ 僅當 **line_no.start** 和 **line_no.end** 被指定時，在 **gte** 子句后添加逗號。 ⑦ 僅當指定 **line_no.end** 時，包含 **lte** 子句。 ⑨ ⑩ 填充 **line_no.end** 參數值。注意如上所述，模板不是有效的 **JSON** 形式，因為它包含類似的部分標記，因此，模板應存儲在文件中（參考 [預注冊模板](http://apache.wiki/pages/viewpage.action?pageId=4882772) 一節）或者在通過 **REST API** 使用時，應該將其寫成字符串格式，比如： ``` "inline": "{\"query\":{\"bool\":{\"must\":{\"match\":{\"line\":\"{{text}}\"}},\"filter\":{{{#line_no}}\"range\":{\"line_no\":{{{#start}}\"gte\":\"{{start}}\"{{#end}},{{/end}}{{/start}}{{#end}}\"lte\":\"{{end}}\"{{/end}}}}{{/line_no}}}}}}" ``` ### 預注冊（Pre-registered）模板你可以通過將搜索模板存儲在 **config/scripts** 目錄中，在使用 **.mustache** 擴展名的文件中注冊搜索模板。為了執行存儲的模板，請使用 **template** 鍵下單名稱來引用它： ``` GET /_search/template { "file": "storedTemplate", ① "params": { "query_string": "search for these words" } } ``` ① **config/sripts/** 查詢模板的名稱，即： ?**?`storedTemplate.mustache`.** 你還可以通過將搜索模板存儲在集群狀態中來注冊搜索模板，由 **REST API** 來管理這些索引的模板。 ``` POST /_search/template/<templatename> { "template": { "query": { "match": { "title": "{{query_string}}" } } } } ``` 該模板可以通過以下方法來檢查： ``` GET /_search/template/<templatename> ``` 其可以呈現為： ``` { "template": { "query": { "match": { "title": "{{query_string}}" } } } } ``` 這個模板可以被刪除： ``` DELETE /_search/template/<templatename> ``` 在搜索時使用索引模板，使用： ``` GET /_search/template { "id": "templateName", ① "params": { "query_string": "search for these words" } } ``` ①?存儲在 **.scripts** 索引中的查詢模板的名稱。 ### 驗證（Validating）模板 ``` 可以在具有給定參數的響應中使用來呈現模板： ``` ``` GET /_render/template { "inline": { "query": { "terms": { "status": [ "{{#status}}", "{{.}}", "{{/status}}" ] } } }, "params": { "status": [ "pending", "published" ] } } ``` 次調用將返回呈現的模板： ``` { "template_output": { "query": { "terms": { "status": [ ① "pending", "published" ] } } } } ``` ① status 數據已使用來自 params 對象的值填充。 ``` 文件和索引模板也可以通過分別用 file 或 id 代替 inline 來呈現。例如，呈現文件模板： ``` ``` GET /_render/template { "file": "my_template", "params": { "status": [ "pending", "published" ] } } ``` 預注冊模板可以使用以下呈現： ``` GET /_render/template/<template_name> { "params": { "..." } } ```