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

274 lines
7.8 KiB
Plaintext
Raw Normal View History

First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[cat]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
== cat APIs
First pass at cat docs.
2013-11-14 20:14:39 -05:00
["float",id="intro"]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
=== Introduction
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[DOCS] Add admonition for app using cat APIs (#52727) Adds an explicit "important" admonition discouraging apps from using cat APIs. cat APIs are intended for human consumption via the command line or Kibana console only. They are not intended for consumption by applications.
2020-02-25 07:19:35 -05:00
JSON is great... for computers. Even if it's pretty-printed, trying
to find relationships in the data is tedious. Human eyes, especially
when looking at a terminal, need compact and aligned text. The cat APIs
aim to meet this need.
[IMPORTANT]
====
cat APIs are only intended for human consumption using the
{kibana-ref}/console-kibana.html[Kibana console] or command line. They are _not_
intended for use by applications. For application consumption, we recommend
using a corresponding JSON API.
====
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Document h/headers switcheroo.
2014-01-06 12:23:24 -05:00
All the cat commands accept a query string parameter `help` to see all
Display all available endpoints by default at /_cat Closes #5106
2014-03-07 14:21:43 -05:00
the headers and info they provide, and the `/_cat` command alone lists all
remove help command, list all cat commands in /_cat?h endpoint
2013-12-05 08:36:27 -05:00
the available commands.
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[common-parameters]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
=== Common parameters
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[verbose]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
==== Verbose
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Each of the commands accepts a query string parameter `v` to turn on
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
verbose output. For example:
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[DOCS] [2 of 5] Change // CONSOLE comments to [source,console] (#46353) (#46502)
2019-09-09 13:38:14 -04:00
[source,console]
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
--------------------------------------------------
GET /_cat/master?v
--------------------------------------------------
Might respond with:
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
id host ip node
u_n93zwxThWHi1PDBJAGAg 127.0.0.1 127.0.0.1 u_n93zw
First pass at cat docs.
2013-11-14 20:14:39 -05:00
--------------------------------------------------
[DOCS] Change `// TESTRESPONSE[_cat]` to `// TESTRESPONSE[non_json]` (#43006)
2019-06-10 09:33:32 -04:00
// TESTRESPONSE[s/u_n93zw(xThWHi1PDBJAGAg)?/.+/ non_json]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
[[help]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
==== Help
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
Document h/headers switcheroo.
2014-01-06 12:23:24 -05:00
Each of the commands accepts a query string parameter `help` which will
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
output its available columns. For example:
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
[DOCS] [2 of 5] Change // CONSOLE comments to [source,console] (#46353) (#46502)
2019-09-09 13:38:14 -04:00
[source,console]
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
GET /_cat/master?help
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
Add a note to the docs that _cat api `help` option cannot be used if an optional url param is used (#28686)
2018-02-15 09:56:01 -05:00
Might respond with:
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
--------------------------------------------------
id | | node id
host | h | host name
ip | | ip address
node | n | node name
--------------------------------------------------
[DOCS] Change `// TESTRESPONSE[_cat]` to `// TESTRESPONSE[non_json]` (#43006)
2019-06-10 09:33:32 -04:00
// TESTRESPONSE[s/[|]/[|]/ non_json]
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
Add a note to the docs that _cat api `help` option cannot be used if an optional url param is used (#28686)
2018-02-15 09:56:01 -05:00
NOTE: `help` is not supported if any optional url parameter is used.
[DOCS] Replace `twitter` dataset in cat API docs (#60588) (#60597)
2020-08-03 10:22:36 -04:00
For example `GET _cat/shards/my-index-000001?help` or `GET _cat/indices/my-index-*?help`
Add a note to the docs that _cat api `help` option cannot be used if an optional url param is used (#28686)
2018-02-15 09:56:01 -05:00
results in an error. Use `GET _cat/shards?help` or `GET _cat/indices?help`
instead.
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
[[headers]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
==== Headers
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
Document h/headers switcheroo.
2014-01-06 12:23:24 -05:00
Each of the commands accepts a query string parameter `h` which forces
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
only those columns to appear. For example:
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
[DOCS] [2 of 5] Change // CONSOLE comments to [source,console] (#46353) (#46502)
2019-09-09 13:38:14 -04:00
[source,console]
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
--------------------------------------------------
GET /_cat/nodes?h=ip,port,heapPercent,name
--------------------------------------------------
Responds with:
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
127.0.0.1 9300 27 sLBaIGK
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
--------------------------------------------------
[DOCS] Change `// TESTRESPONSE[_cat]` to `// TESTRESPONSE[non_json]` (#43006)
2019-06-10 09:33:32 -04:00
// TESTRESPONSE[s/9300 27 sLBaIGK/\\d+ \\d+ .+/ non_json]
[DOCS] Add headers and help parameters.
2013-12-23 18:14:56 -05:00
Cat API: Add wildcard support for header names This adds wildcard support (simple regexes) for specifying header names. Aliases are supported as well. Closes #10811
2015-05-27 06:05:32 -04:00
You can also request multiple columns using simple wildcards like
Rename the bulk thread pool to write thread pool (#29593) This commit renames the bulk thread pool to the write thread pool. This is to better reflect the fact that the underlying thread pool is used to execute any document write request (single-document index/delete/update requests, and bulk requests). With this change, we add support for fallback settings thread_pool.bulk.* which will be supported until 7.0.0. We also add a system property so that the display name of the thread pool remains as "bulk" if needed to avoid breaking users.
2018-04-19 07:47:20 -04:00
`/_cat/thread_pool?h=ip,queue*` to get all headers (or aliases) starting
with `queue`.
Cat API: Add wildcard support for header names This adds wildcard support (simple regexes) for specifying header names. Aliases are supported as well. Closes #10811
2015-05-27 06:05:32 -04:00
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[numeric-formats]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
==== Numeric formats
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Add support for documented byte/size units and for micros as a time unit in _cat API We advertise in our documentation that byte units are like `kb`, `mb`... But we actually only support the simple notation `k` or `m`. This commit adds support for the documented form and keeps the non documented options to avoid any breaking change. It also adds support for `micros`, `nanos` and `d` as a time unit in `_cat` API. Remove the support for `b` as a SizeValue unit. Actually, for numbers, when using raw numbers without unit, there is no text to add/parse after the number. For example, you don't write `10` as `10b`. We support option like `size=` in `_cat` API which means that we want to display raw data without unit (singles). Documentation updated accordingly. Add test for the empty size option. Fix missing TimeValues options for some cat APIs
2016-04-15 06:24:54 -04:00
Many commands provide a few types of numeric output, either a byte, size
or a time value. By default, these types are human-formatted,
First pass at cat docs.
2013-11-14 20:14:39 -05:00
for example, `3.5mb` instead of `3763212`. The human values are not
sortable numerically, so in order to operate on these values where
order is important, you can change it.
Say you want to find the largest index in your cluster (storage used
by all the shards, not number of documents). The `/_cat/indices` API
[DOCS] Use `s` parameter in cat API overview example (#50616) Updates a snippet to use the `s` query string parameter rather than piping the output to a separate `sort` command. This ensures the snippet is tested and available in clients other than curl (Kibana console, etc.). Issue was originally raised by @hackaholic in #40926.
2020-01-14 08:21:32 -05:00
is ideal. You only need to add three things to the API request:
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[DOCS] Use `s` parameter in cat API overview example (#50616) Updates a snippet to use the `s` query string parameter rather than piping the output to a separate `sort` command. This ensures the snippet is tested and available in clients other than curl (Kibana console, etc.). Issue was originally raised by @hackaholic in #40926.
2020-01-14 08:21:32 -05:00
. The `bytes` query string parameter with a value of `b` to get byte-level resolution.
. The `s` (sort) parameter with a value of `store.size:desc` to sort the output
by shard storage in descending order.
. The `v` (verbose) parameter to include column headings in the response.
[source,console]
--------------------------------------------------
GET /_cat/indices?bytes=b&s=store.size:desc&v
--------------------------------------------------
[DOCS] Replace `twitter` dataset in cat API docs (#60588) (#60597)
2020-08-03 10:22:36 -04:00
// TEST[setup:my_index_huge]
// TEST[s/^/PUT my-index-000002\n{"settings": {"number_of_replicas": 0}}\n/]
[DOCS] Use `s` parameter in cat API overview example (#50616) Updates a snippet to use the `s` query string parameter rather than piping the output to a separate `sort` command. This ensures the snippet is tested and available in clients other than curl (Kibana console, etc.). Issue was originally raised by @hackaholic in #40926.
2020-01-14 08:21:32 -05:00
The API returns the following response:
[source,txt]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
--------------------------------------------------
[DOCS] Replace `twitter` dataset in cat API docs (#60588) (#60597)
2020-08-03 10:22:36 -04:00
health status index uuid pri rep docs.count docs.deleted store.size pri.store.size
yellow open my-index-000001 u8FNjxh8Rfy_awN11oDKYQ 1 1 1200 0 72171 72171
green open my-index-000002 nYFWZEO7TUiOjLQXBaYJpA 1 0 0 0 230 230
First pass at cat docs.
2013-11-14 20:14:39 -05:00
--------------------------------------------------
[DOCS] Use `s` parameter in cat API overview example (#50616) Updates a snippet to use the `s` query string parameter rather than piping the output to a separate `sort` command. This ensures the snippet is tested and available in clients other than curl (Kibana console, etc.). Issue was originally raised by @hackaholic in #40926.
2020-01-14 08:21:32 -05:00
// TESTRESPONSE[s/72171|230/\\d+/]
// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
AwaitsFix for #51619
2020-08-06 04:40:55 -04:00
// TESTRESPONSE[skip:"AwaitsFix https://github.com/elastic/elasticsearch/issues/51619"]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Add support for documented byte/size units and for micros as a time unit in _cat API We advertise in our documentation that byte units are like `kb`, `mb`... But we actually only support the simple notation `k` or `m`. This commit adds support for the documented form and keeps the non documented options to avoid any breaking change. It also adds support for `micros`, `nanos` and `d` as a time unit in `_cat` API. Remove the support for `b` as a SizeValue unit. Actually, for numbers, when using raw numbers without unit, there is no text to add/parse after the number. For example, you don't write `10` as `10b`. We support option like `size=` in `_cat` API which means that we want to display raw data without unit (singles). Documentation updated accordingly. Add test for the empty size option. Fix missing TimeValues options for some cat APIs
2016-04-15 06:24:54 -04:00
If you want to change the <<time-units,time units>>, use `time` parameter.
If you want to change the <<size-units,size units>>, use `size` parameter.
If you want to change the <<byte-units,byte units>>, use `bytes` parameter.
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
==== Response as text, json, smile, yaml or cbor
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
[source,sh]
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
% curl 'localhost:9200/_cat/indices?format=json&pretty'
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
[
{
"pri.store.size": "650b",
"health": "yellow",
"status": "open",
[DOCS] Replace `twitter` dataset in cat API docs (#60588) (#60597)
2020-08-03 10:22:36 -04:00
"index": "my-index-000001",
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
"pri": "5",
"rep": "1",
"docs.count": "0",
"docs.deleted": "0",
"store.size": "650b"
}
]
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
// NOTCONSOLE
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
Fixed asciidoc issues
2016-02-05 08:47:27 -05:00
Currently supported formats (for the `?format=` parameter):
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
- text (default)
- json
- smile
- yaml
- cbor
Fixed asciidoc issues
2016-02-05 08:47:27 -05:00
Alternatively you can set the "Accept" HTTP header to the appropriate media format.
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
All formats above are supported, the GET parameter takes precedence over the header.
Fixed asciidoc issues
2016-02-05 08:47:27 -05:00
For example:
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
[source,sh]
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
% curl '192.168.56.10:9200/_cat/indices?pretty' -H "Accept: application/json"
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
[
{
"pri.store.size": "650b",
"health": "yellow",
"status": "open",
[DOCS] Replace `twitter` dataset in cat API docs (#60588) (#60597)
2020-08-03 10:22:36 -04:00
"index": "my-index-000001",
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
"pri": "5",
"rep": "1",
"docs.count": "0",
"docs.deleted": "0",
"store.size": "650b"
}
]
--------------------------------------------------
CONSOLEify some _cat docs Added `// NOTCONSOLE` to some `_cat` docs that rely on `sort` or are otherwise too difficult for us to test at this point. Relates to #20717
2016-10-06 13:31:18 -04:00
// NOTCONSOLE
Use Accept header field in cat API The cat API previously used the Content-Type header field for determining the media type of the response. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. This commit replaces the use of the Content-Type header field with the Accept header field in the cat API. Closes #14421
2016-02-04 12:47:08 -05:00
[DOCS] Swap `[float]` for `[discrete]` (#60134) Changes instances of `[float]` in our docs for `[discrete]`. Asciidoctor prefers the `[discrete]` tag for floating headings: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#blocks
2020-07-23 12:42:33 -04:00
[discrete]
Adding built-in sorting capability to _cat apis. (#20658) * Adding built-in sorting capability to _cat apis. Closes #16975 * addressing pr comments * changing value types back to original implementation and fixing cosmetic issues * Changing compareTo, hashCode of value types to a better implementation * Changed value compareTos to use Double.compare instead of if statements + fixed some failed unit tests
2016-10-11 12:29:22 -04:00
[[sort]]
[DOCS] Remove heading offsets for REST APIs (#44568) Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
2019-07-19 14:35:36 -04:00
==== Sort
Adding built-in sorting capability to _cat apis. (#20658) * Adding built-in sorting capability to _cat apis. Closes #16975 * addressing pr comments * changing value types back to original implementation and fixing cosmetic issues * Changing compareTo, hashCode of value types to a better implementation * Changed value compareTos to use Double.compare instead of if statements + fixed some failed unit tests
2016-10-11 12:29:22 -04:00
Each of the commands accepts a query string parameter `s` which sorts the table by
the columns specified as the parameter value. Columns are specified either by name or by
alias, and are provided as a comma separated string. By default, sorting is done in
ascending fashion. Appending `:desc` to a column will invert the ordering for
that column. `:asc` is also accepted but exhibits the same behavior as the default sort order.
For example, with a sort string `s=column1,column2:desc,column3`, the table will be
sorted in ascending order by column1, in descending order by column2, and in ascending
order by column3.
[source,sh]
--------------------------------------------------
Allows multiple patterns to be specified for index templates (#21009) * Allows for an array of index template patterns to be provided to an index template, and rename the field from 'template' to 'index_pattern'. Closes #20690
2016-11-10 18:00:30 -05:00
GET _cat/templates?v&s=order:desc,index_patterns
Adding built-in sorting capability to _cat apis. (#20658) * Adding built-in sorting capability to _cat apis. Closes #16975 * addressing pr comments * changing value types back to original implementation and fixing cosmetic issues * Changing compareTo, hashCode of value types to a better implementation * Changed value compareTos to use Double.compare instead of if statements + fixed some failed unit tests
2016-10-11 12:29:22 -04:00
--------------------------------------------------
//CONSOLE
returns:
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
Adding built-in sorting capability to _cat apis. (#20658) * Adding built-in sorting capability to _cat apis. Closes #16975 * addressing pr comments * changing value types back to original implementation and fixing cosmetic issues * Changing compareTo, hashCode of value types to a better implementation * Changed value compareTos to use Double.compare instead of if statements + fixed some failed unit tests
2016-10-11 12:29:22 -04:00
--------------------------------------------------
Allows multiple patterns to be specified for index templates (#21009) * Allows for an array of index template patterns to be provided to an index template, and rename the field from 'template' to 'index_pattern'. Closes #20690
2016-11-10 18:00:30 -05:00
name index_patterns order version
pizza_pepperoni [*pepperoni*] 2
sushi_california_roll [*avocado*] 1 1
pizza_hawaiian [*pineapples*] 1
Adding built-in sorting capability to _cat apis. (#20658) * Adding built-in sorting capability to _cat apis. Closes #16975 * addressing pr comments * changing value types back to original implementation and fixing cosmetic issues * Changing compareTo, hashCode of value types to a better implementation * Changed value compareTos to use Double.compare instead of if statements + fixed some failed unit tests
2016-10-11 12:29:22 -04:00
--------------------------------------------------
[DOCS] Added documentation for CAT Aliases API Added asciidoc. Added new lines in java class.
2014-01-20 03:23:00 -05:00
include::cat/alias.asciidoc[]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
include::cat/allocation.asciidoc[]
[DOCS] Adds cat anomaly detectors API (#52866) (#52970)
2020-03-02 10:28:55 -05:00
include::cat/anomaly-detectors.asciidoc[]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
include::cat/count.asciidoc[]
[DOCS] Adds cat data frame analytics API (#52764) Co-authored-by: Lisa Cawley <lcawley@elastic.co>
2020-02-26 05:09:37 -05:00
include::cat/dataframeanalytics.asciidoc[]
[DOCS] Adds cat datafeeds API (#52738)
2020-02-26 12:20:36 -05:00
include::cat/datafeeds.asciidoc[]
[DOCS] reordered cat apis menu
2014-06-03 05:05:26 -04:00
include::cat/fielddata.asciidoc[]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
include::cat/health.asciidoc[]
include::cat/indices.asciidoc[]
include::cat/master.asciidoc[]
Add _cat/nodeattrs API This provides a _cat/nodeattrs API call, which presents custom node attributes in a denormalized table. Closes #8000
2015-07-29 09:56:57 -04:00
include::cat/nodeattrs.asciidoc[]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
include::cat/nodes.asciidoc[]
Add _cat/pending_tasks. Closes #4251.
2013-11-29 02:08:54 -05:00
include::cat/pending_tasks.asciidoc[]
[DOCS] reordered cat apis menu
2014-06-03 05:05:26 -04:00
include::cat/plugins.asciidoc[]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
include::cat/recovery.asciidoc[]
Add cat API for repositories and snapshots Closes #14247 Closes #13919
2015-10-22 05:00:51 -04:00
include::cat/repositories.asciidoc[]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
include::cat/shards.asciidoc[]
Add _cat/plugins endpoint If we want to have a full picture of versions running in a cluster, we need to add a `_cat/plugins` endpoint. Response could look like: ```sh % curl es2:9200/_cat/plugins?v node component version type url desc es1 mapper-attachments 1.7.0 j Adds the attachment type allowing to parse difference attachment formats es1 lang-javascript 1.4.0 j JavaScript plugin allowing to add javascript scripting support es1 analysis-smartcn 1.9.0 j Smart Chinese analysis support es1 marvel 1.1.0 j/s http://localhost:9200/_plugins/marvel Elasticsearch Management & Monitoring es1 kopf 0.5.3 s http://localhost:9200/_plugins/kopf kopf - simple web administration tool for ElasticSearch es2 mapper-attachments 2.0.0.RC1 j Adds the attachment type allowing to parse difference attachment formats es2 lang-javascript 2.0.0.RC1 j JavaScript plugin allowing to add javascript scripting support es2 analysis-smartcn 2.0.0.RC1 j Smart Chinese analysis support ``` Closes #4824.
2014-03-16 07:14:44 -04:00
Cat API: Add wildcard support for header names This adds wildcard support (simple regexes) for specifying header names. Aliases are supported as well. Closes #10811
2015-05-27 06:05:32 -04:00
include::cat/segments.asciidoc[]
Add cat API for repositories and snapshots Closes #14247 Closes #13919
2015-10-22 05:00:51 -04:00
include::cat/snapshots.asciidoc[]
Provides a cat api endpoint for templates. (#20545) Adds a cat api endpoint: /_cat/templates and its more specific version, /_cat/templates/{name}. It looks something like: $ curl "localhost:9200/_cat/templates?v" name template order version sushi_california_roll *avocado* 1 1 pizza_hawaiian *pineapples* 1 pizza_pepperoni *pepperoni* 1 The specified version (only allows * globs) looks like: $ curl "localhost:9200/_cat/templates/pizza*" name template order version pizza_hawaiian *pineapples* 1 pizza_pepperoni *pepperoni* 1 Partially specified columns: $ curl "localhost:9200/_cat/templates/pizza*?v=true&h=name,template" name template pizza_hawaiian *pineapples* pizza_pepperoni *pepperoni* The help text: $ curl "localhost:9200/_cat/templates/pizza*?help" name | n | template name template | t | template pattern string order | o | template application order number version | v | version Closes #20467
2016-09-20 04:40:23 -04:00
[DOCS] Adds stub for cat transform API (#53737)
2020-03-18 11:29:18 -04:00
include::cat/tasks.asciidoc[]
Provides a cat api endpoint for templates. (#20545) Adds a cat api endpoint: /_cat/templates and its more specific version, /_cat/templates/{name}. It looks something like: $ curl "localhost:9200/_cat/templates?v" name template order version sushi_california_roll *avocado* 1 1 pizza_hawaiian *pineapples* 1 pizza_pepperoni *pepperoni* 1 The specified version (only allows * globs) looks like: $ curl "localhost:9200/_cat/templates/pizza*" name template order version pizza_hawaiian *pineapples* 1 pizza_pepperoni *pepperoni* 1 Partially specified columns: $ curl "localhost:9200/_cat/templates/pizza*?v=true&h=name,template" name template pizza_hawaiian *pineapples* pizza_pepperoni *pepperoni* The help text: $ curl "localhost:9200/_cat/templates/pizza*?help" name | n | template name template | t | template pattern string order | o | template application order number version | v | version Closes #20467
2016-09-20 04:40:23 -04:00
include::cat/templates.asciidoc[]
[DOCS] Adds stub for cat transform API (#53737)
2020-03-18 11:29:18 -04:00
include::cat/thread_pool.asciidoc[]
include::cat/trainedmodel.asciidoc[]
[Transform] renamed _cat/transform to _cat/transforms (#53743) (#53771) renaming _cat/transform to _cat/transforms for uniformity with the other _cat apis.
2020-03-18 19:54:03 -04:00
include::cat/transforms.asciidoc[]