Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edits to text in API Conventions docs #39001

Merged
merged 3 commits into from
Feb 20, 2019
Merged

Edits to text in API Conventions docs #39001

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4d31c33
Edits to text in API Conventions docs
dmeiss Feb 16, 2019
e79d2dc
Made requested change on “s” multiplier
dmeiss Feb 18, 2019
66af433
Removed "single" multiplier
dmeiss Feb 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 57 additions & 54 deletions docs/reference/api-conventions.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,39 +20,40 @@ API, unless otherwise specified.

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*` 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`.

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`::

Controls whether to ignore if any specified indices are unavailable, this
includes indices that don't exist or closed indices. Either `true` or `false`
Controls whether to ignore if any specified indices are unavailable,
including 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
Controls whether to fail if a wildcard indices expression results in 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
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
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
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
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
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
<<indices-aliases,single-index `alias` APIs>> do not support multiple indices.
Expand All @@ -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
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.

A date math index name takes the following form:
Expand All @@ -83,7 +84,7 @@ Where:
`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_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`.

You must enclose date math index name expressions within angle brackets, and
all special characters should be URI encoded. For example:
Expand Down Expand Up @@ -177,8 +178,8 @@ to set `?format=yaml` which will cause the result to be returned in the
=== 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`).
(e.g. `"exists_time": "1h"` or `"size": "1kb"`) and for computers
(e.g. `"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
Expand All @@ -190,36 +191,37 @@ consumption. The default for the `human` flag is
=== Date Math

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`
aggregations>> -- understand date maths.

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
one or more maths expressions:

* `+1h` - add one hour
* `-1d` - subtract one day
* `/d` - round down to the nearest day
* `+1h`: Add one hour
* `-1d`: Subtract one 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 units are:

[horizontal]
`y`:: years
`M`:: months
`w`:: weeks
`d`:: days
`h`:: hours
`H`:: hours
`m`:: minutes
`s`:: seconds
`y`:: Years
`M`:: Months
`w`:: Weeks
`d`:: Days
`h`:: Hours
`H`:: Hours
`m`:: Minutes
`s`:: Seconds

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 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`

[float]
Expand Down Expand Up @@ -397,8 +399,8 @@ GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc
[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:
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:

[source,js]
--------------------------------------------------
Expand Down Expand Up @@ -428,7 +430,7 @@ Returns:
// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index\\\\.uuid/]
// 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:

[source,js]
Expand Down Expand Up @@ -463,7 +465,7 @@ Returns:
// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index.uuid/]
// 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]
=== Parameters
Expand All @@ -474,7 +476,7 @@ convention of using underscore casing.
[float]
=== 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
value `true`. All other values will raise an error.

Expand All @@ -492,19 +494,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:

[horizontal]
`d`:: days
`h`:: hours
`m`:: minutes
`s`:: seconds
`ms`:: milliseconds
`micros`:: microseconds
`nanos`:: nanoseconds
`d`:: Days
`h`:: Hours
`m`:: Minutes
`s`:: Seconds
`ms`:: Milliseconds
`micros`:: Microseconds
`nanos`:: Nanoseconds

[[byte-units]]
[float]
=== 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
these units use powers of 1024, so `1kb` means 1024 bytes. The supported units are:

Expand All @@ -526,7 +528,7 @@ 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:

[horizontal]
``:: Single
`s`:: Single
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The s suffix is not recognized by Elasticsearch (see also

elasticsearch/server/src/main/java/org/elasticsearch/common/unit/SizeValue.java

Lines 170 to 197 in 869de3f

public static SizeValue parseSizeValue(String sValue) throws ElasticsearchParseException {
return parseSizeValue(sValue, null);
}
public static SizeValue parseSizeValue(String sValue, SizeValue defaultValue) throws ElasticsearchParseException {
if (sValue == null) {
return defaultValue;
}
long singles;
try {
if (sValue.endsWith("k") || sValue.endsWith("K")) {
singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C1);
} else if (sValue.endsWith("m") || sValue.endsWith("M")) {
singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C2);
} else if (sValue.endsWith("g") || sValue.endsWith("G")) {
singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C3);
} else if (sValue.endsWith("t") || sValue.endsWith("T")) {
singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C4);
} else if (sValue.endsWith("p") || sValue.endsWith("P")) {
singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C5);
} else {
singles = Long.parseLong(sValue);
}
} catch (NumberFormatException e) {
throw new ElasticsearchParseException("failed to parse [{}]", e, sValue);
}
return new SizeValue(singles, SizeUnit.SINGLE);
}
) so this needs to be an empty string.

`k`:: Kilo
`m`:: Mega
`g`:: Giga
Expand All @@ -538,8 +540,8 @@ when we mean 87 though. These are the supported multipliers:
=== Distance Units

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 meter. Distances can be specified in other units, such as `"1km"` or
the <<query-dsl-geo-distance-query>>), the default unit is meters if none is specified.
Distances can be specified in other units, such as `"1km"` or
`"2mi"` (2 miles).

The full list of units is listed below:
Expand All @@ -553,7 +555,7 @@ Kilometer:: `km` or `kilometers`
Meter:: `m` or `meters`
Centimeter:: `cm` or `centimeters`
Millimeter:: `mm` or `millimeters`
Nautical mile:: `NM`, `nmi` or `nauticalmiles`
Nautical mile:: `NM`, `nmi`, or `nauticalmiles`

[[fuzziness]]
[float]
Expand All @@ -569,20 +571,21 @@ make it the same as another string.

The `fuzziness` parameter can be specified as:

[horizontal]
`0`, `1`, `2`::

the maximum allowed Levenshtein Edit Distance (or number of edits)
The maximum allowed Levenshtein Edit Distance (or number of edits)

`AUTO`::
+
--
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,
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,
the default values are 3 and 6, equivalent to `AUTO:3,6` that make for lengths:

`0..2`:: must match exactly
`3..5`:: one edit allowed
`>5`:: two edits allowed
`0..2`:: Must match exactly
`3..5`:: One edit allowed
`>5`:: Two edits allowed

`AUTO` should generally be the preferred value for `fuzziness`.
--
Expand Down Expand Up @@ -682,9 +685,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 supported formats that the API supports. Most APIs support JSON,
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
string parameter.

Expand All @@ -693,7 +696,7 @@ string parameter.

Many users use a proxy with URL-based access control to secure access to
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
within the request body. This can make URL-based access control challenging.

Expand Down