Skip to content

CAT API automation (Part II) #9060

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
Naarcha-AWS merged 40 commits into from
Jan 22, 2025
Merged

CAT API automation (Part II) #9060

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
f95be66
Add CAT API automation
Naarcha-AWS Jan 9, 2025
ba94920
Add CAT API reference
Naarcha-AWS Jan 9, 2025
7a45d1d
Update cat-pit-segments.md
Naarcha-AWS Jan 9, 2025
2e56e27
Fix mustache template
Naarcha-AWS Jan 9, 2025
5314b42
Fix table spacing
Naarcha-AWS Jan 9, 2025
e6d2233
Updated expected output
Naarcha-AWS Jan 9, 2025
d0b2fa0
Revert back to type
Naarcha-AWS Jan 9, 2025
cbdd6c1
Fix pretty test expected result
Naarcha-AWS Jan 9, 2025
f91bbe7
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 9, 2025
a4358fb
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 13, 2025
1aea840
Add updated tables.
Naarcha-AWS Jan 13, 2025
e27ec68
Add CAT API automation with updated spec-insert
Naarcha-AWS Jan 13, 2025
9f7b951
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 13, 2025
bb750d3
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 17, 2025
e4884bc
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 17, 2025
62ef5e4
Add updated CAT API tables
Naarcha-AWS Jan 17, 2025
03a800d
See if an extra space will fix the table.
Naarcha-AWS Jan 17, 2025
e0f4666
Update mustache template to add spaces
Naarcha-AWS Jan 17, 2025
658063c
Mustache template update
Naarcha-AWS Jan 17, 2025
db7760d
Update expected output.
Naarcha-AWS Jan 17, 2025
4035f06
Add lines to renderer.
Naarcha-AWS Jan 17, 2025
d27cd84
Add new lines
Naarcha-AWS Jan 17, 2025
ac5421a
Try another way
Naarcha-AWS Jan 17, 2025
8dcf38a
Fix mustache spec
Naarcha-AWS Jan 17, 2025
daec3e4
Add line breaks correctly.
Naarcha-AWS Jan 17, 2025
e1fc7db
Update endpoint expected output.
Naarcha-AWS Jan 17, 2025
7fc3b0e
Fix renderer spacing. Fix tests.
Naarcha-AWS Jan 17, 2025
8da5e7a
Fix expected output.
Naarcha-AWS Jan 17, 2025
2ff38f1
Fix table
Naarcha-AWS Jan 17, 2025
5159c33
Update expected results
Naarcha-AWS Jan 17, 2025
6eabb6a
Fix output, again.
Naarcha-AWS Jan 17, 2025
92bd3d6
Add another test
Naarcha-AWS Jan 17, 2025
d6de5f9
Theoretically the correct spacing.
Naarcha-AWS Jan 17, 2025
cb3c4da
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 17, 2025
6437c1d
Add Theo's suggestions
Naarcha-AWS Jan 17, 2025
9a848c0
Fix BR tags
Naarcha-AWS Jan 21, 2025
bc95b50
Fix expected output.
Naarcha-AWS Jan 21, 2025
80dcf37
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 21, 2025
1495f2a
Make wildcard defintion consistent.
Naarcha-AWS Jan 21, 2025
4d96caa
Merge branch 'main' into cat-api-automation
Naarcha-AWS Jan 21, 2025
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
7 changes: 5 additions & 2 deletions _api-reference/cat/cat-aliases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,14 @@ GET /_cat/aliases/{name}
<!-- spec_insert_start
api: cat.aliases
component: query_parameters
columns: Parameter,Type,Description,Default
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters
Parameter | Type | Description | Default

The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
Copy link
Collaborator

@kolchfa-aws kolchfa-aws Jan 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

The "Default" column is not populated for some rows so the table is not displayed correctly (in all these files).

Screenshot 2025-01-14 at 8 55 55 AM

Also, since the table is automatically generated, could we have consistency in pipe symbols: either no pipe symbols on either end of the row, or pipe symbols on both ends of the row (the latter is more extensible).

Copy link
Contributor Author

@Naarcha-AWS Naarcha-AWS Jan 14, 2025

Choose a reason for hiding this comment

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

It makes sense to add |'s at the end and the beginning to me. @nhtruong, would that be difficult to change in the workflow?

The pretty setting will add pipes but also add additional spacing. One solution is we could enable that by default, since the tables aren't going to be touched directly anyways.

