[ESQL] Improve `skip_unavailable` description in CCS doc #1919

smalyshev · 2025-06-25T22:17:18Z

Improve the description to match 9.1 GA semantics

github-actions · 2025-06-25T22:17:26Z

🔍 Preview links for changed docs:

explore-analyze/query-filter/languages/esql-cross-clusters.md

🔔 The preview site may take up to 3 minutes to finish building. These links will become live once it completes.

leemthompo

Few suggestions and questions, was also wondering if you could just bundle this into your other PR? #maybe? :)

leemthompo · 2025-06-26T09:36:18Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

@@ -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


Suggested change

stack: ga 9.1

stack: preview 9.0, ga 9.1

this isn't brand new and the docs now cover all 9.x versions, so the reader might be on 9.0 or 9.1 so we need to maintain lifecycle information

but if the entire page is marked preview 9.0, GA 9.1, you might not need this section-level tag at all?

Well, this is different thing, because what is described here is correct only for 9.1, it works differently in 9.0. The point is not that it's preview in 9.0, it just doesn't work the way this paragraph describes in 9.0.

OK thanks for clarifying :) Let me check on what the best way to handle this is then.

@smalyshev in this case you should use tabs to house the 9.0 and 9.1 differences:

::::{tab-set} :::{tab-item} 9.0 This is where the content for tab #1 goes. ::: :::{tab-item} 9.1 This is where the content for tab #2 goes. ::: ::::

Oh interesting. I'll try that.

leemthompo · 2025-06-26T09:36:36Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

+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:


Suggested change

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:

Remote clusters are configured with `skip_unavailable: true` by default. With this setting, the cluster will be marked as `skipped` or `partial` instead of causing query failures:

* `skipped` means the cluster was unavailable and no data was returned

* `partial` means some data was returned despite errors during the query

This means queries won't fail if:

* The remote cluster disconnects from the querying cluster (before or during query execution)

* The remote cluster lacks the requested index

* An error occurs during query processing on the remote cluster

attempt to improve readability

leemthompo · 2025-06-26T09:39:31Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

+* 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.


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

leemthompo · 2025-06-26T09:56:32Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

+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:


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.

Might be a candidate for an admonition

leemthompo · 2025-06-26T10:02:33Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

