elasticsearch/docs/reference/rest-api/common-options.asciidoc

[[common-options]]
== Common options

All {es} REST APIs support the following options.

[discrete]
=== 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.


[discrete]
=== Human readable output

Statistics are returned in a format suitable for humans
(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
consumption. The default for the `human` flag is
`false`.

[[date-math]]
[discrete]
=== Date Math

Most parameters which accept a formatted date value -- such as `gt` and `lt`
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

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

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`
 `2001.02.01\|\|+1M/d`:: `2001-02-01` in milliseconds plus one month. Resolves to: `2001-03-01 00:00:00`

[discrete]
[[common-options-response-filtering]]
=== 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,console]
--------------------------------------------------
GET /_search?q=kimchy&filter_path=took,hits.hits._id,hits.hits._score
--------------------------------------------------
// TEST[setup:my_index]

Responds:

[source,console-result]
--------------------------------------------------
{
  "took" : 3,
  "hits" : {
    "hits" : [
      {
        "_id" : "0",
        "_score" : 1.6375021
      }
    ]
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"took" : 3/"took" : $body.took/]
// TESTRESPONSE[s/1.6375021/$body.hits.hits.0._score/]

It also supports the `*` wildcard character to match any field or part
of a field's name:

[source,console]
--------------------------------------------------
GET /_cluster/state?filter_path=metadata.indices.*.stat*
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n/]

Responds:

[source,console-result]
--------------------------------------------------
{
  "metadata" : {
    "indices" : {
      "my-index-000001": {"state": "open"}
    }
  }
}
--------------------------------------------------

And the `**` wildcard can be used to include fields without knowing the
exact path of the field. For example, we can return the state
of every shard with this request:

[source,console]
--------------------------------------------------
GET /_cluster/state?filter_path=routing_table.indices.**.state
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n/]

Responds:

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

It is also possible to exclude one or more fields by prefixing the filter with the char `-`:

[source,console]
--------------------------------------------------
GET /_count?filter_path=-_shards
--------------------------------------------------
// TEST[setup:my_index]

Responds:

[source,console-result]
--------------------------------------------------
{
  "count" : 5
}
--------------------------------------------------

And for more control, both inclusive and exclusive filters can be combined in the same expression. In
this case, the exclusive filters will be applied first and the result will be filtered again using the
inclusive filters:

[source,console]
--------------------------------------------------
GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\nPUT my-index-000002\nPUT my-index-000003\nPUT logstash-2016.01\n/]

Responds:

[source,console-result]
--------------------------------------------------
{
  "metadata" : {
    "indices" : {
      "my-index-000001" : {"state" : "open"},
      "my-index-000002" : {"state" : "open"},
      "my-index-000003" : {"state" : "open"}
    }
  }
}
--------------------------------------------------

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
<<get-source-filtering,Get API>> for more details) with the `filter_path`
parameter like this:

[source,console]
--------------------------------------------------
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
--------------------------------------------------

[source,console-result]
--------------------------------------------------
{
  "hits" : {
    "hits" : [ {
      "_source":{"title":"Book #1"}
    }, {
      "_source":{"title":"Book #2"}
    }, {
      "_source":{"title":"Book #3"}
    } ]
  }
}
--------------------------------------------------


[discrete]
=== Flat Settings

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,console]
--------------------------------------------------
GET my-index-000001/_settings?flat_settings=true
--------------------------------------------------
// TEST[setup:my_index]

Returns:

[source,console-result]
--------------------------------------------------
{
  "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"
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/1474389951325/$body.my-index-000001.settings.index\\\\.creation_date/]
// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.my-index-000001.settings.index\\\\.uuid/]
// TESTRESPONSE[s/"index.version.created": \.\.\./"index.version.created": $body.my-index-000001.settings.index\\\\.version\\\\.created/]

When the `flat_settings` flag is `false`, settings are returned in a more
human readable structured format:

[source,console]
--------------------------------------------------
GET my-index-000001/_settings?flat_settings=false
--------------------------------------------------
// TEST[setup:my_index]

Returns:

[source,console-result]
--------------------------------------------------
{
  "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"
      }
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/1474389951325/$body.my-index-000001.settings.index.creation_date/]
// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.my-index-000001.settings.index.uuid/]
// TESTRESPONSE[s/"created": \.\.\./"created": $body.my-index-000001.settings.index.version.created/]

By default `flat_settings` is set to `false`.

[[fuzziness]]
[discrete]
=== Fuzziness

Some queries and APIs support parameters to allow inexact _fuzzy_ matching,
using the `fuzziness` parameter.

When querying `text` or `keyword` fields, `fuzziness` is interpreted as a
{wikipedia}/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:

[horizontal]
`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.
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

`AUTO` should generally be the preferred value for `fuzziness`.
--

[discrete]
[[common-options-error-options]]
=== Enabling stack traces

By default when a request returns an error Elasticsearch doesn't include the
stack trace of the error. You can enable that behavior by setting the
`error_trace` url parameter to `true`. For example, by default when you send an
invalid `size` parameter to the `_search` API:

[source,console]
----------------------------------------------------------------------
POST /my-index-000001/_search?size=surprise_me
----------------------------------------------------------------------
// TEST[s/surprise_me/surprise_me&error_trace=false/ catch:bad_request]
// Since the test system sends error_trace=true by default we have to override

The response looks like:

[source,console-result]
----------------------------------------------------------------------
{
  "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
}
----------------------------------------------------------------------

But if you set `error_trace=true`:

[source,console]
----------------------------------------------------------------------
POST /my-index-000001/_search?size=surprise_me&error_trace=true
----------------------------------------------------------------------
// TEST[catch:bad_request]

The response looks like:

[source,console-result]
----------------------------------------------------------------------
{
  "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
}
----------------------------------------------------------------------
// TESTRESPONSE[s/"stack_trace": "Failed to parse int parameter.+\.\.\."/"stack_trace": $body.error.root_cause.0.stack_trace/]
// TESTRESPONSE[s/"stack_trace": "java.lang.IllegalArgum.+\.\.\."/"stack_trace": $body.error.stack_trace/]
// TESTRESPONSE[s/"stack_trace": "java.lang.Number.+\.\.\."/"stack_trace": $body.error.caused_by.stack_trace/]