Copy link
Collaborator

@kolchfa-aws kolchfa-aws Jan 14, 2025

Choose a reason for hiding this comment

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

I would just add pipe symbols regardless of pretty. Also, there should be no empty cells in the table. Where there is no default, we should add N/A. However, it's strange that there was no default automatically provided for expand_wildcards. Is it missing from the spec?

Copy link
Contributor

@nhtruong nhtruong Jan 14, 2025

Choose a reason for hiding this comment

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

It's not difficult. Are you saying with pretty: false (the default), the pipes are never present and with pretty: true they are there? OR are you saying that with pretty: false the pipes are there sometimes (this inconsistency would be a bug)

Copy link
Contributor

@nhtruong nhtruong Jan 14, 2025

Choose a reason for hiding this comment

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

Regarding Default values not showing: Are they on the spec but not in the generated tables?

Copy link
Collaborator

@kolchfa-aws kolchfa-aws Jan 14, 2025

Choose a reason for hiding this comment

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

I would go with adding pipes at the ends in any case (for pretty either true or false). This way, all tables are consistent (have pipes at either end at all times).

Copy link
Contributor Author

@Naarcha-AWS Naarcha-AWS Jan 14, 2025

Choose a reason for hiding this comment

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

Right now, according to the expected output, pretty: true does include pipes at the end and the beginning.

:--- | :--- | :--- | :---
`expand_wildcards` | List or String | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. |
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
Expand Down
7 changes: 5 additions & 2 deletions _api-reference/cat/cat-allocation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,14 @@ GET /_cat/allocation/{node_id}
<!-- spec_insert_start
api: cat.allocation
component: query_parameters
columns: Parameter,Type,Description,Default
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters
Parameter | Type | Description | Default

The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`bytes` | String | The units used to display byte values. |
`cluster_manager_timeout` | String | A timeout for connection to the cluster manager node. |
Expand Down
33 changes: 27 additions & 6 deletions _api-reference/cat/cat-cluster_manager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,40 @@ has_children: false
The CAT cluster manager operation lists information that helps identify the elected cluster manager node.


<!-- spec_insert_start
api: cat.cluster_manager
component: endpoints
-->
## Endpoints

```json
GET _cat/cluster_manager
GET /_cat/cluster_manager
```
<!-- spec_insert_end -->


<!-- spec_insert_start
api: cat.cluster_manager
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`cluster_manager_timeout` | String | A timeout for connection to the cluster manager node. |
`format` | String | A short version of the HTTP `Accept` header, such as `json` or `yaml`. |
`h` | List | A comma-separated list of column names to display. |
`help` | Boolean | Returns help information. | `false`
`local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->


## Example requests
## Example request

```
GET _cat/cluster_manager?v
Expand Down
30 changes: 27 additions & 3 deletions _api-reference/cat/cat-count.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,36 @@ redirect_from:
The CAT count operation lists the number of documents in your cluster.


<!-- spec_insert_start
api: cat.count
component: endpoints
-->
## Endpoints

```json
GET _cat/count?v
GET _cat/count/<index>?v
GET /_cat/count
GET /_cat/count/{index}
```
<!-- spec_insert_end -->


<!-- spec_insert_start
api: cat.count
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
`h` | List | A comma-separated list of column names to display. |
`help` | Boolean | Returns help information. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->

## Example requests

Expand Down
32 changes: 25 additions & 7 deletions _api-reference/cat/cat-field-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,37 @@ redirect_from:

The CAT Field Data operation lists the memory size used by each field per node.


<!-- spec_insert_start
api: cat.fielddata
component: endpoints
-->
## Endpoints

```json
GET _cat/fielddata?v
GET _cat/fielddata/<field_name>?v
GET /_cat/fielddata
GET /_cat/fielddata/{fields}
```
<!-- spec_insert_end -->


<!-- spec_insert_start
api: cat.fielddata
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`bytes` | String | The units used to display byte values. |
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
`h` | List | A comma-separated list of column names to display. |
`help` | Boolean | Returns help information. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->

## Example requests

Expand Down
32 changes: 25 additions & 7 deletions _api-reference/cat/cat-health.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@
layout: default
title: CAT health
parent: CAT API

nav_order: 20
has_children: false
redirect_from:
Expand All @@ -16,18 +15,37 @@ redirect_from:
The CAT health operation lists the status of the cluster, how long the cluster has been up, the number of nodes, and other useful information that helps you analyze the health of your cluster.


