常见选项

以下选项可以应用于所有 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 ( 时间单位 )不同于持续时间支持的 时间单位。所支持的单位是：

符号	含义
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 了解更多详细信息 ）与 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 。