« API 约定 REST API 兼容性 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API

常用选项

编辑

常用选项

编辑

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

美化结果

编辑

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

人类可读的输出

编辑

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

日期数学

编辑

大多数接受格式化日期值的参数（例如 范围查询中的 gt 和 lt，或 daterange聚合中的 from 和 to）都理解日期数学。

表达式以一个锚点日期开始，它可以是 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

响应过滤

编辑

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

resp = client.search(
    q="kimchy",
    filter_path="took,hits.hits._id,hits.hits._score",
)
print(resp)
response = client.search(
  q: 'kimchy',
  filter_path: 'took,hits.hits._id,hits.hits._score'
)
puts response
const response = await client.search({
  q: "kimchy",
  filter_path: "took,hits.hits._id,hits.hits._score",
});
console.log(response);
GET /_search?q=kimchy&filter_path=took,hits.hits._id,hits.hits._score

响应

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

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

$response = $client->cluster()->state();
resp = client.cluster.state(
    filter_path="metadata.indices.*.stat*",
)
print(resp)
response = client.cluster.state(
  filter_path: 'metadata.indices.*.stat*'
)
puts response
res, err := es.Cluster.State(
	es.Cluster.State.WithFilterPath("metadata.indices.*.stat*"),
)
fmt.Println(res, err)
const response = await client.cluster.state({
  filter_path: "metadata.indices.*.stat*",
});
console.log(response);
GET /_cluster/state?filter_path=metadata.indices.*.stat*

响应

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

并且可以使用 ** 通配符来包含字段，而无需知道字段的确切路径。例如，我们可以使用此请求返回每个分片的状态

$response = $client->cluster()->state();
resp = client.cluster.state(
    filter_path="routing_table.indices.**.state",
)
print(resp)
response = client.cluster.state(
  filter_path: 'routing_table.indices.**.state'
)
puts response
res, err := es.Cluster.State(
	es.Cluster.State.WithFilterPath("routing_table.indices.**.state"),
)
fmt.Println(res, err)
const response = await client.cluster.state({
  filter_path: "routing_table.indices.**.state",
});
console.log(response);
GET /_cluster/state?filter_path=routing_table.indices.**.state

响应

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

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

$response = $client->count();
resp = client.count(
    filter_path="-_shards",
)
print(resp)
response = client.count(
  filter_path: '-_shards'
)
puts response
res, err := es.Count(
	es.Count.WithFilterPath("-_shards"),
	es.Count.WithPretty(),
)
fmt.Println(res, err)
const response = await client.count({
  filter_path: "-_shards",
});
console.log(response);
GET /_count?filter_path=-_shards

响应

{
  "count" : 5
}

为了获得更多控制，包含和排除过滤器可以组合在同一表达式中。在这种情况下，将首先应用排除过滤器，然后使用包含过滤器再次过滤结果

$response = $client->cluster()->state();
resp = client.cluster.state(
    filter_path="metadata.indices.*.state,-metadata.indices.logstash-*",
)
print(resp)
response = client.cluster.state(
  filter_path: 'metadata.indices.*.state,-metadata.indices.logstash-*'
)
puts response
res, err := es.Cluster.State(
	es.Cluster.State.WithFilterPath("metadata.indices.*.state,-metadata.indices.logstash-*"),
)
fmt.Println(res, err)
const response = await client.cluster.state({
  filter_path: "metadata.indices.*.state,-metadata.indices.logstash-*",
});
console.log(response);
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 参数结合使用，如下所示

$params = [
    'index' => 'library',
    'body' => [
        'title' => 'Book #1',
        'rating' => 200.1,
    ],
];
$response = $client->index($params);
$params = [
    'index' => 'library',
    'body' => [
        'title' => 'Book #2',
        'rating' => 1.7,
    ],
];
$response = $client->index($params);
$params = [
    'index' => 'library',
    'body' => [
        'title' => 'Book #3',
        'rating' => 0.1,
    ],
];
$response = $client->index($params);
$response = $client->search();
resp = client.index(
    index="library",
    refresh=True,
    document={
        "title": "Book #1",
        "rating": 200.1
    },
)
print(resp)

