常见选项 · 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** 。