+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
+```


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

annotating the query might nice, clean way to explain it

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.

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

leemthompo

Few minor readability issues to clear up and I think this will be good to go. Thanks for iterating :)

explore-analyze/query-filter/languages/esql-cross-clusters.md

leemthompo · 2025-06-27T08:10:47Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

+* 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 will be used if the remote query was partially successful and some data may have been returned.


Suggested change

The `partial` status will be used if the remote query was partially successful and some data may have been returned.

The `partial` status means the remote query has errors, but some data may be returned.

This is not entirely accurate, partial can result from an error, but also from interruption like async stop, which is not an error but an explicit user action.

leemthompo · 2025-06-27T08:15:15Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

@@ -471,9 +471,36 @@ FROM my-index-000001,cluster*:my-index-*,cluster_three:-my-index-000001

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



Suggested change

Cross-cluster search behavior with unavailable clusters differs between versions.

just a word of intro for the tabs

just for a second set of eyes, @florent-leborgne let me know how you feel about this tab approach

👍 👍 Hopefully soon we will support metadata for tabs too but at least this is clear

It's not only unavailable clusters, at least for 9.1 it covers a lot more errors. It is linked to how skip_unavailable option behaves, but despite it's name, it controls more than just mere un-availablity now. That's why we need the whole 9.1 section to explain that :)

leemthompo · 2025-06-27T08:17:22Z

explore-analyze/query-filter/languages/esql-cross-clusters.md

@@ -471,9 +471,36 @@ FROM my-index-000001,cluster*:my-index-*,cluster_three:-my-index-000001

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


Suggested change

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

## Handling unavailable remote clusters [ccq-skip-unavailable-clusters]

I don't think the current heading is super clear, feel free to tweak my suggestion

As per above, it's not only unavailability. I am having hard time to find a precise word for it but basically those are the clusters that it's ok if they don't deliver perfect results or any results at all. Calling them "optional" seems to me a good approximation, but if you have better suggestions please tell.

Co-authored-by: Liam Thompson <[email protected]>

Improve skip_un description

31214cb

smalyshev requested review from a team as code owners June 25, 2025 22:17

smalyshev added documentation Improvements or additions to documentation v9.1.0 labels Jun 25, 2025

github-actions bot deployed to docs-preview June 25, 2025 22:17 View deployment

fix

1c75606

smalyshev requested review from florent-leborgne and quux00 June 25, 2025 23:03

github-actions bot deployed to docs-preview June 25, 2025 23:03 View deployment

leemthompo reviewed Jun 26, 2025

View reviewed changes

leemthompo changed the title ~~Improve skip_un description~~ [ESQL] Improve skip_unavailable description in CCS doc Jun 26, 2025

leemthompo mentioned this pull request Jun 26, 2025

Better description of skip-un funciton in 8.19 elastic/elasticsearch#130043

Merged

Use 9.0/9.1 tabs

3bcf536

github-actions bot had a problem deploying to docs-preview June 26, 2025 22:18 Failure

Ws

20aaf55

github-actions bot deployed to docs-preview June 26, 2025 22:19 View deployment

Merge branch 'main' into skip-un-91

61ccd82

github-actions bot deployed to docs-preview June 26, 2025 22:23 View deployment

ws

60c591f

github-actions bot deployed to docs-preview June 26, 2025 22:25 View deployment

fix syntax

e28d295

github-actions bot deployed to docs-preview June 26, 2025 22:40 View deployment

leemthompo reviewed Jun 27, 2025

View reviewed changes

Update explore-analyze/query-filter/languages/esql-cross-clusters.md

c0a615b

Co-authored-by: Liam Thompson <[email protected]>

github-actions bot deployed to docs-preview June 27, 2025 18:33 View deployment

		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:

-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:
+Remote clusters are configured with `skip_unavailable: true` by default. With this setting, the cluster will be marked as `skipped` or `partial` instead of causing query failures:
+* `skipped` means the cluster was unavailable and no data was returned
+* `partial` means some data was returned despite errors during the query
+This means queries won't fail if:
+* The remote cluster disconnects from the querying cluster (before or during query execution)
+* The remote cluster lacks the requested index
+* An error occurs during query processing on the remote cluster

		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:

-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>
+```
+. Single missing index on one cluster
+. Index pattern that matches nothing
+. All indices and index patterns missing across every cluster

	The `partial` status will be used if the remote query was partially successful and some data may have been returned.
	The `partial` status means the remote query has errors, but some data may be returned.

		@@ -471,9 +471,36 @@ FROM my-index-000001,cluster:my-index-,cluster_three:-my-index-000001

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


	Cross-cluster search behavior with unavailable clusters differs between versions.

	## Optional remote clusters [ccq-skip-unavailable-clusters]
	## Handling unavailable remote clusters [ccq-skip-unavailable-clusters]

[ESQL] Improve skip_unavailable description in CCS doc #1919

Are you sure you want to change the base?

[ESQL] Improve skip_unavailable description in CCS doc #1919

Conversation

smalyshev commented Jun 25, 2025

Uh oh!

github-actions bot commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smalyshev Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

leemthompo Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

[ESQL] Improve `skip_unavailable` description in CCS doc #1919

[ESQL] Improve `skip_unavailable` description in CCS doc #1919

github-actions bot commented Jun 25, 2025 •

edited

Loading

smalyshev Jun 26, 2025 •

edited

Loading

leemthompo Jun 26, 2025 •

edited

Loading

leemthompo Jun 26, 2025 •

edited

Loading

leemthompo Jun 26, 2025 •

edited

Loading

leemthompo Jun 27, 2025 •

edited

Loading