honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edits to text in API Conventions docs (#39001)

This commit is contained in:
Darren Meiss 2019-02-20 04:37:15 -05:00 committed by Daniel Mitterdorfer
parent c1018db404
commit dc1ed80c73
1 changed files with 56 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
docs/reference/api-conventions.asciidoc
View File

@ -20,39 +20,40 @@ API, unless otherwise specified.
Most APIs that refer to an `index` parameter support execution across 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 using simple `test1,test2,test3` notation (or `_all` for all indices). It also
support wildcards, for example: `test*` or `*test` or `te*t` or `*test*`, and the supports wildcards, for example: `test*` or `*test` or `te*t` or `*test*`, and the
ability to "exclude" (`-`), for example: `test*,-test3`. ability to "exclude" (`-`), for example: `test*,-test3`.
All multi indices API support the following url query string parameters: All multi indices APIs support the following url query string parameters:
[horizontal]
`ignore_unavailable`:: `ignore_unavailable`::
Controls whether to ignore if any specified indices are unavailable, this Controls whether to ignore if any specified indices are unavailable,
includes indices that don't exist or closed indices. Either `true` or `false` including indices that don't exist or closed indices. Either `true` or `false`
can be specified. can be specified.
`allow_no_indices`:: `allow_no_indices`::
Controls whether to fail if a wildcard indices expressions results into no Controls whether to fail if a wildcard indices expression results in no
concrete indices. Either `true` or `false` can be specified. For example if concrete indices. Either `true` or `false` can be specified. For example if
the wildcard expression `foo*` is specified and no indices are available that 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 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 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. settings also applies for aliases, in case an alias points to a closed index.
`expand_wildcards`:: `expand_wildcards`::
Controls to what kind of concrete indices wildcard indices expression expand Controls what kind of concrete indices that wildcard indices expressions can expand
to. If `open` is specified then the wildcard expression is expanded to only 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 open indices. If `closed` is specified then the wildcard expression is
expanded only to closed indices. Also both values (`open,closed`) can be expanded only to closed indices. Also both values (`open,closed`) can be
specified to expand to all indices. specified to expand to all indices.
+ +
If `none` is specified then wildcard expansion will be disabled and if `all` If `none` is specified then wildcard expansion will be disabled. If `all`
is specified, wildcard expressions will expand to all indices (this is equivalent is specified, wildcard expressions will expand to all indices (this is equivalent
to specifying `open,closed`). to specifying `open,closed`).
The defaults settings for the above parameters depend on the api being used. The defaults settings for the above parameters depend on the API being used.
NOTE: Single index APIs such as the <<docs>> and the NOTE: Single index APIs such as the <<docs>> and the
<<indices-aliases,single-index `alias` APIs>> do not support multiple indices. <<indices-aliases,single-index `alias` APIs>> do not support multiple indices.
@ -67,7 +68,7 @@ execution performance. For example, if you are searching for errors in your
daily logs, you can use a date math name template to restrict the search to the past daily logs, you can use a date math name template to restrict the search to the past
two days. two days.
Almost all APIs that have an `index` parameter, support date math in the `index` parameter Almost all APIs that have an `index` parameter support date math in the `index` parameter
value. value.
A date math index name takes the following form: A date math index name takes the following form:
@ -83,7 +84,7 @@ Where:
`static_name`:: is the static text part of the name `static_name`:: is the static text part of the name
`date_math_expr`:: is a dynamic date math expression that computes the date dynamically `date_math_expr`:: is a dynamic date math expression that computes the date dynamically
`date_format`:: is the optional format in which the computed date should be rendered. Defaults to `YYYY.MM.dd`. `date_format`:: is the optional format in which the computed date should be rendered. Defaults to `YYYY.MM.dd`.
`time_zone`:: is the optional time zone . Defaults to `utc`. `time_zone`:: is the optional time zone. Defaults to `utc`.
Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other
calendars than the Gregorian calendar. calendars than the Gregorian calendar.
@ -180,8 +181,8 @@ to set `?format=yaml` which will cause the result to be returned in the
=== Human readable output === Human readable output
Statistics are returned in a format suitable for humans Statistics are returned in a format suitable for humans
(eg `"exists_time": "1h"` or `"size": "1kb"`) and for computers (e.g. `"exists_time": "1h"` or `"size": "1kb"`) and for computers
(eg `"exists_time_in_millis": 3600000` or `"size_in_bytes": 1024`). (e.g. `"exists_time_in_millis": 3600000` or `"size_in_bytes": 1024`).
The human readable values can be turned off by adding `?human=false` The human readable values can be turned off by adding `?human=false`
to the query string. This makes sense when the stats results are to the query string. This makes sense when the stats results are
being consumed by a monitoring tool, rather than intended for human being consumed by a monitoring tool, rather than intended for human
@ -193,7 +194,7 @@ consumption. The default for the `human` flag is
=== Date Math === Date Math
Most parameters which accept a formatted date value -- such as `gt` and `lt` Most parameters which accept a formatted date value -- such as `gt` and `lt`
in <<query-dsl-range-query,range queries>> `range` queries, or `from` and `to` in <<query-dsl-range-query,`range` queries>>, or `from` and `to`
in <<search-aggregations-bucket-daterange-aggregation,`daterange` in <<search-aggregations-bucket-daterange-aggregation,`daterange`
aggregations>> -- understand date maths. aggregations>> -- understand date maths.
@ -201,28 +202,29 @@ The expression starts with an anchor date, which can either be `now`, or a
date string ending with `||`. This anchor date can optionally be followed by date string ending with `||`. This anchor date can optionally be followed by
one or more maths expressions: one or more maths expressions:
* `+1h` - add one hour * `+1h`: Add one hour
* `-1d` - subtract one day * `-1d`: Subtract one day
* `/d` - round down to the nearest day * `/d`: Round down to the nearest day
The supported time units differ from those supported by <<time-units, time units>> for durations. The supported time units differ from those supported by <<time-units, time units>> for durations.
The supported units are: The supported units are:
[horizontal] [horizontal]
`y`:: years `y`:: Years
`M`:: months `M`:: Months
`w`:: weeks `w`:: Weeks
`d`:: days `d`:: Days
`h`:: hours `h`:: Hours
`H`:: hours `H`:: Hours
`m`:: minutes `m`:: Minutes
`s`:: seconds `s`:: Seconds
Assuming `now` is `2001-01-01 12:00:00`, some examples are: Assuming `now` is `2001-01-01 12:00:00`, some examples are:
[horizontal]
`now+1h`:: `now` in milliseconds plus one hour. Resolves to: `2001-01-01 13:00:00` `now+1h`:: `now` in milliseconds plus one hour. Resolves to: `2001-01-01 13:00:00`
`now-1h`:: `now` in milliseconds minus one hour. Resolves to: `2001-01-01 11:00:00` `now-1h`:: `now` in milliseconds minus one hour. Resolves to: `2001-01-01 11:00:00`
`now-1h/d`:: `now` in milliseconds minus one hour, rounded down to UTC 00:00. Resolves to: `2001-01-01 00:00:00`` `now-1h/d`:: `now` in milliseconds minus one hour, rounded down to UTC 00:00. Resolves to: `2001-01-01 00:00:00`
`2001.02.01\|\|+1M/d`:: `2001-02-01` in milliseconds plus one month. Resolves to: `2001-03-01 00:00:00` `2001.02.01\|\|+1M/d`:: `2001-02-01` in milliseconds plus one month. Resolves to: `2001-03-01 00:00:00`
[float] [float]
@ -396,8 +398,8 @@ GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc
[float] [float]
=== Flat Settings === Flat Settings
The `flat_settings` flag affects rendering of the lists of settings. When The `flat_settings` flag affects rendering of the lists of settings. When the
`flat_settings` flag is `true` settings are returned in a flat format: `flat_settings` flag is `true`, settings are returned in a flat format:
[source,js] [source,js]
-------------------------------------------------- --------------------------------------------------
@ -427,7 +429,7 @@ Returns:
// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index\\\\.uuid/] // TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index\\\\.uuid/]
// TESTRESPONSE[s/"index.version.created": \.\.\./"index.version.created": $body.twitter.settings.index\\\\.version\\\\.created/] // TESTRESPONSE[s/"index.version.created": \.\.\./"index.version.created": $body.twitter.settings.index\\\\.version\\\\.created/]
When the `flat_settings` flag is `false` settings are returned in a more When the `flat_settings` flag is `false`, settings are returned in a more
human readable structured format: human readable structured format:
[source,js] [source,js]
@ -462,7 +464,7 @@ Returns:
// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index.uuid/] // TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index.uuid/]
// TESTRESPONSE[s/"created": \.\.\./"created": $body.twitter.settings.index.version.created/] // TESTRESPONSE[s/"created": \.\.\./"created": $body.twitter.settings.index.version.created/]
By default the `flat_settings` is set to `false`. By default `flat_settings` is set to `false`.
[float] [float]
=== Parameters === Parameters
@ -473,7 +475,7 @@ convention of using underscore casing.
[float] [float]
=== Boolean Values === Boolean Values
All REST APIs parameters (both request parameters and JSON body) support All REST API parameters (both request parameters and JSON body) support
providing boolean "false" as the value `false` and boolean "true" as the providing boolean "false" as the value `false` and boolean "true" as the
value `true`. All other values will raise an error. value `true`. All other values will raise an error.
@ -491,19 +493,19 @@ Whenever durations need to be specified, e.g. for a `timeout` parameter, the dur
the unit, like `2d` for 2 days. The supported units are: the unit, like `2d` for 2 days. The supported units are:
[horizontal] [horizontal]
`d`:: days `d`:: Days
`h`:: hours `h`:: Hours
`m`:: minutes `m`:: Minutes
`s`:: seconds `s`:: Seconds
`ms`:: milliseconds `ms`:: Milliseconds
`micros`:: microseconds `micros`:: Microseconds
`nanos`:: nanoseconds `nanos`:: Nanoseconds
[[byte-units]] [[byte-units]]
[float] [float]
=== Byte size units === Byte size units
Whenever the byte size of data needs to be specified, eg when setting a buffer size Whenever the byte size of data needs to be specified, e.g. when setting a buffer size
parameter, the value must specify the unit, like `10kb` for 10 kilobytes. Note that parameter, the value must specify the unit, like `10kb` for 10 kilobytes. Note that
these units use powers of 1024, so `1kb` means 1024 bytes. The supported units are: these units use powers of 1024, so `1kb` means 1024 bytes. The supported units are:
@ -525,7 +527,6 @@ If one of these quantities is large we'll print it out like 10m for 10,000,000 o
when we mean 87 though. These are the supported multipliers: when we mean 87 though. These are the supported multipliers:
[horizontal] [horizontal]
``:: Single
`k`:: Kilo `k`:: Kilo
`m`:: Mega `m`:: Mega
`g`:: Giga `g`:: Giga
@ -537,8 +538,8 @@ when we mean 87 though. These are the supported multipliers:
=== Distance Units === Distance Units
Wherever distances need to be specified, such as the `distance` parameter in Wherever distances need to be specified, such as the `distance` parameter in
the <<query-dsl-geo-distance-query>>), the default unit if none is specified is the <<query-dsl-geo-distance-query>>), the default unit is meters if none is specified.
the meter. Distances can be specified in other units, such as `"1km"` or Distances can be specified in other units, such as `"1km"` or
`"2mi"` (2 miles). `"2mi"` (2 miles).
The full list of units is listed below: The full list of units is listed below:
@ -552,7 +553,7 @@ Kilometer:: `km` or `kilometers`
Meter:: `m` or `meters` Meter:: `m` or `meters`
Centimeter:: `cm` or `centimeters` Centimeter:: `cm` or `centimeters`
Millimeter:: `mm` or `millimeters` Millimeter:: `mm` or `millimeters`
Nautical mile:: `NM`, `nmi` or `nauticalmiles` Nautical mile:: `NM`, `nmi`, or `nauticalmiles`
[[fuzziness]] [[fuzziness]]
[float] [float]
@ -568,20 +569,21 @@ make it the same as another string.
The `fuzziness` parameter can be specified as: The `fuzziness` parameter can be specified as:
[horizontal]
`0`, `1`, `2`:: `0`, `1`, `2`::
the maximum allowed Levenshtein Edit Distance (or number of edits) The maximum allowed Levenshtein Edit Distance (or number of edits)
`AUTO`:: `AUTO`::
+ +
-- --
generates an edit distance based on the length of the term. Generates an edit distance based on the length of the term.
Low and high distance arguments may be optionally provided `AUTO:[low],[high]`, if not specified, Low and high distance arguments may be optionally provided `AUTO:[low],[high]`. If not specified,
the default values are 3 and 6, equivalent to `AUTO:3,6` that make for lengths: the default values are 3 and 6, equivalent to `AUTO:3,6` that make for lengths:
`0..2`:: must match exactly `0..2`:: Must match exactly
`3..5`:: one edit allowed `3..5`:: One edit allowed
`>5`:: two edits allowed `>5`:: Two edits allowed
`AUTO` should generally be the preferred value for `fuzziness`. `AUTO` should generally be the preferred value for `fuzziness`.
-- --
@ -681,9 +683,9 @@ The type of the content sent in a request body must be specified using
the `Content-Type` header. The value of this header must map to one of the `Content-Type` header. The value of this header must map to one of
the supported formats that the API supports. Most APIs support JSON, the supported formats that the API supports. Most APIs support JSON,
YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON, YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON,
JSON and SMILE; other types will result in an error response. JSON, and SMILE; other types will result in an error response.
Additionally, when using the `source` query string parameter the Additionally, when using the `source` query string parameter, the
content type must be specified using the `source_content_type` query content type must be specified using the `source_content_type` query
string parameter. string parameter.
@ -692,7 +694,7 @@ string parameter.
Many users use a proxy with URL-based access control to secure access to Many users use a proxy with URL-based access control to secure access to
Elasticsearch indices. For <<search-multi-search,multi-search>>, Elasticsearch indices. For <<search-multi-search,multi-search>>,
<<docs-multi-get,multi-get>> and <<docs-bulk,bulk>> requests, the user has <<docs-multi-get,multi-get>>, and <<docs-bulk,bulk>> requests, the user has
the choice of specifying an index in the URL and on each individual request 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. within the request body. This can make URL-based access control challenging.