The Elasticsearch REST APIs are exposed using HTTP and are jSON-based.

Unless otherwise noted, the conventions in this chapter can be used using REST apis.

  • Multiple index
  • Date math is supported in index names
  • The public option
  • Url-based access control

Multiple index

Most apis that reference the index parameter support execution across multiple indexes, using simple test1, test2, test3 notation (or _all for all indexes).

All multi-index apis support the following URL query string parameters:

ignore_unavailable Controls whether to ignore the specified index if it is not available. True or false can be specified, including b nonexistent indexes and closed indexes
allow_no_indices Controls whether the result fails when a wildcard index expression has no specific index. You can specify true or false. For example, if you specify a wildcard expressionfoo*, and no index starting with foo is available, the request will fail. when_all,*This setting also applies if no index is specified. This setting also applies to aliases in case the alias points to a closed index.
expand_wildcards Controls what specific indexes wildcard index expressions can be extended to. If you specifyopen, the wildcard expression expands to open indexes only. If you specifyclosed, the wildcard expression extends only to closed indexes. You can also specify these two values (openandclosed) extends to all indexes.

The default Settings for the above parameters depend on the API used.

As opposed to multi-index apis, single-index apis, such as DocumentAPI and aliasAPI, do not support multiple indexes.

Date math is supported in index names

Date mathematical index name resolution lets you search for indexes in a time-series range, rather than searching all time-series indexes and filtering results or maintaining aliases. Limiting the number of search indexes reduces the load on the cluster and improves execution performance. For example, if you are searching for errors in your daily log, you can use the Date Math Name template to limit the search to the past two days.

Almost all apis with an index parameter support date math in the index parameter value.

Date mathematical index names take the following form:

<static_name{date_math_expr{date_format|time_zone}}>
Copy the code
Static_name is the static text part of the name
date_math_exprIs a dynamic date expression used for dynamic calculation
date_formatThe presentation format of the date is optional and defaults toyyyy.MM.dd. The format should matchJava-timeCompatible with
time_zoneOptional time zone. The default time zone isutc

Note the use of lowercase vs uppercase letters in date_format. For example, mm is the minute of an hour and mm is the month of a year. Similarly, hh represents hours in the 1-12 hour range combined with AM/PM, while HH represents hours in the 0-23 24 hour range.

Note the use of small and uppercase characters in date_format. For example, mm is the minute, and mm is the month of the year. Similarly, hh represents a combination of hours in the range 1-12 and AM/PM, while HH represents hours in the range 0-23.

Date mathematical expressions are independent of the region time. It is therefore impossible to use any calendar other than the Gregorian calendar.

Date Math index name expressions must be enclosed in braces, and all special characters should be URI-encoded. Such as:

# GET /<logstash-{now/d}>/_search
curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d'
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}
'
Copy the code

The encoding of the date Math character

Date parentheses, which must be urI-encoded, can be seen in the following table:

< %3C
> %3E
/ %2F
{ %7B
} %7D
| %7C
+ %2B
: %3A
. %2C

The following example shows the different forms of date mathematical index names, and the final index that they resolve based on the current time is 22nd March 2024 Noon UTC.

Expression Resolves to
<logstash-{now/d}> Logstash - 2024.03.22
<logstash-{now/M}> Logstash - 2024.03.01
<logstash-{now/M{yyyy.MM}}> Logstash - 2024.03 -
<logstash-{now/M-1M{yyyy.MM}}> Logstash - 2024.02 -
<logstash-{now/d{yyyy.MM.dd|+12:00}}> Logstash - 2024.03.23

To use the characters {and} in the static part of the index name template, escape them with a backslash \, for example:

  • <elastic\\{ON\\}-{now/M}> → ON elastic {} - 2024.03.01

The following example shows a search request that searches the Logstash index for the last three days, assuming the index uses the default Logstash index name format, Logstash – YYYY.mm.dd.

# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_searchcurl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search " -H 'Content-Type: application/json' -d' { "query" : { "match": { "test": "data" } } } 'Copy the code

The public option

All of the following options are available on all apis.

The result of beautification

When pretty = true is added to the request, the JSON returned is formatted (for debugging only!). . Another option is to set format = YAMl, which causes the result to be returned in readable YAML format.

