From d021613b43df8d7d647afb268ef1a58b8ace6f4a Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 29 Jan 2025 10:04:30 -0800 Subject: [PATCH 1/3] [DOCS] Add descriptions for remote info API --- specification/_doc_ids/table.csv | 1 + .../remote_info/ClusterRemoteInfoRequest.ts | 13 ++++++-- .../remote_info/ClusterRemoteInfoResponse.ts | 30 +++++++++++++++++++ 3 files changed, 42 insertions(+), 2 deletions(-) diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index ab78c8a79b..428f3aef8b 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -413,6 +413,7 @@ ml-update-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{bran ml-upgrade-job-model-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ml-upgrade-job-model-snapshot.html modules-cluster,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cluster.html modules-cross-cluster-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html +modules-cross-cluster-optional,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#skip-unavailable-clusters modules-discovery-hosts-providers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-discovery-hosts-providers.html modules-fielddata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-fielddata.html modules-gateway-dangling-indices,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-gateway-dangling-indices.html diff --git a/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts b/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts index 5452d497b4..bce879205d 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts @@ -21,11 +21,20 @@ import { RequestBase } from '@_types/Base' /** * Get remote cluster information. - * Get all of the configured remote cluster information. - * This API returns connection and endpoint information keyed by the configured remote cluster alias. + * + * Get information about configured remote clusters. + * The API returns connection and endpoint information keyed by the configured remote cluster alias. + * + * > info + * > This API returns information that reflects current state on the local cluster. + * > The `connected` field does not necessarily reflect whether a remote cluster is down or unavailable, only whether there is currently an open connection to it. + * > Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster. + * > To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster). * @rest_spec_name cluster.remote_info * @availability stack since=6.1.0 stability=stable + * @cluster_privileges monitor * @doc_id cluster-remote-info + * @ext_doc_id modules-cross-cluster-search */ export interface Request extends RequestBase { urls: [ diff --git a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts index 583dc6c499..74d4e3510e 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts @@ -30,22 +30,52 @@ export class Response { export type ClusterRemoteInfo = ClusterRemoteSniffInfo | ClusterRemoteProxyInfo export class ClusterRemoteSniffInfo { + /** The connection mode for the remote cluster. */ mode: 'sniff' + /** + * If it is `true`, there is at least one open connection to the remote cluster. + * If it is `false`, it means that the cluster no longer has an open connection to the remote cluster. + * It does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost. + */ connected: boolean + /** The maximum number of connections maintained for the remote cluster when sniff mode is configured. */ max_connections_per_cluster: integer + /** The number of connected nodes in the remote cluster when sniff mode is configured. */ num_nodes_connected: long + /** The initial connect timeout for remote cluster connections. */ initial_connect_timeout: Duration + /** + * If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster. + * @ext_doc_id modules-cross-cluster-optional + */ skip_unavailable: boolean + /** + * The initial seed transport addresses of the remote cluster when sniff mode is configured. + */ seeds: string[] } export class ClusterRemoteProxyInfo { + /** The connection mode for the remote cluster. */ mode: 'proxy' + /** + * If it is `true`, there is at least one open connection to the remote cluster. + * If it is `false`, it means that the cluster no longer has an open connection to the remote cluster. + * It does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost. + */ connected: boolean + /** The initial connect timeout for remote cluster connections. */ initial_connect_timeout: Duration + /** + * If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster. + * @ext_doc_id modules-cross-cluster-optional + */ skip_unavailable: boolean + /** The address for remote connections when proxy mode is configured. */ proxy_address: string server_name: string + /** The number of open socket connections to the remote cluster when proxy mode is configured. */ num_proxy_sockets_connected: integer + /** The maximum number of socket connections to the remote cluster when proxy mode is configured. */ max_proxy_socket_connections: integer } From 9a2bcb24077b24c4d9bda1c13cb15b0a80ff998f Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 29 Jan 2025 10:23:56 -0800 Subject: [PATCH 2/3] [DOCS] Edit descriptions in resolve cluster API --- .../resolve_cluster/ResolveClusterRequest.ts | 33 ++++++++++++++----- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index 235b7a8321..e4426e3c53 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -22,8 +22,9 @@ import { ExpandWildcards, Names } from '@_types/common' /** * Resolve the cluster. - * Resolve the specified index expressions to return information about each cluster, including the local cluster, if included. - * Multiple patterns and remote clusters are supported. + * + * Resolve the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. + * If no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster. * * This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search. * @@ -32,7 +33,7 @@ import { ExpandWildcards, Names } from '@_types/common' * * For each cluster in the index expression, information is returned about: * - * * Whether the querying ("local") cluster is currently connected to each remote cluster in the index expression scope. + * * Whether the querying ("local") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint. * * Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`. * * Whether there are any indices, aliases, or data streams on that cluster that match the index expression. * * Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index). @@ -41,7 +42,7 @@ import { ExpandWildcards, Names } from '@_types/common' * For example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`. * Each cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`. * - * **Advantages of using this endpoint before a cross-cluster search** + * ## Advantages of using this endpoint before a cross-cluster search * * You may want to exclude a cluster or index from a search when: * @@ -49,6 +50,16 @@ import { ExpandWildcards, Names } from '@_types/common' * * A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search. * * The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.) * * A remote cluster is an older version that does not support the feature you want to use in your search. + * + * ## Test availability of remote clusters + * + * The `remote/info` endpoint is commonly used to test whether the "local" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not. + * The remote cluster may be available, while the local cluster is not currently connected to it. + * + * You can use the `_resolve/cluster` API to attempt to reconnect to remote clusters. + * For example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`. + * The `connected` field in the response will indicate whether it was successful. + * If a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status. * @rest_spec_name indices.resolve_cluster * @availability stack since=8.13.0 stability=stable * @doc_id indices-resolve-cluster-api @@ -63,16 +74,17 @@ export interface Request extends RequestBase { ] path_parts: { /** - * Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve. + * A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve. * Resources on remote clusters can be specified using the ``:`` syntax. */ name: Names } query_parameters: { /** - * If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing + * If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing * or closed indices. This behavior applies even if the request targets other open indices. For example, a request - * targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar. + * targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. + * @server_default true */ allow_no_indices?: boolean // default: true /** @@ -84,11 +96,14 @@ export interface Request extends RequestBase { */ expand_wildcards?: ExpandWildcards /** - * If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false. + * If true, concrete, expanded, or aliased indices are ignored when frozen. + * @server_default false + * @deprecated 7.16.0 */ ignore_throttled?: boolean // default: false /** - * If false, the request returns an error if it targets a missing or closed index. Defaults to false. + * If false, the request returns an error if it targets a missing or closed index. + * @server_default false */ ignore_unavailable?: boolean // default: false } From fa4f67c08d3c3df5e04c4258a16d6c10ae2b8255 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 29 Jan 2025 10:25:06 -0800 Subject: [PATCH 3/3] Generate output --- output/openapi/elasticsearch-openapi.json | 35 +++++++++++--- output/schema/schema.json | 56 ++++++++++++++++++----- 2 files changed, 72 insertions(+), 19 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 7d5dc3a2ad..7557f6b314 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -4334,7 +4334,10 @@ "cluster" ], "summary": "Get remote cluster information", - "description": "Get all of the configured remote cluster information.\nThis API returns connection and endpoint information keyed by the configured remote cluster alias.", + "description": "Get information about configured remote clusters.\nThe API returns connection and endpoint information keyed by the configured remote cluster alias.\n\n> info\n> This API returns information that reflects current state on the local cluster.\n> The `connected` field does not necessarily reflect whether a remote cluster is down or unavailable, only whether there is currently an open connection to it.\n> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.\n> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html" + }, "operationId": "cluster-remote-info", "responses": { "200": { @@ -15141,13 +15144,13 @@ "indices" ], "summary": "Resolve the cluster", - "description": "Resolve the specified index expressions to return information about each cluster, including the local cluster, if included.\nMultiple patterns and remote clusters are supported.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster in the index expression scope.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n**Advantages of using this endpoint before a cross-cluster search**\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.", + "description": "Resolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` endpoint is commonly used to test whether the \"local\" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", "operationId": "indices-resolve-cluster", "parameters": [ { "in": "path", "name": "name", - "description": "Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.", + "description": "A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.", "required": true, "deprecated": false, "schema": { @@ -15158,7 +15161,7 @@ { "in": "query", "name": "allow_no_indices", - "description": "If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.", + "description": "If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.", "deprecated": false, "schema": { "type": "boolean" @@ -15178,8 +15181,8 @@ { "in": "query", "name": "ignore_throttled", - "description": "If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false.", - "deprecated": false, + "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.", + "deprecated": true, "schema": { "type": "boolean" }, @@ -15188,7 +15191,7 @@ { "in": "query", "name": "ignore_unavailable", - "description": "If false, the request returns an error if it targets a missing or closed index. Defaults to false.", + "description": "If false, the request returns an error if it targets a missing or closed index.", "deprecated": false, "schema": { "type": "boolean" @@ -66034,27 +66037,36 @@ "type": "object", "properties": { "mode": { + "description": "The connection mode for the remote cluster.", "type": "string", "enum": [ "sniff" ] }, "connected": { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "type": "boolean" }, "max_connections_per_cluster": { + "description": "The maximum number of connections maintained for the remote cluster when sniff mode is configured.", "type": "number" }, "num_nodes_connected": { + "description": "The number of connected nodes in the remote cluster when sniff mode is configured.", "type": "number" }, "initial_connect_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "skip_unavailable": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters" + }, + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", "type": "boolean" }, "seeds": { + "description": "The initial seed transport addresses of the remote cluster when sniff mode is configured.", "type": "array", "items": { "type": "string" @@ -66075,30 +66087,39 @@ "type": "object", "properties": { "mode": { + "description": "The connection mode for the remote cluster.", "type": "string", "enum": [ "proxy" ] }, "connected": { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "type": "boolean" }, "initial_connect_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "skip_unavailable": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters" + }, + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", "type": "boolean" }, "proxy_address": { + "description": "The address for remote connections when proxy mode is configured.", "type": "string" }, "server_name": { "type": "string" }, "num_proxy_sockets_connected": { + "description": "The number of open socket connections to the remote cluster when proxy mode is configured.", "type": "number" }, "max_proxy_socket_connections": { + "description": "The maximum number of socket connections to the remote cluster when proxy mode is configured.", "type": "number" } }, diff --git a/output/schema/schema.json b/output/schema/schema.json index 716ca0d374..acc31b3f00 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2750,10 +2750,17 @@ "stability": "stable" } }, - "description": "Get remote cluster information.\nGet all of the configured remote cluster information.\nThis API returns connection and endpoint information keyed by the configured remote cluster alias.", + "description": "Get remote cluster information.\n\nGet information about configured remote clusters.\nThe API returns connection and endpoint information keyed by the configured remote cluster alias.\n\n> info\n> This API returns information that reflects current state on the local cluster.\n> The `connected` field does not necessarily reflect whether a remote cluster is down or unavailable, only whether there is currently an open connection to it.\n> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.\n> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).", "docId": "cluster-remote-info", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-remote-info.html", + "extDocId": "modules-cross-cluster-search", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html", "name": "cluster.remote_info", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cluster.remote_info" @@ -8437,7 +8444,7 @@ "stability": "stable" } }, - "description": "Resolve the cluster.\nResolve the specified index expressions to return information about each cluster, including the local cluster, if included.\nMultiple patterns and remote clusters are supported.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster in the index expression scope.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n**Advantages of using this endpoint before a cross-cluster search**\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.", + "description": "Resolve the cluster.\n\nResolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` endpoint is commonly used to test whether the \"local\" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", "docId": "indices-resolve-cluster-api", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-resolve-cluster-api.html", "name": "indices.resolve_cluster", @@ -111506,6 +111513,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -111514,6 +111522,7 @@ } }, { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "name": "connected", "required": true, "type": { @@ -111525,6 +111534,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -111536,6 +111546,9 @@ } }, { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", + "extDocId": "modules-cross-cluster-optional", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#skip-unavailable-clusters", "name": "skip_unavailable", "required": true, "type": { @@ -111547,6 +111560,7 @@ } }, { + "description": "The address for remote connections when proxy mode is configured.", "name": "proxy_address", "required": true, "type": { @@ -111569,6 +111583,7 @@ } }, { + "description": "The number of open socket connections to the remote cluster when proxy mode is configured.", "name": "num_proxy_sockets_connected", "required": true, "type": { @@ -111580,6 +111595,7 @@ } }, { + "description": "The maximum number of socket connections to the remote cluster when proxy mode is configured.", "name": "max_proxy_socket_connections", "required": true, "type": { @@ -111591,7 +111607,7 @@ } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L42-L51" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L58-L81" }, { "kind": "interface", @@ -111601,6 +111617,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -111609,6 +111626,7 @@ } }, { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "name": "connected", "required": true, "type": { @@ -111620,6 +111638,7 @@ } }, { + "description": "The maximum number of connections maintained for the remote cluster when sniff mode is configured.", "name": "max_connections_per_cluster", "required": true, "type": { @@ -111631,6 +111650,7 @@ } }, { + "description": "The number of connected nodes in the remote cluster when sniff mode is configured.", "name": "num_nodes_connected", "required": true, "type": { @@ -111642,6 +111662,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -111653,6 +111674,9 @@ } }, { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", + "extDocId": "modules-cross-cluster-optional", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#skip-unavailable-clusters", "name": "skip_unavailable", "required": true, "type": { @@ -111664,6 +111688,7 @@ } }, { + "description": "The initial seed transport addresses of the remote cluster when sniff mode is configured.", "name": "seeds", "required": true, "type": { @@ -111678,7 +111703,7 @@ } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L40" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L56" }, { "kind": "request", @@ -111688,7 +111713,7 @@ "body": { "kind": "no_body" }, - "description": "Get remote cluster information.\nGet all of the configured remote cluster information.\nThis API returns connection and endpoint information keyed by the configured remote cluster alias.", + "description": "Get remote cluster information.\n\nGet information about configured remote clusters.\nThe API returns connection and endpoint information keyed by the configured remote cluster alias.\n\n> info\n> This API returns information that reflects current state on the local cluster.\n> The `connected` field does not necessarily reflect whether a remote cluster is down or unavailable, only whether there is currently an open connection to it.\n> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.\n> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).", "inherits": { "type": { "name": "RequestBase", @@ -111701,7 +111726,7 @@ }, "path": [], "query": [], - "specLocation": "cluster/remote_info/ClusterRemoteInfoRequest.ts#L22-L37" + "specLocation": "cluster/remote_info/ClusterRemoteInfoRequest.ts#L22-L46" }, { "kind": "response", @@ -140843,7 +140868,7 @@ "body": { "kind": "no_body" }, - "description": "Resolve the cluster.\nResolve the specified index expressions to return information about each cluster, including the local cluster, if included.\nMultiple patterns and remote clusters are supported.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster in the index expression scope.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n**Advantages of using this endpoint before a cross-cluster search**\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.", + "description": "Resolve the cluster.\n\nResolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` endpoint is commonly used to test whether the \"local\" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", "inherits": { "type": { "name": "RequestBase", @@ -140856,7 +140881,7 @@ }, "path": [ { - "description": "Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.", + "description": "A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.", "name": "name", "required": true, "type": { @@ -140870,9 +140895,10 @@ ], "query": [ { - "description": "If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.", + "description": "If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.", "name": "allow_no_indices", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -140895,9 +140921,14 @@ } }, { - "description": "If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false.", + "deprecation": { + "description": "", + "version": "7.16.0" + }, + "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.", "name": "ignore_throttled", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -140907,9 +140938,10 @@ } }, { - "description": "If false, the request returns an error if it targets a missing or closed index. Defaults to false.", + "description": "If false, the request returns an error if it targets a missing or closed index.", "name": "ignore_unavailable", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -140919,7 +140951,7 @@ } } ], - "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L23-L95" + "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L23-L110" }, { "kind": "interface",