From 9b567e4779c4ba7001164e85a5974fa9ad9dcb1d Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 24 May 2023 10:29:47 -0700 Subject: [PATCH 1/3] Add descriptions for some cat APIs --- output/schema/schema.json | 150 +++++++++++++----- output/schema/validation-errors.json | 2 - output/typescript/types.ts | 1 + .../cat/aliases/CatAliasesRequest.ts | 5 + .../cat/allocation/CatAllocationRequest.ts | 5 + specification/cat/allocation/types.ts | 24 +-- .../CatComponentTemplatesRequest.ts | 6 + specification/cat/count/CatCountRequest.ts | 9 ++ .../cat/fielddata/CatFielddataRequest.ts | 11 ++ specification/cat/health/CatHealthRequest.ts | 20 +++ .../cat/indices/CatIndicesRequest.ts | 26 +++ .../CatDataFrameAnalyticsRequest.ts | 1 + specification/cat/ml_jobs/CatJobsRequest.ts | 1 + 13 files changed, 210 insertions(+), 51 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index 250559b359..e3a0be9d73 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -425,6 +425,11 @@ "docId": "cat-alias", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-alias.html", "name": "cat.aliases", + "privileges": { + "index": [ + "view_index_metadata" + ] + }, "request": { "name": "Request", "namespace": "cat.aliases" @@ -461,6 +466,11 @@ "docId": "cat-allocation", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-allocation.html", "name": "cat.allocation", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cat.allocation" @@ -496,6 +506,11 @@ "description": "Returns information about existing component_templates templates.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/cat-component-templates.html", "name": "cat.component_templates", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cat.component_templates" @@ -532,6 +547,11 @@ "docId": "cat-count", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-count.html", "name": "cat.count", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "cat.count" @@ -568,6 +588,11 @@ "docId": "cat-fielddata", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-fielddata.html", "name": "cat.fielddata", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cat.fielddata" @@ -604,6 +629,11 @@ "docId": "cat-health", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-health.html", "name": "cat.health", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cat.health" @@ -663,6 +693,14 @@ "docId": "cat-indices", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-indices.html", "name": "cat.indices", + "privileges": { + "cluster": [ + "monitor" + ], + "index": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cat.indices" @@ -729,6 +767,11 @@ "docId": "cat-dfanalytics", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-dfanalytics.html", "name": "cat.ml_data_frame_analytics", + "privileges": { + "cluster": [ + "monitor_ml" + ] + }, "request": { "name": "Request", "namespace": "cat.ml_data_frame_analytics" @@ -75546,7 +75589,7 @@ "body": { "kind": "no_body" }, - "description": "Shows information about currently configured aliases to indices including filter and routing infos.", + "description": "Retrieves the cluster’s index aliases, including filter and routing information.\nThe API does not return data stream aliases.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.", "inherits": { "type": { "name": "CatRequestBase", @@ -75560,7 +75603,7 @@ }, "path": [ { - "description": "A comma-separated list of alias names to return", + "description": "A comma-separated list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`.", "name": "name", "required": false, "type": { @@ -75586,7 +75629,7 @@ } } ], - "specLocation": "cat/aliases/CatAliasesRequest.ts#L23-L36" + "specLocation": "cat/aliases/CatAliasesRequest.ts#L23-L41" }, { "body": { @@ -75620,7 +75663,7 @@ "aliases": [ "s" ], - "description": "number of shards on node", + "description": "Number of primary and replica shards assigned to the node.", "name": "shards", "required": false, "type": { @@ -75636,7 +75679,7 @@ "di", "diskIndices" ], - "description": "disk used by ES indices", + "description": "Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards.\nIMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.", "name": "disk.indices", "required": false, "type": { @@ -75664,7 +75707,7 @@ "du", "diskUsed" ], - "description": "disk used (total, not just ES)", + "description": "Total disk space in use.\nElasticsearch retrieves this metric from the node’s operating system (OS).\nThe metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node.\nUnlike `disk.indices`, this metric does not double-count disk space for hard-linked files.", "name": "disk.used", "required": false, "type": { @@ -75692,7 +75735,7 @@ "da", "diskAvail" ], - "description": "disk available", + "description": "Free disk space available to Elasticsearch.\nElasticsearch retrieves this metric from the node’s operating system.\nDisk-based shard allocation uses this metric to assign shards to nodes based on available disk space.", "name": "disk.avail", "required": false, "type": { @@ -75720,7 +75763,7 @@ "dt", "diskTotal" ], - "description": "total capacity of all volumes", + "description": "Total disk space for the node, including in-use and available space.", "name": "disk.total", "required": false, "type": { @@ -75748,7 +75791,7 @@ "dp", "diskPercent" ], - "description": "percent disk used", + "description": "Total percentage of disk space in use. Calculated as `disk.used / disk.total`.", "name": "disk.percent", "required": false, "type": { @@ -75775,7 +75818,7 @@ "aliases": [ "h" ], - "description": "host of node", + "description": "Network host for the node. Set using the `network.host` setting.", "name": "host", "required": false, "type": { @@ -75799,7 +75842,7 @@ } }, { - "description": "ip of node", + "description": "IP address and port for the node.", "name": "ip", "required": false, "type": { @@ -75826,7 +75869,7 @@ "aliases": [ "n" ], - "description": "name of node", + "description": "Name for the node. Set using the `node.name` setting.", "name": "node", "required": false, "type": { @@ -75838,7 +75881,7 @@ } } ], - "specLocation": "cat/allocation/types.ts#L24-L69" + "specLocation": "cat/allocation/types.ts#L24-L75" }, { "attachedBehaviors": [ @@ -75848,7 +75891,7 @@ "body": { "kind": "no_body" }, - "description": "Provides a snapshot of how many shards are allocated to each data node and how much disk space they are using.", + "description": "Provides a snapshot of the number of shards allocated to each data node and their disk space.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.", "inherits": { "type": { "name": "CatRequestBase", @@ -75862,7 +75905,7 @@ }, "path": [ { - "description": "A comma-separated list of node IDs or names to limit the returned information", + "description": "Comma-separated list of node identifiers or names used to limit the returned information.", "name": "node_id", "required": false, "type": { @@ -75876,7 +75919,7 @@ ], "query": [ { - "description": "The unit in which to display byte values", + "description": "The unit used to display byte values.", "name": "bytes", "required": false, "type": { @@ -75888,7 +75931,7 @@ } } ], - "specLocation": "cat/allocation/CatAllocationRequest.ts#L23-L36" + "specLocation": "cat/allocation/CatAllocationRequest.ts#L23-L41" }, { "body": { @@ -76006,7 +76049,7 @@ "body": { "kind": "no_body" }, - "description": "Returns information about existing component_templates templates.", + "description": "Returns information about component templates in a cluster.\nComponent templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.\nThey are not intended for use by applications. For application consumption, use the get component template API.", "inherits": { "type": { "name": "CatRequestBase", @@ -76020,7 +76063,7 @@ }, "path": [ { - "description": "A pattern that returned component template names must match", + "description": "The name of the component template. Accepts wildcard expressions. If omitted, all component templates are returned.", "name": "name", "required": false, "type": { @@ -76033,7 +76076,7 @@ } ], "query": [], - "specLocation": "cat/component_templates/CatComponentTemplatesRequest.ts#L22-L31" + "specLocation": "cat/component_templates/CatComponentTemplatesRequest.ts#L22-L37" }, { "body": { @@ -76142,7 +76185,7 @@ "body": { "kind": "no_body" }, - "description": "Provides quick access to the document count of the entire cluster, or individual indices.", + "description": "Provides quick access to a document count for a data stream, an index, or an entire cluster.\nNOTE: The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.\nThey are not intended for use by applications. For application consumption, use the count API.", "inherits": { "type": { "name": "CatRequestBase", @@ -76156,7 +76199,7 @@ }, "path": [ { - "description": "A comma-separated list of index names to limit the returned information", + "description": "Comma-separated list of data streams, indices, and aliases used to limit the request.\nSupports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`.", "name": "index", "required": false, "type": { @@ -76169,7 +76212,7 @@ } ], "query": [], - "specLocation": "cat/count/CatCountRequest.ts#L23-L33" + "specLocation": "cat/count/CatCountRequest.ts#L23-L42" }, { "body": { @@ -76291,7 +76334,7 @@ "body": { "kind": "no_body" }, - "description": "Shows how much heap memory is currently being used by fielddata on every data node in the cluster.", + "description": "Returns the amount of heap memory currently used by the field data cache on every data node in the cluster.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.\nThey are not intended for use by applications. For application consumption, use the nodes stats API.", "inherits": { "type": { "name": "CatRequestBase", @@ -76305,7 +76348,7 @@ }, "path": [ { - "description": "A comma-separated list of fields to return the fielddata size", + "description": "Comma-separated list of fields used to limit returned information.\nTo retrieve all fields, omit this parameter.", "name": "fields", "required": false, "type": { @@ -76319,7 +76362,7 @@ ], "query": [ { - "description": "The unit in which to display byte values", + "description": "The unit used to display byte values.", "name": "bytes", "required": false, "type": { @@ -76329,9 +76372,21 @@ "namespace": "_types" } } + }, + { + "description": "Comma-separated list of fields used to limit returned information.", + "name": "fields", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "Fields", + "namespace": "_types" + } + } } ], - "specLocation": "cat/fielddata/CatFielddataRequest.ts#L23-L36" + "specLocation": "cat/fielddata/CatFielddataRequest.ts#L23-L47" }, { "body": { @@ -76618,7 +76673,7 @@ "body": { "kind": "no_body" }, - "description": "Returns a concise representation of the cluster health.", + "description": "Returns the health status of a cluster, similar to the cluster health API.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.\nThey are not intended for use by applications. For application consumption, use the cluster health API.\nThis API is often used to check malfunctioning clusters.\nTo help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats:\n`HH:MM:SS`, which is human-readable but includes no date information;\n`Unix epoch time`, which is machine-sortable and includes date information.\nThe latter format is useful for cluster recoveries that take multiple days.\nYou can use the cat health API to verify cluster health across multiple nodes.\nYou also can use the API to track the recovery of a large cluster over a longer period of time.", "inherits": { "type": { "name": "CatRequestBase", @@ -76633,9 +76688,22 @@ "path": [], "query": [ { - "description": "Set to false to disable timestamping", + "description": "The unit used to display time values.", + "name": "time", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "TimeUnit", + "namespace": "_types" + } + } + }, + { + "description": "If true, returns `HH:MM:SS` and Unix epoch timestamps.", "name": "ts", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -76645,7 +76713,7 @@ } } ], - "specLocation": "cat/health/CatHealthRequest.ts#L22-L32" + "specLocation": "cat/health/CatHealthRequest.ts#L23-L52" }, { "body": { @@ -78790,7 +78858,7 @@ "body": { "kind": "no_body" }, - "description": "Returns information about indices: number of primaries and replicas, document counts, disk size, ...", + "description": "Returns high-level information about indices in a cluster, including backing indices for data streams.\nIMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.\nThey are not intended for use by applications. For application consumption, use the get index API.\nUse the cat indices API to get the following information for each index in a cluster: shard count; document count; deleted document count; primary store size; total store size of all shards, including shard replicas.\nThese metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents.\nTo get an accurate count of Elasticsearch documents, use the cat count or count APIs.", "inherits": { "type": { "name": "CatRequestBase", @@ -78804,7 +78872,7 @@ }, "path": [ { - "description": "A comma-separated list of index names to limit the returned information", + "description": "Comma-separated list of data streams, indices, and aliases used to limit the request.\nSupports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`.", "name": "index", "required": false, "type": { @@ -78818,7 +78886,7 @@ ], "query": [ { - "description": "The unit in which to display byte values", + "description": "The unit used to display byte values.", "name": "bytes", "required": false, "type": { @@ -78830,7 +78898,7 @@ } }, { - "description": "Whether to expand wildcard expression to concrete indices that are open, closed or both.", + "description": "The type of index that wildcard patterns can match.", "name": "expand_wildcards", "required": false, "type": { @@ -78842,7 +78910,7 @@ } }, { - "description": "A health status (\"green\", \"yellow\", or \"red\" to filter only indices matching the specified health status", + "description": "The health status used to limit returned indices. By default, the response includes indices of any health status.", "name": "health", "required": false, "type": { @@ -78854,9 +78922,10 @@ } }, { - "description": "If set to true segment stats will include stats for segments that are not currently loaded into memory", + "description": "If true, the response includes information from segments that are not loaded into memory.", "name": "include_unloaded_segments", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -78866,9 +78935,10 @@ } }, { - "description": "Set to true to return stats only for primary shards", + "description": "If true, the response only includes information from primary shards.", "name": "pri", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -78878,7 +78948,7 @@ } }, { - "description": "The unit in which to display time values", + "description": "The unit used to display time values.", "name": "time", "required": false, "type": { @@ -78890,7 +78960,7 @@ } } ], - "specLocation": "cat/indices/CatIndicesRequest.ts#L24-L42" + "specLocation": "cat/indices/CatIndicesRequest.ts#L24-L68" }, { "body": { @@ -79376,7 +79446,7 @@ } } ], - "specLocation": "cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts#L24-L57" + "specLocation": "cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts#L24-L58" }, { "body": { diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index 47fa620d92..96b9ce4011 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -145,7 +145,6 @@ "Request: missing json spec query parameter 'help'", "Request: missing json spec query parameter 's'", "Request: missing json spec query parameter 'v'", - "Request: missing json spec query parameter 'fields'", "request definition cat.fielddata:Request / body - A request with inherited properties must have a PropertyBody" ], "response": [] @@ -156,7 +155,6 @@ "Request: missing json spec query parameter 'h'", "Request: missing json spec query parameter 'help'", "Request: missing json spec query parameter 's'", - "Request: missing json spec query parameter 'time'", "Request: missing json spec query parameter 'v'", "request definition cat.health:Request / body - A request with inherited properties must have a PropertyBody" ], diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 0c83f8dafd..e863dcab53 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -6394,6 +6394,7 @@ export interface CatHealthHealthRecord { } export interface CatHealthRequest extends CatCatRequestBase { + time?: TimeUnit ts?: boolean } diff --git a/specification/cat/aliases/CatAliasesRequest.ts b/specification/cat/aliases/CatAliasesRequest.ts index 319ee52ceb..2655b51ea6 100644 --- a/specification/cat/aliases/CatAliasesRequest.ts +++ b/specification/cat/aliases/CatAliasesRequest.ts @@ -21,13 +21,18 @@ import { CatRequestBase } from '@cat/_types/CatBase' import { ExpandWildcards, Names } from '@_types/common' /** + * Retrieves the cluster’s index aliases, including filter and routing information. + * The API does not return data stream aliases. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. * @rest_spec_name cat.aliases * @since 0.0.0 * @stability stable * @doc_id cat-alias + * @index_privileges view_index_metadata */ export interface Request extends CatRequestBase { path_parts: { + /** A comma-separated list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`. */ name?: Names } query_parameters: { diff --git a/specification/cat/allocation/CatAllocationRequest.ts b/specification/cat/allocation/CatAllocationRequest.ts index a4d8de3d90..37f58d5c7a 100644 --- a/specification/cat/allocation/CatAllocationRequest.ts +++ b/specification/cat/allocation/CatAllocationRequest.ts @@ -21,16 +21,21 @@ import { CatRequestBase } from '@cat/_types/CatBase' import { Bytes, NodeIds } from '@_types/common' /** + * Provides a snapshot of the number of shards allocated to each data node and their disk space. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. * @rest_spec_name cat.allocation * @since 0.0.0 * @stability stable * @doc_id cat-allocation + * @cluster_privileges monitor */ export interface Request extends CatRequestBase { path_parts: { + /** Comma-separated list of node identifiers or names used to limit the returned information. */ node_id?: NodeIds } query_parameters: { + /** The unit used to display byte values. */ bytes?: Bytes } } diff --git a/specification/cat/allocation/types.ts b/specification/cat/allocation/types.ts index 09067d4583..004fe44b02 100644 --- a/specification/cat/allocation/types.ts +++ b/specification/cat/allocation/types.ts @@ -23,46 +23,52 @@ import { Percentage } from '@_types/Numeric' export class AllocationRecord { /** - * number of shards on node + * Number of primary and replica shards assigned to the node. * @aliases s */ shards?: string /** - * disk used by ES indices + * Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards. + * IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index. * @aliases di,diskIndices */ 'disk.indices'?: ByteSize | null /** - * disk used (total, not just ES) + * Total disk space in use. + * Elasticsearch retrieves this metric from the node’s operating system (OS). + * The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node. + * Unlike `disk.indices`, this metric does not double-count disk space for hard-linked files. * @aliases du,diskUsed */ 'disk.used'?: ByteSize | null /** - * disk available + * Free disk space available to Elasticsearch. + * Elasticsearch retrieves this metric from the node’s operating system. + * Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space. * @aliases da,diskAvail */ 'disk.avail'?: ByteSize | null /** - * total capacity of all volumes + * Total disk space for the node, including in-use and available space. * @aliases dt,diskTotal */ 'disk.total'?: ByteSize | null /** - * percent disk used + * Total percentage of disk space in use. Calculated as `disk.used / disk.total`. * @aliases dp,diskPercent */ 'disk.percent'?: Percentage | null /** - * host of node + * Network host for the node. Set using the `network.host` setting. * @aliases h */ host?: Host | null /** - * ip of node + * IP address and port for the node. */ ip?: Ip | null /** - * name of node + * Name for the node. Set using the `node.name` setting. * @aliases n */ node?: string diff --git a/specification/cat/component_templates/CatComponentTemplatesRequest.ts b/specification/cat/component_templates/CatComponentTemplatesRequest.ts index 4b0f495c73..be108e24f3 100644 --- a/specification/cat/component_templates/CatComponentTemplatesRequest.ts +++ b/specification/cat/component_templates/CatComponentTemplatesRequest.ts @@ -20,12 +20,18 @@ import { CatRequestBase } from '@cat/_types/CatBase' /** + * Returns information about component templates in a cluster. + * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. + * They are not intended for use by applications. For application consumption, use the get component template API. * @rest_spec_name cat.component_templates * @since 5.1.0 * @stability stable + * @cluster_privileges monitor */ export interface Request extends CatRequestBase { path_parts: { + /** The name of the component template. Accepts wildcard expressions. If omitted, all component templates are returned. */ name?: string } } diff --git a/specification/cat/count/CatCountRequest.ts b/specification/cat/count/CatCountRequest.ts index 763e38535e..848f5ee290 100644 --- a/specification/cat/count/CatCountRequest.ts +++ b/specification/cat/count/CatCountRequest.ts @@ -21,13 +21,22 @@ import { CatRequestBase } from '@cat/_types/CatBase' import { Indices } from '@_types/common' /** + * Provides quick access to a document count for a data stream, an index, or an entire cluster. + * NOTE: The document count only includes live documents, not deleted documents which have not yet been removed by the merge process. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. + * They are not intended for use by applications. For application consumption, use the count API. * @rest_spec_name cat.count * @since 0.0.0 * @stability stable * @doc_id cat-count + * @index_privileges read */ export interface Request extends CatRequestBase { path_parts: { + /** + * Comma-separated list of data streams, indices, and aliases used to limit the request. + * Supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. + */ index?: Indices } } diff --git a/specification/cat/fielddata/CatFielddataRequest.ts b/specification/cat/fielddata/CatFielddataRequest.ts index 34d9a4837b..2bdf0dca9d 100644 --- a/specification/cat/fielddata/CatFielddataRequest.ts +++ b/specification/cat/fielddata/CatFielddataRequest.ts @@ -21,16 +21,27 @@ import { CatRequestBase } from '@cat/_types/CatBase' import { Bytes, Fields } from '@_types/common' /** + * Returns the amount of heap memory currently used by the field data cache on every data node in the cluster. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. + * They are not intended for use by applications. For application consumption, use the nodes stats API. * @rest_spec_name cat.fielddata * @since 0.0.0 * @stability stable * @doc_id cat-fielddata + * @cluster_privileges monitor */ export interface Request extends CatRequestBase { path_parts: { + /** + * Comma-separated list of fields used to limit returned information. + * To retrieve all fields, omit this parameter. + */ fields?: Fields } query_parameters: { + /** The unit used to display byte values. */ bytes?: Bytes + /** Comma-separated list of fields used to limit returned information. */ + fields?: Fields } } diff --git a/specification/cat/health/CatHealthRequest.ts b/specification/cat/health/CatHealthRequest.ts index ae31c1e31c..4d68dea7d2 100644 --- a/specification/cat/health/CatHealthRequest.ts +++ b/specification/cat/health/CatHealthRequest.ts @@ -18,15 +18,35 @@ */ import { CatRequestBase } from '@cat/_types/CatBase' +import { TimeUnit } from '@_types/Time' /** + * Returns the health status of a cluster, similar to the cluster health API. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. + * They are not intended for use by applications. For application consumption, use the cluster health API. + * This API is often used to check malfunctioning clusters. + * To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: + * `HH:MM:SS`, which is human-readable but includes no date information; + * `Unix epoch time`, which is machine-sortable and includes date information. + * The latter format is useful for cluster recoveries that take multiple days. + * You can use the cat health API to verify cluster health across multiple nodes. + * You also can use the API to track the recovery of a large cluster over a longer period of time. * @rest_spec_name cat.health * @since 0.0.0 * @stability stable * @doc_id cat-health + * @cluster_privileges monitor */ export interface Request extends CatRequestBase { query_parameters: { + /** + * The unit used to display time values. + */ + time?: TimeUnit + /** + * If true, returns `HH:MM:SS` and Unix epoch timestamps. + * @server_default true + */ ts?: boolean } } diff --git a/specification/cat/indices/CatIndicesRequest.ts b/specification/cat/indices/CatIndicesRequest.ts index 2aad222b8f..f01456a958 100644 --- a/specification/cat/indices/CatIndicesRequest.ts +++ b/specification/cat/indices/CatIndicesRequest.ts @@ -22,21 +22,47 @@ import { Bytes, ExpandWildcards, HealthStatus, Indices } from '@_types/common' import { TimeUnit } from '@_types/Time' /** + * Returns high-level information about indices in a cluster, including backing indices for data streams. + * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. + * They are not intended for use by applications. For application consumption, use the get index API. + * Use the cat indices API to get the following information for each index in a cluster: shard count; document count; deleted document count; primary store size; total store size of all shards, including shard replicas. + * These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. + * To get an accurate count of Elasticsearch documents, use the cat count or count APIs. * @rest_spec_name cat.indices * @since 0.0.0 * @stability stable * @doc_id cat-indices + * @cluster_privileges monitor + * @index_privileges monitor */ export interface Request extends CatRequestBase { path_parts: { + /** + * Comma-separated list of data streams, indices, and aliases used to limit the request. + * Supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. + */ index?: Indices } query_parameters: { + /** The unit used to display byte values. */ bytes?: Bytes + /** + * The type of index that wildcard patterns can match. + */ expand_wildcards?: ExpandWildcards + /** The health status used to limit returned indices. By default, the response includes indices of any health status. */ health?: HealthStatus + /** + * If true, the response includes information from segments that are not loaded into memory. + * @server_default false + */ include_unloaded_segments?: boolean + /** + * If true, the response only includes information from primary shards. + * @server_default false + */ pri?: boolean + /** The unit used to display time values. */ time?: TimeUnit } } diff --git a/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts b/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts index 6b079d678a..48085ba9c4 100644 --- a/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts +++ b/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts @@ -32,6 +32,7 @@ import { Duration } from '@_types/Time' * @since 7.7.0 * @stability stable * @doc_id cat-dfanalytics + * @cluster_privileges monitor_ml */ export interface Request extends CatRequestBase { path_parts: { diff --git a/specification/cat/ml_jobs/CatJobsRequest.ts b/specification/cat/ml_jobs/CatJobsRequest.ts index 1d706808f4..81a801c934 100644 --- a/specification/cat/ml_jobs/CatJobsRequest.ts +++ b/specification/cat/ml_jobs/CatJobsRequest.ts @@ -73,5 +73,6 @@ export interface Request extends CatRequestBase { * The unit used to display time values. */ time?: TimeUnit + } } } From 0d361c07dbe7a162baf18f2de26c3454db520070 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 24 May 2023 10:34:17 -0700 Subject: [PATCH 2/3] Fix typo --- specification/cat/ml_jobs/CatJobsRequest.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/cat/ml_jobs/CatJobsRequest.ts b/specification/cat/ml_jobs/CatJobsRequest.ts index 81a801c934..1d706808f4 100644 --- a/specification/cat/ml_jobs/CatJobsRequest.ts +++ b/specification/cat/ml_jobs/CatJobsRequest.ts @@ -73,6 +73,5 @@ export interface Request extends CatRequestBase { * The unit used to display time values. */ time?: TimeUnit - } } } From 295722b59bc31ec840e92450de60db2994c70591 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 24 May 2023 11:14:49 -0700 Subject: [PATCH 3/3] Fix formatting --- specification/cat/indices/CatIndicesRequest.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/cat/indices/CatIndicesRequest.ts b/specification/cat/indices/CatIndicesRequest.ts index f01456a958..6bf7681985 100644 --- a/specification/cat/indices/CatIndicesRequest.ts +++ b/specification/cat/indices/CatIndicesRequest.ts @@ -55,7 +55,7 @@ export interface Request extends CatRequestBase { /** * If true, the response includes information from segments that are not loaded into memory. * @server_default false - */ + */ include_unloaded_segments?: boolean /** * If true, the response only includes information from primary shards.