Readable output

Statistics are returned in readable format (for example, exists_time: 1h or SIZE: 1KB) and computer (for example, exists_time_in_millis: 3600000 or size_IN_bytes: 1024). You can turn off the readable format by adding human = false to the query string. When statistical results are used by monitoring tools rather than by people. The default value is false.

Date Math

Most arguments accept a formatted date value, such as GT and lt in the range query, or from and to in the Daterange aggregate

Expression to anchor the date, may be now, also can is | | end date string. This anchoring date can optionally be followed by one or more mathematical expressions:

  • +1h: Add an hour
  • -1d: Reduce by an hour
  • /d: Rounds to the latest day

Supported time unit and duration time unit The supported time unit is different. The supported units are:

y years
M month
w weeks
d day
h when
H when
m points
s seconds

Suppose now is 2001-01-01 12:00:00, for example:

now+1h nowAdd an hour in milliseconds. The result is:The 2001-01-01 13:00:00
now-1h nowIn milliseconds minus one hour. The result is:The 2001-01-01 11:00:00
now-1h/d nowSubtract 1 hour in milliseconds, rounded to UTC 00:00. The result is:2001-01-01 00:00:00
2001.02.01 \ | the \ | + 1 m/d 2001-02-01Add one month in milliseconds. The result is:2001-03-01 00:00:00

Response filtering

All REST apis accept the filter_path parameter, which can be used to reduce the return of responses, as a comma-separated list of filters, expressed in dot notation:

curl -X GET "localhost:9200/_search? q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score"Copy the code

Response results:

{
  "took" : 3."hits" : {
    "hits": [{"_id" : "0"."_score" : 1.6375021}}}]Copy the code

It also supports * wildcards matching any field or part of the field name:

curl -X GET "localhost:9200/_cluster/state? filter_path=metadata.indices.*.stat*"Copy the code

Response results:

{
  "metadata" : {
    "indices" : {
      "twitter": {"state": "open"}}}}Copy the code

And ** wildcards can be used to include fields without knowing the exact path of the field. For example, we can use this request to return the Lucene version for each slice:

curl -X GET "localhost:9200/_cluster/state? filter_path=routing_table.indices.**.state"Copy the code

Response results:

{
  "routing_table": {
    "indices": {
      "twitter": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]}}}}}Copy the code

You can also exclude one or more fields by prefacing the filter with –

curl -X GET "localhost:9200/_count? filter_path=-_shards"Copy the code

Response results:

{
  "count" : 5
}

Copy the code

And for more control, you can combine inclusive and exclusive filters in the same expression. In this case, an exclusive filter is applied first, and the results are filtered again using an include filter:

curl -X GET "localhost:9200/_cluster/state? filter_path=metadata.indices.*.state,-metadata.indices.logstash-*"Copy the code

Response results:

{
  "metadata" : {
    "indices" : {
      "index-1" : {"state" : "open"},
      "index-2" : {"state" : "open"},
      "index-3" : {"state" : "open"}}}}Copy the code

Note that Elasticsearch sometimes returns the original value of a field, like the _source field. If you want to filter the _source field, you should consider combining the existing _source parameter with the filter_path parameter as follows:

curl -X POST "localhost:9200/library/book? refresh" -H 'Content-Type: application/json' -d' {"title": "Book #1", "rating": 200.1} 'curl -x POST "localhost: 9200 / library/book? refresh" -H 'Content-Type: application/json' -d' {"title": "Book #2", "rating": 1.7} 'curl -x POST "localhost: 9200 / library/book? refresh" -H 'Content-Type: application/json' -d' {"title": "Book #3", "rating": 0.1} 'curl -x GET "localhost:9200/_search? filter_path=hits.hits._source&_source=title&sort=rating:desc"Copy the code
{
  "hits" : {
    "hits": [{"_source": {"title":"Book #1"}}, {"_source": {"title":"Book #2"}}, {"_source": {"title":"Book #3"}}]}}Copy the code

Flat set

The flat_settings flag affects the rendering of the Settings list. When the flat_settings flag is true, the Settings are returned in the following format:

curl -X GET "localhost:9200/twitter/_settings? flat_settings=true"Copy the code

Response results:

