[[api-conventions]] = API Conventions [partintro] -- The *elasticsearch* REST APIs are exposed using <>. The conventions listed in this chapter can be applied throughout the REST API, unless otherwise specified. * <> * <> -- [[multi-index]] == Multiple Indices Most APIs that refer to an `index` parameter support execution across multiple indices, using simple `test1,test2,test3` notation (or `_all` for all indices). It also support wildcards, for example: `test*`, and the ability to "add" (`+`) and "remove" (`-`), for example: `+test*,-test3`. All multi indices API support the following url query string parameters: `ignore_unavailable`:: Controls whether to ignore if any specified indices are unavailable, this includes indices that don't exist or closed indices. Either `true` or `false` can be specified. `allow_no_indices`:: Controls whether to fail if a wildcard indices expressions results into no concrete indices. Either `true` or `false` can be specified. For example if the wildcard expression `foo*` is specified and no indices are available that start with `foo` then depending on this setting the request will fail. This setting is also applicable when `_all`, `*` or no index has been specified. This settings also applies for aliases, in case an alias points to a closed index. `expand_wildcards`:: Controls to what kind of concrete indices wildcard indices expression expand to. If `open` is specified then the wildcard expression is expanded to only open indices and if `closed` is specified then the wildcard expression is expanded only to closed indices. Also both values (`open,closed`) can be specified to expand to all indices. If `none` is specified then wildcard expansion will be disabled and if `all` is specified, wildcard expressions will expand to all indices (this is equivalent to specifying `open,closed`). The defaults settings for the above parameters depend on the api being used. NOTE: Single index APIs such as the <> and the <> do not support multiple indices. [[common-options]] == Common options The following options can be applied to all of the REST APIs. [float] === Pretty Results When appending `?pretty=true` to any request made, the JSON returned will be pretty formatted (use it for debugging only!). Another option is to set `?format=yaml` which will cause the result to be returned in the (sometimes) more readable yaml format. [float] === Human readable output Statistics are returned in a format suitable for humans (eg `"exists_time": "1h"` or `"size": "1kb"`) and for computers (eg `"exists_time_in_millis": 3600000` or `"size_in_bytes": 1024`). The human readable values can be turned off by adding `?human=false` to the query string. This makes sense when the stats results are being consumed by a monitoring tool, rather than intended for human consumption. The default for the `human` flag is `false`. [float] === Response Filtering All REST APIs accept a `filter_path` parameter that can be used to reduce the response returned by elasticsearch. This parameter takes a comma separated list of filters expressed with the dot notation: [source,sh] -------------------------------------------------- curl -XGET 'localhost:9200/_search?pretty&filter_path=took,hits.hits._id,hits.hits._score' { "took" : 3, "hits" : { "hits" : [ { "_id" : "3640", "_score" : 1.0 }, { "_id" : "3642", "_score" : 1.0 } ] } } -------------------------------------------------- It also supports the `*` wildcard character to match any field or part of a field's name: [source,sh] -------------------------------------------------- curl -XGET 'localhost:9200/_nodes/stats?filter_path=nodes.*.ho*' { "nodes" : { "lvJHed8uQQu4brS-SXKsNA" : { "host" : "portable" } } } -------------------------------------------------- And the `**` wildcard can be used to include fields without knowing the exact path of the field. For example, we can return the Lucene version of every segment with this request: [source,sh] -------------------------------------------------- curl 'localhost:9200/_segments?pretty&filter_path=indices.**.version' { "indices" : { "movies" : { "shards" : { "0" : [ { "segments" : { "_0" : { "version" : "5.2.0" } } } ], "2" : [ { "segments" : { "_0" : { "version" : "5.2.0" } } } ] } }, "books" : { "shards" : { "0" : [ { "segments" : { "_0" : { "version" : "5.2.0" } } } ] } } } } -------------------------------------------------- Note that elasticsearch sometimes returns directly the raw value of a field, like the `_source` field. If you want to filter _source fields, you should consider combining the already existing `_source` parameter (see <> for more details) with the `filter_path` parameter like this: [source,sh] -------------------------------------------------- curl -XGET 'localhost:9200/_search?pretty&filter_path=hits.hits._source&_source=title' { "hits" : { "hits" : [ { "_source":{"title":"Book #2"} }, { "_source":{"title":"Book #1"} }, { "_source":{"title":"Book #3"} } ] } } -------------------------------------------------- [float] === Flat Settings The `flat_settings` flag affects rendering of the lists of settings. When `flat_settings` flag is `true` settings are returned in a flat format: [source,js] -------------------------------------------------- { "persistent" : { }, "transient" : { "discovery.zen.minimum_master_nodes" : "1" } } -------------------------------------------------- When the `flat_settings` flag is `false` settings are returned in a more human readable structured format: [source,js] -------------------------------------------------- { "persistent" : { }, "transient" : { "discovery" : { "zen" : { "minimum_master_nodes" : "1" } } } } -------------------------------------------------- By default the `flat_settings` is set to `false`. [float] === Parameters Rest parameters (when using HTTP, map to HTTP URL parameters) follow the convention of using underscore casing. [float] === Boolean Values All REST APIs parameters (both request parameters and JSON body) support providing boolean "false" as the values: `false`, `0`, `no` and `off`. All other values are considered "true". Note, this is not related to fields within a document indexed treated as boolean fields. [float] === Number Values All REST APIs support providing numbered parameters as `string` on top of supporting the native JSON number types. [[time-units]] [float] === Time units Whenever durations need to be specified, eg for a `timeout` parameter, the duration can be specified as a whole number representing time in milliseconds, or as a time value like `2d` for 2 days. The supported units are: [horizontal] `y`:: Year `M`:: Month `w`:: Week `d`:: Day `h`:: Hour `m`:: Minute `s`:: Second [[distance-units]] [float] === Distance Units Wherever distances need to be specified, such as the `distance` parameter in the <>), the default unit if none is specified is the meter. Distances can be specified in other units, such as `"1km"` or `"2mi"` (2 miles). The full list of units is listed below: [horizontal] Mile:: `mi` or `miles` Yard:: `yd` or `yards` Feet:: `ft` or `feet` Inch:: `in` or `inch` Kilometer:: `km` or `kilometers` Meter:: `m` or `meters` Centimeter:: `cm` or `centimeters` Millimeter:: `mm` or `millimeters` Nautical mile:: `NM`, `nmi` or `nauticalmiles` The `precision` parameter in the <> accepts distances with the above units, but if no unit is specified, then the precision is interpreted as the length of the geohash. [[fuzziness]] [float] === Fuzziness Some queries and APIs support parameters to allow inexact _fuzzy_ matching, using the `fuzziness` parameter. The `fuzziness` parameter is context sensitive which means that it depends on the type of the field being queried: [float] ==== Numeric, date and IPv4 fields When querying numeric, date and IPv4 fields, `fuzziness` is interpreted as a `+/-` margin. It behaves like a <> where: -fuzziness <= field value <= +fuzziness The `fuzziness` parameter should be set to a numeric value, eg `2` or `2.0`. A `date` field interprets a long as milliseconds, but also accepts a string containing a time value -- `"1h"` -- as explained in <>. An `ip` field accepts a long or another IPv4 address (which will be converted into a long). [float] ==== String fields When querying `string` fields, `fuzziness` is interpreted as a http://en.wikipedia.org/wiki/Levenshtein_distance[Levenshtein Edit Distance] -- the number of one character changes that need to be made to one string to make it the same as another string. The `fuzziness` parameter can be specified as: `0`, `1`, `2`:: the maximum allowed Levenshtein Edit Distance (or number of edits) `AUTO`:: + -- generates an edit distance based on the length of the term. For lengths: `0..2`:: must match exactly `3..5`:: one edit allowed `>5`:: two edits allowed `AUTO` should generally be the preferred value for `fuzziness`. -- `0.0..1.0`:: converted into an edit distance using the formula: `length(term) * (1.0 - fuzziness)`, eg a `fuzziness` of `0.6` with a term of length 10 would result in an edit distance of `4`. Note: in all APIs the maximum allowed edit distance is `2`. [float] === Result Casing All REST APIs accept the `case` parameter. When set to `camelCase`, all field names in the result will be returned in camel casing, otherwise, underscore casing will be used. Note, this does not apply to the source document indexed. [float] === Request body in query string For libraries that don't accept a request body for non-POST requests, you can pass the request body as the `source` query string parameter instead. [[url-access-control]] == URL-based access control Many users use a proxy with URL-based access control to secure access to Elasticsearch indices. For <>, <> and <> requests, the user has the choice of specifying an index in the URL and on each individual request within the request body. This can make URL-based access control challenging. To prevent the user from overriding the index which has been specified in the URL, add this setting to the `config.yml` file: rest.action.multi.allow_explicit_index: false The default value is `true`, but when set to `false`, Elasticsearch will reject requests that have an explicit index specified in the request body.