前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

1、多索引

大多数API都支持跨多个索引执行，可以使用简单的 test1、 test2、test3 表示法(或对所有索引执行，用_all) 。它还支持通配 符，例如 test 或 test 或 te*t或*test*，以及 “排除” ( - ) 功能，例 如 -test3。

所有多索引API都支持以下URL查询字符串参数:

2、日期数学格式

索引名称支持日期解析，这样能够搜索一个时间范围内或某几段 时间内的索引，而不是搜索所有索引再筛选结果或维护别名。限制搜 索的索引数量可以减少集群上的负载并提高执行性能。例如，如果在 日常日志中搜索错误信息，可以使用日期格式名称模板将搜索严格限 制在过去两天内。

几乎所有具有 indexv参数的 API 都支持 index 参数值中包含日期数 学格式。日期数学索引名称具有以下形式:

<static_name{date_math_expr{date_format|time_zone}}>

2.1、日期数学字符百分比编码

2.2、日期数学格式解析实例

3、通用选项

3.1、格式化搜索结果

当任何请求 URL 加 pretty = true 参数时，返回的 JSON 都将是格式 化的(仅用于调试)。另一个选项是设置 format = yaml ，结果以更可读的 yaml 格式返回。

3.2、可读输出

统计数据以 适 合 人 ( 例 如 “ exists_time ” : “ 1h ” 或 “ size ”:“ 1KB ”) 和计算机(例如“ exists_time_in_millis ”: 3600000 或“size_in_bytes ”: 1024 )的格式返回。可以通过添加 human = false 来关闭对人友好可读输出格式。当统计结果被监控工具 使用，而不是用于人阅读时，这是有意义的。此标志的默认值为 false。

3.3、格式化日期值

大多数参数都可以接受格式化日期值，例如范围查询中的 gt 和 lt ，或范围内聚合中的 from 和 to。

表达式以基准日期开始，可以是 now，也可以是以 ‖ 结束的日期 字符串。基准日期后面可以有一个或多个日期数学表达式

3.3.1、时间单位

3.3.2、时间单位解析实例

3.4、返回信息过滤

所有 REST API 都接受一个 filter_path 参数，该参数可用于减少 Elasticsearch 返回的响应信息。此参数采用逗号分隔的列表形式， 如下示例:

3.4.1、filter_path 过滤

GET/bank/_search?q=*&sort=account_number:asc&pretty&&filter_path=took,hits.hits._id,hits.hits._score

3.4.2、* 通配符

GET/_cluster/state?filter_path=metadata.indices.*.stat*

3.4.3、字符-前缀来排除一个或多个字段

GET/_count?filter_path=-_shards

3.5、展开设置

flat_settings 标志会影响设置信息列表 (_settings) 的呈现。如果 flat_settings 标志为 true，则以平铺格式返回设置

默认值，flat_settings = false

⬤ 当 flat_settings 标志是以 true 平面格式返回设置时：

GET bank/_settings?flat_settings=true

{
  "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 标志是以 fales 平面格式返回设置时：

GET bank/_settings?flat_settings=false

{
  "twitter" : {
    "settings" : {
      "index" : {
        "number_of_replicas": "1",
        "number_of_shards": "1",
        "creation_date": "1474389951325",
        "uuid": "n6gzFZTgS664GUfx0Xrpjw",
        "version": {
          "created": ...
        },
        "provided_name" : "twitter"
      }
    }
  }
}

3.6、布尔值

所有 REST API 参数(请求参数和 JSON 主体)都支持布尔值 false 和 true，所有其他值都将引发错误。

3.7、数字值

所有 REST API 都支持以字符串的形式提供数字参数。

3.8、时间单位

每当需要指定时间区间，例如对于超时参数时，时间区间必须指定单位，如表示 2 天的 2d 。支持的单位如表3-5所示

3.9、数据单位

每当需要指定数据的字节大小，例如设置缓冲区大小参数时，该值必须指定单位，如 10KB 表示 10 千字节。请注意，这些单元使用 1024 的幂，所以1KB 表示 1024 字节。支持的单位如表 3-6所示

3.10、缩略处理

无单位意味着它们没有“单位”，如“ bytes ” “ Hertz ” “ mete ” 或 “ long tonne ”。

如果这些数量中有一个很大，会把它特殊地缩略处理， 10000000 打印成 10m ，7000 打印成 7k。但当我们说 87的时候，我 们还是会打印87。支持的乘数如表3-7所示

3.11、距离单位

需要指定距离(如地理距离查询中的距离参数)时，如果未指定，则默认单位为 m 。距离可以用其他单位指定，例如 1km 或 2mi (2英里)。

3.12、模糊性

一些查询和 API 支持使用模糊参数 ( fuzziness ) 进行不精确的模 糊匹配。

在查询 text 或 keyword 字段时，fuzziness 被解释为编辑距离，也就是一个字符串需要更改的字符数，以使其与另一个字符串相同。

fuzziness 参数可以指定为如下两种值。

⬤ 0，1，2 :允许的最大编辑距离(或编辑次数)

⬤ AUTO: 根据 Term 的长度生成编辑距离。可以选择自动提供低距离和高距离参数: AUTO : [ low ] , [ high ]。如果未指定，默认值为 3 和 6 ，相当于AUTO: 3 , 6 ，表示长度如，0 . . 2 必须精确匹配。 · 3 . . 5编辑距离1。 · > 5 编辑距离 2 。 · AUTO一般应为 fuzziness 的首选值

2.13、启用堆栈跟踪

默认情况下，当请求返回错误时，Elasticsearch 不包括错误的 堆栈跟踪。可以通过将 error_trace参数设置为 true 来启用堆栈 跟踪。

① 例如，默认情况下，将无效的 size 参数发送到 _search API 时

入参：

POST/bank/_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/bank/_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
}

2.14、查询字符串中的请求正文

对于不接受非 POST请求的请求主体的库，可以将请求主体作为 source 查询字符串参数传递。使用此方法时，还应使用指示源格式的 媒 体 类 型 值 ( 如 application/json ) 传 递 source_content_type 参 数。

2.15、Content-Type 要求

在请求正文中发送的内容的类型必须使用 Content-Type 头指 定。此头的值必须映射到 API支持的格式之一。大多数API支持 JSON、Yaml、Cbor 等常用格式。批量和多搜索 API 支持 Ndjson 、 JSON 和 smile，其他类型将导致错误

此外，使用 source 参数时，必须使用 source_content_type 参数 指定内容类型。

4、基于 URL 的访问控制

许多用户使用具有基于 URL 的访问控制的代理来安全地访问 Elasticsearch 索引。对于 multi-search、multi -get 和 bulk请求，用户可以选择在 URL 以及请求主体中的每个请求上指定索引。这会使基 于 URL 的访问控制变得具有挑战性。

要防止用户覆盖 URL 中指定的索引，请将此设置添加到 elasticsearch.yml 文件中:

默认值为 true，但当设置为 false 时，Elasticsearch 将拒绝请求 主体中指定了显式索引的请求。