{
  "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"}}}Copy the code

The default value of flat_settings is false.

parameter

REST parameters (when using HTTP, mapped to HTTP URL parameters) follow the convention of using underlined boxes.

Boolean value

All REST API parameters (request parameters and JSON body) support Boolean values of “false” as the value false and “true” as the value true. All other values raise an error.

The numerical

All REST apis support providing parameters in the form of a string (the string must be in numeric format, for example, not 12A).

Unit of time

When you need to specify a duration, for example, for a timeout parameter, the duration must be specified in a unit, such as 2d, lasting 2 days. Supporting units include:

d day
h when
m points
s seconds
ms ms
micros microseconds
nanos A nanosecond

Unit of byte size

Whenever you need to specify the size of the data in bytes, for example, when setting the buffer size parameter, the value must specify units, such as 10 kilobytes for 10 kilobytes. Note that these units use powers of 1024, so 1KB represents 1024 bytes. The supported units are:

b Bytes
kb Kilobytes
mb Megabytes
gb Gigabytes
tb Terabytes
pb Petabytes

Unitary quantity

Unitless quantities mean that they have no “units”, such as “bytes”, “Hertz”, “meters” or “tons”.

If one of these quantities is large, we will print it out, say 10m(10,000,000) or 7K (7000). When we mean 87, we still print 87. These are the supported multipliers:

k Kilo
m Mega
g Giga
t Tera
p Peta

From the unit

Where a distance needs to be specified, such as the distance parameter in a geographical distance query, the default is in meters if no distance is specified. Distances can be expressed in other units, such as “1km” or “2mi” (2 miles).

Mile mi or miles(miles)
Yard yd or yards(code)
Feet ft or feet(feet)
Inch in or inch(inches)
Kilometer km or kilometers(km)
Meter m or meters(m)
Centimeter cm or centimeters(cm)
Millimeter mm or millimeters(mm)
Nautical mile NM.nmi, or nauticalmiles(nm)

The fuzzy

Some queries and apis support fuzzy matching using fuzzy parameters.

When querying text or keyword fields, fuzziness is interpreted as Levenshtein edit distance — the number of characters that need to be changed to make one string the same as another.

Fuzziness can be specified as:

0.1.2 Maximum allowable Levenshtein Edit Distance (or Edit number)
AUTO Generate edit distances based on the length of the term. Optionally provide low range and high range parametersAUTO:[low],[high]. If not specified, the default values are 3 and 6, equivalent toAUTO: 3, 6Length:



0.. 2

It has to match exactly

3.. 5

Allow one edit

> 5

Allow two edits

AUTO should generally be the preferred value for ambiguity.

Enabling stack tracing

Elasticsearch does not contain an error stack trace by default when an error is returned on request. You can enable stack tracing by setting the error_traceurl parameter to truel, for example: by default, when you send an invalid size to _searchAPI:

curl -X POST "localhost:9200/twitter/_search? size=surprise_me"Copy the code

The corresponding results are as follows:

{
  "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
}

Copy the code

If you set error_trace=true

curl -X POST "localhost:9200/twitter/_search? size=surprise_me&error_trace=true"Copy the code

The corresponding results are as follows:

{
  "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
}

Copy the code

The request body is in the query string

For libraries that do not accept the request body of a non-POST request, the request body can be passed as the source query string parameter. When using this method, the source_content_type parameter should also be passed with a media type indicating the source format, such as Application /json.

The content-type request

The content-type request header must be used to specify the Type of Content to be sent in the request body. The content-type value must be one of the formats supported by the API. Most apis support JSON, YAML, CBOR, and SMILE. Batch and multiple search apis support NDJSON, JSON, and SMILE; Any other type will result in an error response.

Alternatively, when we use the source query string argument, we must specify the content-type using source_content_type.

Url-based access control

Many users use URL-based access control agents to ensure access to the Elasticsearch index. For multi-search, multi-fetch, and bulk requests, the user can choose to specify the index in the URL or in the request body for each request.

To prevent the user from overwriting the index specified in the URL, add this setting to the elasticSearch.yml file:

rest.action.multi.allow_explicit_index: false

Copy the code

The default value is true, but when set to false, Elasticsearch will reject requests that specify an explicit index in the request body.