Skip to content

[DOCS] Document bytes and time params in cat API docs #47672

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

Merged
merged 4 commits into from
Oct 10, 2019
Merged

[DOCS] Document bytes and time params in cat API docs #47672

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
09ecfb0
[DOCS] Document `bytes` and `time` params in cat API docs
jrodewig Oct 7, 2019
1904efc
iter
jrodewig Oct 9, 2019
6f322d3
iter
jrodewig Oct 9, 2019
be233f3
Merge branch 'master' into doc-missing-cat-parms
elasticmachine Oct 9, 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
8 changes: 6 additions & 2 deletions docs/reference/cat/alias.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,16 @@ filter and routing information.
[[cat-alias-api-request]]
==== {api-request-title}

`GET /_cat/aliases/<name>`
`GET /_cat/aliases/<alias>`

`GET /_cat/aliases`

[[cat-alias-api-path-params]]
==== {api-path-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=name]
`<alias>`::
(Optional, string)
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias]


[[cat-alias-api-query-params]]
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/allocation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ and their disk space.

`GET /_cat/allocation/<node_id>`

`GET /_cat/allocation`

[[cat-allocation-api-path-params]]
==== {api-path-parms-title}

Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/count.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ which have not yet been removed by the merge process.

`GET /_cat/count/<index>`

`GET /_cat/count`


[[cat-count-api-path-params]]
==== {api-path-parms-title}
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/fielddata.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ in the cluster.

`GET /_cat/fielddata/<field>`

`GET /_cat/fielddata`


[[cat-fielddata-api-path-params]]
==== {api-path-parms-title}
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/health.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

`ts` (timestamps)::
(Optional, boolean) If `true`, returns `HH:MM:SS` and
https://en.wikipedia.org/wiki/Unix_time[Unix `epoch`] timestamps. Defaults to
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/cat/indices.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Returns high-level information about indices in a cluster.

`GET /_cat/indices/<index>`

`GET /_cat/indices`


[[cat-indices-api-desc]]
==== {api-description-title}
Expand Down Expand Up @@ -77,6 +79,8 @@ primary shards. Defaults to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

Copy link
Contributor

@jakelandis jakelandis Oct 9, 2019

Choose a reason for hiding this comment

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

I think this one should include bytes too

GET _cat/indices?h=ftt,ss&bytes=g&time=ms

Copy link
Contributor Author

@jrodewig jrodewig Oct 9, 2019

Choose a reason for hiding this comment

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

It looks like bytes is already documented for this API:
https://github.com/elastic/elasticsearch/blame/be233f3d235b39d9315fc79974e9b69f20b1fe38/docs/reference/cat/indices.asciidoc#L48

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


Expand Down
4 changes: 4 additions & 0 deletions docs/reference/cat/nodes.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ Returns information about a cluster's nodes.
[[cat-nodes-api-query-params]]
==== {api-query-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]

include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]

`full_id`::
Expand Down Expand Up @@ -287,6 +289,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/pending_tasks.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/recovery.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/segments.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ API.

`GET /_cat/segments/<index>`

`GET /_cat/segments`


[[cat-segments-path-params]]
==== {api-path-parms-title}
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/cat/shards.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ docs, the bytes it takes on disk, and the node where it's located.

`GET /_cat/shards/<index>`

`GET /_cat/shards`


[[cat-shards-path-params]]
==== {api-path-parms-title}
Expand Down Expand Up @@ -269,6 +271,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

Copy link
Contributor

@jakelandis jakelandis Oct 9, 2019

Choose a reason for hiding this comment

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

i think this should also include bytes

GET _cat/shards?h=sm&bytes=b

Copy link
Contributor Author

@jrodewig jrodewig Oct 9, 2019

Choose a reason for hiding this comment

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

It looks like bytes is already documented for this API:
https://github.com/elastic/elasticsearch/blame/be233f3d235b39d9315fc79974e9b69f20b1fe38/docs/reference/cat/shards.asciidoc#L29

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


Expand Down
4 changes: 4 additions & 0 deletions docs/reference/cat/snapshots.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ more repositories. A snapshot is a backup of an index or running {es} cluster.

`GET /_cat/snapshots/<repository>`

`GET /_cat/snapshots`


[[cat-snapshots-path-params]]
==== {api-path-parms-title}
Expand Down Expand Up @@ -103,6 +105,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/tasks.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cat/templates.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ and <<mapping,field mappings>> to new indices at creation.

`GET /_cat/templates/<template_name>`

`GET /_cat/templates`


[[cat-templates-path-params]]
==== {api-path-parms-title}
Expand Down
3 changes: 3 additions & 0 deletions docs/reference/cat/thread_pool.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ pools.

`GET /_cat/thread_pool/<thread_pool>`

`GET /_cat/thread_pool`


[[cat-thread-pool-path-params]]
==== {api-path-parms-title}

Expand Down
11 changes: 6 additions & 5 deletions docs/reference/rest-api/common-parms.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -433,11 +433,6 @@ such as `1264`.
A value of `-1` indicates {es} was unable to compute this number.
end::memory[]

tag::name[]
Copy link
Contributor Author

@jrodewig jrodewig Oct 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Replaced with https://github.com/elastic/elasticsearch/pull/47672/files#diff-38f70f3453c23ad1fda645b01d00773cL19

`<name>`::
(Optional, string) Comma-separated list of alias names to return.
end::name[]

tag::node-id[]
`<node_id>`::
(Optional, string) Comma-separated list of node IDs or names used to limit
Expand Down Expand Up @@ -682,6 +677,12 @@ tag::terminate_after[]
upon reaching which the query execution will terminate early.
end::terminate_after[]

tag::time[]
`time`::
(Optional, <<time-units,time units>>)
Unit used to display time values.
end::time[]

tag::timeoutparms[]

tag::timeout[]
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"ts":{
"type":"boolean",
"description":"Set to false to disable timestamping",
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down
30 changes: 30 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.nodes.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,23 @@
]
},
"params":{
"bytes":{
"type":"enum",
"description":"The unit in which to display byte values",
"options":[
"b",
"k",
"kb",
"m",
"mb",
"g",
"gb",
"t",
"tb",
"p",
"pb"
]
},
"format":{
"type":"string",
"description":"a short version of the Accept header, e.g. json, yaml"
Expand Down Expand Up @@ -45,6 +62,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.pending_tasks.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.recovery.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.shards.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.snapshots.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down
13 changes: 13 additions & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.tasks.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,19 @@
"type":"list",
"description":"Comma-separated list of column names or column aliases to sort by"
},
"time":{
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
]
},
"v":{
"type":"boolean",
"description":"Verbose mode. Display column headers",
Expand Down