resp1 = client.index(
    index="library",
    refresh=True,
    document={
        "title": "Book #2",
        "rating": 1.7
    },
)
print(resp1)

resp2 = client.index(
    index="library",
    refresh=True,
    document={
        "title": "Book #3",
        "rating": 0.1
    },
)
print(resp2)

resp3 = client.search(
    filter_path="hits.hits._source",
    source="title",
    sort="rating:desc",
)
print(resp3)
response = client.index(
  index: 'library',
  refresh: true,
  body: {
    title: 'Book #1',
    rating: 200.1
  }
)
puts response

response = client.index(
  index: 'library',
  refresh: true,
  body: {
    title: 'Book #2',
    rating: 1.7
  }
)
puts response

response = client.index(
  index: 'library',
  refresh: true,
  body: {
    title: 'Book #3',
    rating: 0.1
  }
)
puts response

response = client.search(
  filter_path: 'hits.hits._source',
  _source: 'title',
  sort: 'rating:desc'
)
puts response
{
	res, err := es.Index(
		"library",
		strings.NewReader(`{
	  "title": "Book #1",
	  "rating": 200.1
	}`),
		es.Index.WithRefresh("true"),
		es.Index.WithPretty(),
	)
	fmt.Println(res, err)
}

{
	res, err := es.Index(
		"library",
		strings.NewReader(`{
	  "title": "Book #2",
	  "rating": 1.7
	}`),
		es.Index.WithRefresh("true"),
		es.Index.WithPretty(),
	)
	fmt.Println(res, err)
}

{
	res, err := es.Index(
		"library",
		strings.NewReader(`{
	  "title": "Book #3",
	  "rating": 0.1
	}`),
		es.Index.WithRefresh("true"),
		es.Index.WithPretty(),
	)
	fmt.Println(res, err)
}

{
	res, err := es.Search(
		es.Search.WithSource("title"),
		es.Search.WithFilterPath("hits.hits._source"),
		es.Search.WithSort("rating:desc"),
		es.Search.WithPretty(),
	)
	fmt.Println(res, err)
}
const response = await client.index({
  index: "library",
  refresh: "true",
  document: {
    title: "Book #1",
    rating: 200.1,
  },
});
console.log(response);

const response1 = await client.index({
  index: "library",
  refresh: "true",
  document: {
    title: "Book #2",
    rating: 1.7,
  },
});
console.log(response1);

const response2 = await client.index({
  index: "library",
  refresh: "true",
  document: {
    title: "Book #3",
    rating: 0.1,
  },
});
console.log(response2);

const response3 = await client.search({
  filter_path: "hits.hits._source",
  _source: "title",
  sort: "rating:desc",
});
console.log(response3);
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"}
    } ]
  }
}

扁平设置

编辑

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

resp = client.indices.get_settings(
    index="my-index-000001",
    flat_settings=True,
)
print(resp)
response = client.indices.get_settings(
  index: 'my-index-000001',
  flat_settings: true
)
puts response
const response = await client.indices.getSettings({
  index: "my-index-000001",
  flat_settings: "true",
});
console.log(response);
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 时，设置以更易读的结构化格式返回

resp = client.indices.get_settings(
    index="my-index-000001",
    flat_settings=False,
)
print(resp)
response = client.indices.get_settings(
  index: 'my-index-000001',
  flat_settings: false
)
puts response
const response = await client.indices.getSettings({
  index: "my-index-000001",
  flat_settings: "false",
});
console.log(response);
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。

模糊性

编辑

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

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

fuzziness 参数可以指定为

0, 1, 2

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

AUTO

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

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

AUTO 通常应该是 fuzziness 的首选值。

启用堆栈跟踪

编辑

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

resp = client.search(
    index="my-index-000001",
    size="surprise_me",
)
print(resp)
const response = await client.search({
  index: "my-index-000001",
  size: "surprise_me",
});
console.log(response);
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

resp = client.search(
    index="my-index-000001",
    size="surprise_me",
    error_trace=True,
)
print(resp)
const response = await client.search({
  index: "my-index-000001",
  size: "surprise_me",
  error_trace: "true",
});
console.log(response);
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 约定 REST API 兼容性 »