常用選項 · my-elasticsearch-cn

# 常用選項以下選項可以應用于所有 REST APIs 。 ## 優雅的結果當對任何請求追加`?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`可以關閉人類可讀的值。當統計結果被監視工具消費而不是用于人類消費時，這將是有意義的。人性化標志的默認值是`false`。 ## 日期運算接受格式化的日期值的參數大多數都支持日期運算——譬如使用`gt`與`lt`的[范圍查詢](../Query_DSL/Term_level_queries/Range_Query.md)，或者使用`from`與`to`的[日期范圍聚合](../Aggregations/Bucket_Aggregations/Date_Range_Aggregation.md)。表達式以錨定日期開始，可以是`now`，也可以`||`結尾的日期字符串。此錨定日期可以選擇性地后跟一個或多個數學表達式：數學表達式含義+1h加一個小時（add one hour）-1d減去一天（subtract one day）/d向下舍入到最近的一天（round down to the nearest day）所支持的時間單位不同于[持續時間支持的時間單位](#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 加一個月，向下舍入到最近一天。 ## 響應過濾（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 } ] } } ``` 并且`*`通配符可以用于包括不知道確切路徑的字段。例如： ``` 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 } ``` 為了更多的控制，包含和獨占過濾器可以組合在同一個表達式。在這種情況下，將首先應用獨占過濾器，并使用包含過濾器再次過濾： ``` 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`字段，你需要結合`filter_path`參數來考慮已存在`_source`參數。（請參閱[Get API](../Document_APIS/Get_API.md#get-source-filtering)了解更多詳細信息），如下所示： ``` 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`設置為`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） All REST APIs parameters (both request parameters and JSON body) support providing boolean "false" as the value?`false`?and boolean "true" as the value`true`. All other values will raise an error. ## 數值所有REST API都支持以字符串的形式來提供數字，以支持JSON數字類型。 ## 時間單位（Time units）每當需要指定持續時間時，譬如`timeout`參數，持續時間必須指定單位，如`2d`為`2天`。支持的單位有：符號含義 d days h hours m minutes s seconds ms milliseconds micros microseconds nanos nanoseconds ## 字節大小單位每當需要指定數據的字節大小時，例如，當設置緩沖區（buffer）大小參數時，該值必須指定單位，例如`10`千字節的`10kb`。支持的單位有：單位全稱bByteskbKilobytesmbMegabytesgbGigabytestbTerabytespbPetabytes ## 無單位數量（unit-less quantities）無單位數量意味著它們沒有像“字節（bytes）”或者“赫茲（Hertz）”或者“米（meter）”或者“長噸（long tonne）” 的“單位”。如果這些數量中的一個很大，我們將打印出來，如10,000萬的 10m 或者 7,000 的 7k 。我們仍然打印 87 ，當我們的意思是 87 。這些是支持的乘數（multipliers）：符號含義SinglekKilomMegagGigatTerapPeta ## 距離單位（distance units）無論在何處需要指定距離，例如“地理距離查詢”中的距離參數，默認單位（如果沒有指定）是米（meter）。距離可以用其他單位指定，例如 “1公里（km）”或者“2公里（mi）”（2英里）。單位的完整列表如下：單位表示符號Milemi 或者 milesYardyd 或者 yardsFeetft 或者 feetInchin 或者 inchKilometerkm 或者 kilometersMeterm 或者 metersCentimetercm 或者 centimetersMillimetermm 或者 millimetersNautical mileNM, nmi 或者 nauticalmiles ## 模糊性（Fuzziness）一些查詢和 APIs 支持參數以允許使用模糊性參數進行不精確的模糊匹配。當查詢文本（text）或者關鍵字字段（keyword fields）時，模糊性被解釋為 Levenshtein Edit Distance —— 需要對一個字符串進行更改以使其與另一個字符串相同的一個字符的數目。 `fuzziness`參數可以指定為： `0， 1， 2` 最大允許 Levenshtein Edit Distance （或者編輯次數）。 `AUTO` 基于該項的長度生成編輯距離（generates an edit distance）。對于長度： * 0..2 必須完全匹配 * 3..5 允許編輯一次（one edit allowed） * \>5 允許編輯兩次（two edits allowed） * AUTO 一般應該是`fuzziness`的首選值。 ## 啟用堆棧跟蹤默認情況下，當請求返回錯誤時，Elasticsearch不包括錯誤的堆棧跟蹤。您可以將`error_trace`參數設置為`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 } ``` ## 請求體作為查詢字符串對于不接受請求體的`non-POST`請求，你可以把請求體粘貼到查詢字符串的`source`參數來執行。在使用吃方法時，需要通過`source_content_type`參數指定媒體類型來表明數據來源的格式，譬如：`application/json`。 ## Content-Type自動探測參數內容通過請求主體或者是查詢字符串`source`來傳遞時會自動探測內容的類型（JSON、YAML、SMILE、或者CBOR）。嚴格的模式可以開啟禁用自動探測，然后需要在請求頭的`Content-Type`中設置支持的格式。若要開啟嚴格模式，請添加如下行到`elasticsearch.yml`文件： ``` http.content_type.required: true ``` 它的默認值為false。 > my note > > 通用的URI參數(filter_path,flat_settings,error_trace等等)