# 常见选项

原文链接 : [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&#124;&#124;+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** ( 编辑一次 )

**       &gt;5**

     允许 **two edits allowed** ( 编辑两次 )

**         AUTO** 一般应该是 **fuzziness** ( 模糊性 ) 的首选值。（ 简单的来说就是：如果要匹配的 term 的长度为0-2 则进行精确匹配  3-5 则进行编辑距离=1的匹配 长度&gt;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** 。