<!-- spec_insert_start
api: cat.health
component: endpoints
-->
## Endpoints

```json
GET _cat/health?v
GET /_cat/health
```
<!-- spec_insert_end -->


<!-- spec_insert_start
api: cat.health
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
ts | Boolean | If true, returns HH:MM:SS and Unix epoch timestamps. Default is `true`.
The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
`h` | List | A comma-separated list of column names to display. |
`help` | Boolean | Returns help information. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`time` | String | The unit used to display time values. |
`ts` | Boolean | When `true`, returns `HH:MM:SS` and Unix epoch timestamps. | `true`
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->

## Example request

Expand Down
44 changes: 32 additions & 12 deletions _api-reference/cat/cat-indices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,44 @@ redirect_from:
The CAT indices operation lists information related to indexes, that is, how much disk space they are using, how many shards they have, their health status, and so on.


<!-- spec_insert_start
api: cat.indices
component: endpoints
-->
## Endpoints

```json
GET _cat/indices/<index>
GET _cat/indices
GET /_cat/indices
GET /_cat/indices/{index}
```
<!-- spec_insert_end -->


<!-- spec_insert_start
api: cat.indices
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
health | String | Limit indexes based on their health status. Supported values are `green`, `yellow`, and `red`.
include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is `false`.
cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
pri | Boolean | Whether to return information only from the primary shards. Default is `false`.
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`bytes` | String | The units used to display byte values. |
`cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. |
`expand_wildcards` | List or String | The type of index that wildcard patterns can match. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. |
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
`h` | List | A comma-separated list of column names to display. |
`health` | String | Limits indexes based on their health status. Supported values are `green`, `yellow`, and `red`. |
`help` | Boolean | Returns help information. | `false`
`include_unloaded_segments` | Boolean | Whether to include information from segments not loaded into memory. | `false`
`local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false`
`pri` | Boolean | When `true`, returns information only from the primary shards. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`time` | String | Specifies the time units. |
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->

## Example requests

Expand Down
31 changes: 25 additions & 6 deletions _api-reference/cat/cat-nodeattrs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,37 @@ redirect_from:
The CAT nodeattrs operation lists the attributes of custom nodes.


<!-- spec_insert_start
api: cat.nodeattrs
component: endpoints
-->
## Endpoints

```json
GET _cat/nodeattrs
GET /_cat/nodeattrs
```
<!-- spec_insert_end -->


<!-- spec_insert_start
api: cat.nodeattrs
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. |
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
`h` | List | A comma-separated list of column names to display. |
`help` | Boolean | Returns help information. | `false`
`local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->

## Example request

Expand Down
40 changes: 27 additions & 13 deletions _api-reference/cat/cat-nodes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,25 +17,39 @@ The CAT nodes operation lists node-level information, including node roles and l
A few important node metrics are `pid`, `name`, `cluster_manager`, `ip`, `port`, `version`, `build`, `jdk`, along with `disk`, `heap`, `ram`, and `file_desc`.


<!-- spec_insert_start
api: cat.nodes
component: endpoints
-->
## Endpoints

```json
GET _cat/nodes
GET /_cat/nodes
```
<!-- spec_insert_end -->

## Query parameters

All CAT nodes URL parameters are optional.

In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/api-reference/cat/index), you can specify the following parameters:
<!-- spec_insert_start
api: cat.nodes
component: query_parameters
columns: Parameter, Data type, Description, Default
include_deprecated: false
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
full_id | Boolean | If true, return the full node ID. If false, return the shortened node ID. Defaults to false.
cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is `false`.
The following table lists the available query parameters. All query parameters are optional.

Parameter | Data type | Description | Default
:--- | :--- | :--- | :---
`bytes` | String | The units used to display byte values. |
`cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. |
`format` | String | A short version of the `Accept` header, such as `json` or `yaml`. |
`full_id` | Boolean or String | When `true`, returns the full node ID. When `false`, returns the shortened node ID. | `false`
`h` | List | A comma-separated list of column names to display. |
`help` | Boolean | Returns help information. | `false`
`s` | List | A comma-separated list of column names or column aliases to sort by. |
`time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/). |
`v` | Boolean | Enables verbose mode, which displays column headers. | `false`
<!-- spec_insert_end -->

## Example request

Expand Down
Loading