mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 21:18:31 +00:00
5e1f26c22a
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
189 lines
4.8 KiB
Plaintext
189 lines
4.8 KiB
Plaintext
[[cat]]
|
|
= cat APIs
|
|
|
|
[partintro]
|
|
--
|
|
|
|
["float",id="intro"]
|
|
== Introduction
|
|
|
|
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 an ssh terminal, need compact and aligned text. The
|
|
cat API aims to meet this need.
|
|
|
|
All the cat commands accept a query string parameter `help` to see all
|
|
the headers and info they provide, and the `/_cat` command alone lists all
|
|
the available commands.
|
|
|
|
[float]
|
|
[[common-parameters]]
|
|
== Common parameters
|
|
|
|
[float]
|
|
[[verbose]]
|
|
=== Verbose
|
|
|
|
Each of the commands accepts a query string parameter `v` to turn on
|
|
verbose output.
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl 'localhost:9200/_cat/master?v'
|
|
id ip node
|
|
EGtKWZlWQYWDmX29fUnp3Q 127.0.0.1 Grey, Sara
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
[[help]]
|
|
=== Help
|
|
|
|
Each of the commands accepts a query string parameter `help` which will
|
|
output its available columns.
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl 'localhost:9200/_cat/master?help'
|
|
id | node id
|
|
ip | node transport ip address
|
|
node | node name
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
[[headers]]
|
|
=== Headers
|
|
|
|
Each of the commands accepts a query string parameter `h` which forces
|
|
only those columns to appear.
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl 'n1:9200/_cat/nodes?h=ip,port,heapPercent,name'
|
|
192.168.56.40 9300 40.3 Captain Universe
|
|
192.168.56.20 9300 15.3 Kaluu
|
|
192.168.56.50 9300 17.0 Yellowjacket
|
|
192.168.56.10 9300 12.3 Remy LeBeau
|
|
192.168.56.30 9300 43.9 Ramsey, Doug
|
|
--------------------------------------------------
|
|
|
|
You can also request multiple columns using simple wildcards like
|
|
`/_cat/thread_pool?h=ip,bulk.*` to get all headers (or aliases) starting
|
|
with `bulk.`.
|
|
|
|
[float]
|
|
[[numeric-formats]]
|
|
=== Numeric formats
|
|
|
|
Many commands provide a few types of numeric output, either a byte, size
|
|
or a time value. By default, these types are human-formatted,
|
|
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
|
|
is ideal. We only need to tweak two things. First, we want to turn
|
|
off human mode. We'll use a byte-level resolution. Then we'll pipe
|
|
our output into `sort` using the appropriate column, which in this
|
|
case is the eight one.
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl '192.168.56.10:9200/_cat/indices?bytes=b' | sort -rnk8
|
|
green wiki2 3 0 10000 0 105274918 105274918
|
|
green wiki1 3 0 10000 413 103776272 103776272
|
|
green foo 1 0 227 0 2065131 2065131
|
|
--------------------------------------------------
|
|
|
|
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.
|
|
|
|
[float]
|
|
=== Response as text, json, smile, yaml or cbor
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl '192.168.56.10:9200/_cat/indices?format=json' | jq .
|
|
[
|
|
{
|
|
"pri.store.size": "650b",
|
|
"health": "yellow",
|
|
"status": "open",
|
|
"index": "twitter",
|
|
"pri": "5",
|
|
"rep": "1",
|
|
"docs.count": "0",
|
|
"docs.deleted": "0",
|
|
"store.size": "650b"
|
|
}
|
|
]
|
|
--------------------------------------------------
|
|
|
|
Currently supported formats (for the `?format=` parameter):
|
|
- text (default)
|
|
- json
|
|
- smile
|
|
- yaml
|
|
- cbor
|
|
|
|
Alternatively you can set the "Accept" HTTP header to the appropriate media format.
|
|
All formats above are supported, the GET parameter takes precedence over the header.
|
|
For example:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl '192.168.56.10:9200/_cat/indices' -H "Accept: application/json" | jq .
|
|
[
|
|
{
|
|
"pri.store.size": "650b",
|
|
"health": "yellow",
|
|
"status": "open",
|
|
"index": "twitter",
|
|
"pri": "5",
|
|
"rep": "1",
|
|
"docs.count": "0",
|
|
"docs.deleted": "0",
|
|
"store.size": "650b"
|
|
}
|
|
]
|
|
--------------------------------------------------
|
|
|
|
--
|
|
|
|
include::cat/alias.asciidoc[]
|
|
|
|
include::cat/allocation.asciidoc[]
|
|
|
|
include::cat/count.asciidoc[]
|
|
|
|
include::cat/fielddata.asciidoc[]
|
|
|
|
include::cat/health.asciidoc[]
|
|
|
|
include::cat/indices.asciidoc[]
|
|
|
|
include::cat/master.asciidoc[]
|
|
|
|
include::cat/nodeattrs.asciidoc[]
|
|
|
|
include::cat/nodes.asciidoc[]
|
|
|
|
include::cat/pending_tasks.asciidoc[]
|
|
|
|
include::cat/plugins.asciidoc[]
|
|
|
|
include::cat/recovery.asciidoc[]
|
|
|
|
include::cat/repositories.asciidoc[]
|
|
|
|
include::cat/thread_pool.asciidoc[]
|
|
|
|
include::cat/shards.asciidoc[]
|
|
|
|
include::cat/segments.asciidoc[]
|
|
|
|
include::cat/snapshots.asciidoc[]
|