常見選項 · Elasticsearch 5.4 中文文檔

# 常見選項原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html) 譯文鏈接 : [http://www.apache.wiki/pages/viewpage.action?pageId=4882851](http://www.apache.wiki/pages/viewpage.action?pageId=4882851) 貢獻者 : [小瑤](/display/~chenyao)，[ApacheCN](/display/~apachecn)，[Apache中文網](/display/~apachechina) 以下選項可以應用于所有 **REST APIs** 。 ## Pretty Results(優雅的結果) 當對任何請求追加 **?pretty = true** 時，返回的 **JSON** 將優雅地格式化（僅用于調試！）。另一個選項是設置 **?format = yaml** ，這將使結果以（有時）更可讀的 **yaml** 格式返回。 ## Human readable output (?人類可讀的輸出?) 以適合人類的格式（例如 **"exists_time":"1h"** 或者 **"size":"1kb"**）和計算機（例如 **"exists_time_in_millis":"3600000"** 或者 **"size_in_bytes":"1024"**）返回統計信息。通過向查詢字符串中添加 **?human=false** 可以關閉人類可讀的值。當統計結果被監視工具消費而不是用于人類消費時，這將是有意義的。**human** 的標識的默認值是 **false** 。 ## Date Math 大多數接收格式化日期值的參數（例如，**gt** 和 **lt**）在范圍內查詢范圍查詢，或者從 **daterange** 聚合中獲取或者理解 **date math** 。表達式以 **anchor date** ( 錨定日期?) 開始，可以是現在，也可以是以 **||** 結尾的 **date** 字符串。此錨定日期可以選擇性地后跟一個或多個 **maths expressions**?( 數學表達式?)： | 數學表達式 | 含義 | | --- | --- | | +1h | **add one hour** ( ?加一個小時 ) | | -1d | **subtract one day** ( 減去一天 ) | | /d | **round down to the nearest day** ( 向下舍入到最近的一天 ) | 所支持的 ?**time units** ( 時間單位?)不同于持續時間支持的?[時間單位](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units)。所支持的單位是： | 符號 | 含義 | | --- | --- | | y | years | | M | months | | w | weeks | | d | days | | h | hours | | H | hours | | m | minutes | | s | seconds | 下面是一些例子： | 表達式 | 含義 | | --- | --- | | now+1h | 當前時間加上一個小時，以毫秒（ms）為單位 | | now+1h+1m | 當前時間加上一個小時一分鐘，以毫秒（ms）為單位 | | now+1h/d | 當前時間加上一個小時，向下舍入到最近的一天。 | | 2015-01-01||+1M/d | 2015-01-01 加一個月，向下舍入到最近一天。 | ## ?respoonse filtering ( 響應過濾 ) 所有 **REST API** 接受可用于減少 **elasticsearch** 返回的響應的 **filter_path** 參數。此參數采用用點表示法表示的以逗號分隔的過濾器列表： ``` GET /_search?q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score ``` **Responds** ( 響應?)： ``` { "took" : 3, "hits" : { "hits" : [ { "_id" : "0", "_score" : 1.6375021 } ] } } ``` 并且 ****** 通配符可以用于包括不知道確切路徑的字段。例如，我們可以返回帶有此請求的每個 **segment** ( 段?) 的 **Lucene** 版本： ``` GET /_cluster/state?filter_path=routing_table.indices.**.state ``` **Responds** ( 響應?)?： ``` { "routing_table": { "indices": { "twitter": { "shards": { "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], "1": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], "2": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], "3": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], "4": [{"state": "STARTED"}, {"state": "UNASSIGNED"}] } } } } } ``` 也可以通過使用字符 **-** 前綴過濾器來排除一個或多個字段： ``` GET /_count?filter_path=-_shards ``` **Responds** ( 響應?)?： ``` { "count" : 5 } ``` 為了更多的控制，**inclusive** ( 包含?) 和 **exclusive?**( 獨占過濾器?) 可以組合在同一個表達式。在這種情況下，將首先應用 **exclusive filters**?( 獨占過濾器?) ，并使用 **inclusive filters**?( 包含過濾器?) ?再次過濾效果： ``` GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-* ``` **Responds** ( 響應?)?： ``` { "metadata" : { "indices" : { "index-1" : {"state" : "open"}, "index-2" : {"state" : "open"}, "index-3" : {"state" : "open"} } } } ``` 請注意， **elasticsearch** 有時直接返回字段的原始值，如 **_source** 字段。如果要過濾 **_source** 字段，應該考慮將已有的?**source** 參數（請參閱?**[Get API](/display/Elasticsearch/Get+API)**?了解更多詳細信息）與 **filterpath** 參數組合，如下所示： ``` POST /library/book?refresh {"title": "Book #1", "rating": 200.1} POST /library/book?refresh {"title": "Book #2", "rating": 1.7} POST /library/book?refresh {"title": "Book #3", "rating": 0.1} GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc ``` ``` { "hits" : { "hits" : [ { "_source":{"title":"Book #1"} }, { "_source":{"title":"Book #2"} }, { "_source":{"title":"Book #3"} } ] } } ``` ## Flat Settings (?平面設置 ) : **flat_settings** 標志影響設置列表的呈現。當?**flat_settings** 標志為 **true** 時，設置以平面格式返回： ``` GET twitter/_settings?flat_settings=true ``` **Returns** ( 返回?)?： ``` { "twitter" : { "settings": { "index.number_of_replicas": "1", "index.number_of_shards": "1", "index.creation_date": "1474389951325", "index.uuid": "n6gzFZTgS664GUfx0Xrpjw", "index.version.created": ..., "index.provided_name" : "twitter" } } } ``` 當 **flat_settings** 標志為 **false** 時，設置以更易于閱讀的結構化格式返回： ``` GET twitter/_settings?flat_settings=false ``` **Returns** ( 返回?)?： ``` { "twitter" : { "settings" : { "index" : { "number_of_replicas": "1", "number_of_shards": "1", "creation_date": "1474389951325", "uuid": "n6gzFZTgS664GUfx0Xrpjw", "version": { "created": ... }, "provided_name" : "twitter" } } } } ``` 默認情況下， **flat_settings** 被設置為 **false** 。 ## Parameters ( 參數 )? **Rest** 參數（當使用 **HTTP** 時，映射到 **HTTP URL** 參數）遵循使用下劃線框的慣例。 ## Boolean Values ( 布爾值 ) 所有 **REST APIs** 參數（請求參數和 **JSON** 正文）支持提供布爾值 **"false"** 作為值： **false**， **0**， **no** 和 **off** 。所有其他值均被視為 **"true"** 。警告 ### Deprecated in 5.3.0\. ( 在5.3.0中棄用。 ) 不推薦使用 **"false"** 和 **"true"** 以外的任何值。 ## Number Values ( 數值 )? 所有 **REST APIs** 支持將編號的參數作為 **string** ( 字符串?) 提供，以支持本機 **JSON** 數字類型。 ## Time units ( 時間單位 ) 每當需要指定持續時間時，對于 **timeout** 參數，持續時間必須指定單位，如 **2d** 為 **2**天。支持的單位有： | 符號 | 含義 | | --- | --- | | d | days | | h | hours | | m | minutes | | s | seconds | | ms | milliseconds | | micros | microseconds | | nanos | nanoseconds | ## byte size units ( 字節大小單位 ) 每當需要指定數據的字節大小時，例如，當設置 **buffer?**( 緩沖區?) 大小參數時，該值必須指定單位，例如 **10** 千字節的 **10kb** 。支持的單位有： | 單位 | 全稱 | | --- | --- | | b | Bytes | | kb | Kilobytes | | mb | Megabytes | | gb | Gigabytes | | tb | Terabytes | | pb | Petabytes | ## unit-less quantities ( 無單位數量?)? 無單位數量意味著它們沒有像**“ bytes ( 字節?) ”**或者**“ Hertz ( 赫茲?) ”**或者**“ meter ( 米?) ”**或者**“ long tonne ( 長噸?) ”** 的“單位”。如果這些數量中的一個很大，我們將打印出來，如**10,000萬**的 **10m** 或者 **7,000** 的 **7k** 。我們仍然打印 **87** ，當我們的意思是 **87** 。這些是支持的 **multipliers** ( 乘數?)?： | 符號 | 含義 | | --- | --- | | `` | Single | | k | Kilo | | m | Mega | | g | Giga | | t | Tera | | p | Peta | ## distance units ( 距離單位?) 無論在何處需要指定距離，例如“地理距離查詢”中的距離參數，默認單位（如果沒有指定）是 **meter ( 米?)** 。距離可以用其他單位指定，例如 “**1公里（km）**”或者“**2公里（mi）**”**（2英里）**。單位的完整列表如下： | 單位 | 表示符號 | | --- | --- | | Mile | `mi`?或者?`miles` | | Yard | `yd`?或者?`yards` | | Feet | `ft`?或者?`feet` | | Inch | `in`?或者?`inch` | | Kilometer | `km`?或者?`kilometers` | | Meter | `m`?或者?`meters` | | Centimeter | `cm`?或者?`centimeters` | | Millimeter | `mm`?或者?`millimeters` | | Nautical mile | `NM`,?`nmi`?或者?`nauticalmiles` | ## Fuzziness ( 模糊性?) 一些查詢和 **APIs** 支持參數以允許使用模糊性參數進行不精確的模糊匹配。當查詢 **text** ( 文本?) 或者 **keyword fields**?( 關鍵字字段?)時，模糊性被解釋為?**Levenshtein Edit Distance** ——?是指兩個字串之間，由一個轉成另一個所需的最少編輯操作次數。模糊性參數可以指定為： **0， 1， 2** 最大允許?**Levenshtein Edit Distance** （或者編輯次數）。 **AUTO** 基于 term（詞元）的長度 **generates an edit distance**?( 生成編輯距離?)。對于長度： **? ? ? ?0..2** ? ? ?必須完全匹配 **? ? ? ?3..5** ? ? ?允許 **one edit allowed**?( 編輯一次?) **? ? ? ?>5** ? ? ?允許 **two edits allowed**?( 編輯兩次?) **? ? ? ? ?AUTO** 一般應該是 **fuzziness** ( 模糊性?)?的首選值。（簡單的來說就是：如果要匹配的 term 的長度為0-2 則進行精確匹配 ?3-5 則進行編輯距離=1的匹配長度>5 則進行2次編輯距離）. ## Enabling stack traces ( 啟用堆棧跟蹤?) 默認情況下，當請求返回錯誤時，**Elasticsearch** 不包括錯誤的堆棧跟蹤。您可以將 **error_trace_url** 參數設置為 **true** 來啟用該行為。例如，默認情況下，當您向 **_search API** 發送無效的 **size** 參數時： ``` POST /twitter/_search?size=surprise_me ``` 響應看起來像下面這樣： ``` { "error" : { "root_cause" : [ { "type" : "illegal_argument_exception", "reason" : "Failed to parse int parameter [size] with value [surprise_me]" } ], "type" : "illegal_argument_exception", "reason" : "Failed to parse int parameter [size] with value [surprise_me]", "caused_by" : { "type" : "number_format_exception", "reason" : "For input string: \"surprise_me\"" } }, "status" : 400 } ``` 但是，如果您設置 **error_trace=true** ： ``` POST /twitter/_search?size=surprise_me&error_trace=true ``` 響應看起來像這樣： ``` { "error": { "root_cause": [ { "type": "illegal_argument_exception", "reason": "Failed to parse int parameter [size] with value [surprise_me]", "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..." } ], "type": "illegal_argument_exception", "reason": "Failed to parse int parameter [size] with value [surprise_me]", "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...", "caused_by": { "type": "number_format_exception", "reason": "For input string: \"surprise_me\"", "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..." } }, "status": 400 } ``` ## request body in query string ( 在查詢字符串中的請求主體?) 對于不接受非 **POST** 請求的請求主體的庫，您可以將請求正文作為源查詢字符串參數傳遞。使用此方法時，**source_content_type** 參數也應該傳遞一個**?media type value** ，該值指示 **source** 的格式，例如??**application/json** 。警告 ### Deprecated in 5.3.0\. ( 在5.3.0中棄用 ) Provide the proper Content-Type header ( 提供適當的 **Content-Type** 標題 ) 檢查在 **request body** 中發送的內容或使用?**source query string parameter** 來自動確定內容類型（**JSON，YAML，SMILE** 或 **CBOR**）。可以啟用?**strict mode** ( 嚴格模式 ) ，禁用?**auto-detection** ( 自動檢測功能 ?)，并要求所有具有 **body** 的請求都具有映射到支持格式的?**Content-Type header** 。要啟用此?**strict mode** ( 嚴格模式 )，請將以下設置添加到 **elasticsearch.yml** 文件中： ``` http.content_type.required: true ``` 默認值為 **false** 。