« API conventions REST API compatibility »

› ›

常用选项

edit

常用选项

edit

所有 Elasticsearch REST API 都支持以下选项。

漂亮的结果

edit

当在任何请求中附加?pretty=true时，返回的JSON将会是格式化的（仅用于调试！）。另一个选项是设置?format=yaml，这将导致结果以（有时）更易读的yaml格式返回。

人类可读输出

edit

统计数据以适合人类阅读的格式返回（例如 "exists_time": "1h" 或 "size": "1kb"）和适合计算机处理的格式（例如 "exists_time_in_millis": 3600000 或 "size_in_bytes": 1024）。可以通过在查询字符串中添加 ?human=false 来关闭人类可读的值。当统计结果被监控工具消费而不是供人类阅读时，这样做是有意义的。human 标志的默认值是 false。

日期数学

edit

大多数接受格式化日期值的参数——例如 gt 和 lt 在 range 查询中，或 from 和 to 在 daterange 聚合中——都支持日期数学运算。

表达式以一个锚定日期开始，可以是now，或者是以||结尾的日期字符串。这个锚定日期可以选择性地跟随一个或多个数学表达式：

+1h: 增加一小时
-1d: 减去一天
/d: 向下取整到最近的一天

支持的时间单位与时间单位用于持续时间的单位不同。支持的单位有：

`y`	年份
`M`	月份
`w`	周
`d`	天
`h`	小时
`H`	小时
`m`	分钟
`s`	秒

假设 now 是 2001-01-01 12:00:00，一些例子如下：

`now+1h`	`now` 加上一小时后的毫秒数。解析为：`2001-01-01 13:00:00`
`now-1h`	`now` 减去一小时后的毫秒数。解析为：`2001-01-01 11:00:00`
`now-1h/d`	`now` 在毫秒减去一小时后，向下舍入到UTC 00:00。解析为：`2001-01-01 00:00:00`
`2001.02.01\\|\\|+1M/d`	`2001-02-01` 以毫秒为单位加上一个月。解析为：`2001-03-01 00:00:00`

响应过滤

edit

所有REST API都接受一个filter_path参数，该参数可用于减少Elasticsearch返回的响应。此参数接受使用点表示法表示的过滤器的逗号分隔列表：

GET /_search?q=kimchy&filter_path=took,hits.hits._id,hits.hits._score

响应：

{
  "took" : 3,
  "hits" : {
    "hits" : [
      {
        "_id" : "0",
        "_score" : 1.6375021
      }
    ]
  }
}

它还支持使用通配符字符 * 来匹配任何字段或字段名称的一部分：

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

回应：

{
  "metadata" : {
    "indices" : {
      "my-index-000001": {"state": "open"}
    }
  }
}

而通配符 ** 可以用于包含字段，而无需知道字段的精确路径。例如，我们可以通过以下请求返回每个分片的状态：

GET /_cluster/state?filter_path=routing_table.indices.**.state

回应：

{
  "routing_table": {
    "indices": {
      "my-index-000001": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
        }
      }
    }
  }
}

也可以通过在过滤器前加上字符 - 来排除一个或多个字段：

GET /_count?filter_path=-_shards

回应：

{
  "count" : 5
}

为了更精确的控制，包含性和排除性过滤器可以组合在同一个表达式中。在这种情况下，排除性过滤器将首先被应用，然后结果将再次使用包含性过滤器进行过滤：

GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

回应：

{
  "metadata" : {
    "indices" : {
      "my-index-000001" : {"state" : "open"},
      "my-index-000002" : {"state" : "open"},
      "my-index-000003" : {"state" : "open"}
    }
  }
}

请注意，Elasticsearch 有时会直接返回字段的原始值，例如 _source 字段。如果您想过滤 _source 字段，您应该考虑将现有的 _source 参数（有关详细信息，请参阅 Get API）与 filter_path 参数结合使用，如下所示：

POST /library/_doc?refresh
{"title": "Book #1", "rating": 200.1}
POST /library/_doc?refresh
{"title": "Book #2", "rating": 1.7}
POST /library/_doc?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"}
    } ]
  }
}

扁平化设置

edit

The flat_settings flag 影响设置列表的渲染。当 flat_settings flag 为 true 时，设置会以扁平格式返回：

GET my-index-000001/_settings?flat_settings=true

返回值：

{
  "my-index-000001" : {
    "settings": {
      "index.number_of_replicas": "1",
      "index.number_of_shards": "1",
      "index.creation_date": "1474389951325",
      "index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
      "index.version.created": ...,
      "index.routing.allocation.include._tier_preference" : "data_content",
      "index.provided_name" : "my-index-000001"
    }
  }
}

当 flat_settings 标志为 false 时，设置会以更易于人类阅读的结构化格式返回：

GET my-index-000001/_settings?flat_settings=false

{
  "my-index-000001" : {
    "settings" : {
      "index" : {
        "number_of_replicas": "1",
        "number_of_shards": "1",
        "creation_date": "1474389951325",
        "uuid": "n6gzFZTgS664GUfx0Xrpjw",
        "version": {
          "created": ...
        },
        "routing": {
          "allocation": {
            "include": {
              "_tier_preference": "data_content"
            }
          }
        },
        "provided_name" : "my-index-000001"
      }
    }
  }
}

默认情况下，flat_settings 设置为 false。

模糊性

edit

一些查询和API支持参数以允许不精确的模糊匹配，使用fuzziness参数。

当查询 text 或 keyword 字段时，fuzziness 被解释为 Levenshtein 编辑距离 — 将一个字符串变为另一个字符串所需的一个字符更改的数量。

参数 fuzziness 可以指定为：

0, 1, 2

最大允许的Levenshtein编辑距离（或编辑次数）

自动

基于术语的长度生成编辑距离。可以可选地提供低和高距离参数 AUTO:[low],[high]。如果未指定，默认值为 3 和 6，相当于 AUTO:3,6，适用于长度：

0..2: 必须完全匹配
3..5: 允许一次编辑
>5: 允许两次编辑

AUTO 通常应为 fuzziness 的首选值。

启用堆栈跟踪

edit

默认情况下，当请求返回错误时，Elasticsearch 不会包含错误的堆栈跟踪信息。您可以通过将 error_trace URL 参数设置为 true 来启用该行为。例如，当您向 _search API 发送无效的 size 参数时，默认情况下：

POST /my-index-000001/_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 /my-index-000001/_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
}

« API conventions REST API compatibility »