Skip to content

[ESQL] Improve skip_unavailable description in CCS doc #1919

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.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Jul 1, 2025
29 changes: 28 additions & 1 deletion explore-analyze/query-filter/languages/esql-cross-clusters.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,11 +469,38 @@ FROM my-index-000001,cluster*:my-index-*,cluster_three:-my-index-000001
```


## Optional remote clusters [ccq-skip-unavailable-clusters]
## Skipping problematic remote clusters [ccq-skip-unavailable-clusters]

{{ccs-cap}} for {{esql}} behavior when there are problems connecting to or running query on remote clusters differs between versions.

::::{tab-set}

:::{tab-item} 9.1
Remote clusters are configured with the `skip_unavailable: true` setting by default. With this setting, clusters are marked as `skipped` or `partial` rather than causing queries to fail in the following scenarios:

* The remote cluster is disconnected from the querying cluster, either before or during the query execution.
* The remote cluster does not have the requested index, or it is not accessible due to security settings.
* An error happened while processing the query on the remote cluster.

The `partial` status means the remote query either has errors or was interrupted by an explicit user action, but some data may be returned.

Queries will still fail when `skip_unavailable` is set `true`, if none of the specified indices exist. For example, the
following queries will fail:

```esql
FROM cluster_one:missing-index | LIMIT 10
FROM cluster_one:missing-index* | LIMIT 10
FROM cluster_one:missing-index*,cluster_two:missing-index | LIMIT 10
```
Comment on lines +491 to +494
Copy link
Contributor

@leemthompo leemthompo Jun 26, 2025

Choose a reason for hiding this comment

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

Suggested change
FROM cluster_one:missing-index | LIMIT 10
FROM cluster_one:missing-index* | LIMIT 10
FROM cluster_one:missing-index*,cluster_two:missing-index | LIMIT 10
```
FROM cluster_one:missing-index <1>
FROM cluster_one:missing-index* <2>
FROM cluster_one:missing-index*,cluster_two:missing-index <3>
```
1. Single missing index on one cluster
2. Index pattern that matches nothing
3. All indices and index patterns missing across every cluster

Copy link
Contributor

Choose a reason for hiding this comment

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

annotating the query might nice, clean way to explain it

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think the previous text already explains it, do we really need to supply that much detail? It's just different examples of how to write missing indices, after all.

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think it hurts to be super clear, and personally I really like annotated examples —specially for non-experts.

But I leave this totally up to your discretion! :)

:::

:::{tab-item} 9.0
If a remote cluster disconnects from the querying cluster, {{ccs}} for {{esql}} will set it to `skipped`
and continue the query with other clusters, unless the remote cluster's `skip_unavailable` setting is set to `false`,
in which case the query will fail.
:::

::::

## Query across clusters during an upgrade [ccq-during-upgrade]

Expand Down
Loading