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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Jul 1, 2025
Merged

[ESQL] Improve skip_unavailable description in CCS doc #1919

Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
31214cb
Improve skip_un description
smalyshev Jun 25, 2025
1c75606
fix
smalyshev Jun 25, 2025
3bcf536
Use 9.0/9.1 tabs
smalyshev Jun 26, 2025
20aaf55
Ws
smalyshev Jun 26, 2025
61ccd82
Merge branch 'main' into skip-un-91
smalyshev Jun 26, 2025
60c591f
ws
smalyshev Jun 26, 2025
e28d295
fix syntax
smalyshev Jun 26, 2025
c0a615b
Update explore-analyze/query-filter/languages/esql-cross-clusters.md
smalyshev Jun 27, 2025
b0a78f3
Update explore-analyze/query-filter/languages/esql-cross-clusters.md
smalyshev Jul 1, 2025
14eabb9
refine skip-un section
smalyshev Jul 1, 2025
9d1da01
Merge branch 'main' into skip-un-91
smalyshev Jul 1, 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
23 changes: 20 additions & 3 deletions explore-analyze/query-filter/languages/esql-cross-clusters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -470,10 +470,27 @@ FROM my-index-000001,cluster*:my-index-*,cluster_three:-my-index-000001


## Optional remote clusters [ccq-skip-unavailable-clusters]
```{applies_to}
stack: ga 9.1
```

If the remote cluster is configured with `skip_unavailable: true` (the default setting), the cluster would be set
to `skipped` or `partial` status but the query will not fail, if:

* The remote cluster is disconnected from the querying cluster, either before or during the query.
* The remote cluster does not have the requested index.
* An error happened while processing the query on the remote cluster.

The `partial` status will be used if the remote query was partially successful and some data was returned.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
The `partial` status will be used if the remote query was partially successful and some data was returned.

I suggested explaining skipped and partial in the opening section, so can remove this if accept that :)


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.
This however does not apply to the situation when the remote cluster is missing an index and this is the only index in the query,
or all the indices in the query are missing. For example, the following queries will fail:
Copy link
Contributor

@leemthompo leemthompo Jun 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

This first sentence is a little hard to read, I wonder if we can boil it town to a simpler message:

Queries will still fail when skip_unavailable: true, if none of the specified indices exist.

Copy link
Contributor

Choose a reason for hiding this comment

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

Might be a candidate for an admonition


```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 •
edited
Loading

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! :)


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

Expand Down
Loading