Skip to content

Refine ESQL docs handling of applies_to #125835

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 14 commits into from
Mar 28, 2025
Merged

Refine ESQL docs handling of applies_to #125835

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
1c3ddc7
Remove all warnings from DocsV3Support
craigtaverner Mar 28, 2025
338ad98
Split applies_to from preview warning
craigtaverner Mar 28, 2025
0613bfd
Update examples test to use real examples rendering
craigtaverner Mar 28, 2025
895431f
Merge branch 'main' into esql_docs_applies_to
craigtaverner Mar 28, 2025
6aa5510
Fix EsqlNodeSubclassTests failures
craigtaverner Mar 28, 2025
bc6da1a
Merge branch 'esql_docs_applies_to' of github.com:craigtaverner/elast…
craigtaverner Mar 28, 2025
a979b81
Update x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/…
craigtaverner Mar 28, 2025
7cad5a7
Merge branch 'main' into esql_docs_applies_to
craigtaverner Mar 28, 2025
e283662
Refined applies_to, adding serverless and removing some version info
craigtaverner Mar 28, 2025
8983eaf
Merge branch 'esql_docs_applies_to' of github.com:craigtaverner/elast…
craigtaverner Mar 28, 2025
f682702
Merge remote-tracking branch 'origin/main' into esql_docs_applies_to
craigtaverner Mar 28, 2025
8899713
Remove applies_to from LOOKUP JOIN and MV_EXPAND
craigtaverner Mar 28, 2025
45032bb
Use Elastic Stack instead of Stateful, and remove version from QSTR
craigtaverner Mar 28, 2025
90609b2
Merge branch 'main' into esql_docs_applies_to
craigtaverner Mar 28, 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
1 change: 1 addition & 0 deletions docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions docs/reference/query-languages/esql/_snippets/functions/layout/kql.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 4 additions & 3 deletions docs/reference/query-languages/esql/_snippets/functions/layout/match.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 4 additions & 3 deletions docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions docs/reference/query-languages/esql/_snippets/functions/layout/term.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion ...e/query-languages/esql/_snippets/functions/layout/to_aggregate_metric_double.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions docs/reference/query-languages/esql/_snippets/functions/layout/to_lower.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions docs/reference/query-languages/esql/_snippets/functions/layout/to_upper.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions docs/reference/query-languages/esql/_snippets/functions/layout/values.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 0 additions & 8 deletions docs/reference/query-languages/esql/esql-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -666,10 +666,6 @@ FROM employees
## `LOOKUP JOIN` [esql-lookup-join]

::::{warning}
```{applies_to}
stack: preview 9.0, coming 9.1
serverless: preview
Comment on lines -670 to -671
Copy link
Contributor

Choose a reason for hiding this comment

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

I agree that this maybe shouldn't be in the tech preview warning, but I don't know if these tags should be removed altogether. Maybe @leemthompo can suggest a better position?

```
This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
::::

Expand Down Expand Up @@ -753,10 +749,6 @@ FROM Left
## `MV_EXPAND` [esql-mv_expand]

::::{warning}
```{applies_to}
stack: preview 9.0, coming 9.1
Copy link
Contributor

Choose a reason for hiding this comment

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

Oh, good catch. This is in preview way longer than 9.0, and it's not coming to 9.1 as far as I know.

MV_EXPAND was already in place in 8.11, when ESQL went into tech preview - at least there's an 8.11 PR that mentions it: #100598

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 added these originally as examples to discuss with people, but failed to remove them. Based on current discussions, we should remove any version statements, even if the feature is available in serverless, as there is no guarrantee if it will come out in any particular stateful version.

serverless: preview
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this tag should still apply (but I agree this shouldn't be placed here).

```
This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
::::

Expand Down
2 changes: 1 addition & 1 deletion ...erence/query-languages/esql/kibana/docs/functions/to_aggregate_metric_double.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions ...sql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesTo.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,6 @@
String version() default "";

String description() default "";

boolean serverless() default true;
}
26 changes: 18 additions & 8 deletions ...ain/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesToLifecycle.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,22 @@
package org.elasticsearch.xpack.esql.expression.function;

public enum FunctionAppliesToLifecycle {
PREVIEW,
BETA,
DEVELOPMENT,
DEPRECATED,
COMING,
DISCONTINUED,
UNAVAILABLE,
GA
PREVIEW(true),
BETA(false),
DEVELOPMENT(false),
DEPRECATED(true),
COMING(true),
DISCONTINUED(false),
UNAVAILABLE(false),
GA(true);

private final boolean serverless;

FunctionAppliesToLifecycle(boolean serverless) {
this.serverless = serverless;
}

public FunctionAppliesToLifecycle serverlessLifecycle() {
return serverless ? GA : this;
}
}
5 changes: 1 addition & 4 deletions ...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.core.type.DataType;
import org.elasticsearch.xpack.esql.expression.function.Example;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
import org.elasticsearch.xpack.esql.expression.function.FunctionType;
import org.elasticsearch.xpack.esql.expression.function.Param;
Expand Down Expand Up @@ -86,8 +84,7 @@ public class Values extends AggregateFunction implements ToAggregator {
a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md).
::::""",
type = FunctionType.AGGREGATE,
examples = @Example(file = "string", tag = "values-grouped"),
appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW) }
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This file has both the old and new approaches to tech-preview, so I removed the new one until we make a final decision on how to deal with tech-preview warnings in general. They are all over the place, not just here, so this function was just an experiment to see what it looked like.

examples = @Example(file = "string", tag = "values-grouped")
)
public Values(
Source source,
Expand Down
3 changes: 1 addition & 2 deletions ...n/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,8 +165,7 @@ public class Match extends FullTextFunction implements OptionalArgument, PostAna
appliesTo = {
@FunctionAppliesTo(
lifeCycle = FunctionAppliesToLifecycle.COMING,
version = "9.1.0",
description = "Support for optional named parameters is only available from 9.1.0"
description = "Support for optional named parameters is only available in serverless, or in a future {{es}} release"
) }
)
public Match(
Expand Down
3 changes: 1 addition & 2 deletions .../src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,8 +122,7 @@ public class QueryString extends FullTextFunction implements OptionalArgument {
appliesTo = {
@FunctionAppliesTo(
lifeCycle = FunctionAppliesToLifecycle.COMING,
version = "9.1.0",
description = "Support for optional named parameters is only available from 9.1.0"
description = "Support for optional named parameters is only available in serverless, or in a future {{es}} release"
) }
)
public QueryString(
Expand Down
2 changes: 1 addition & 1 deletion .../elasticsearch/xpack/esql/expression/function/scalar/convert/ToAggregateMetricDouble.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ public class ToAggregateMetricDouble extends AbstractConvertFunction {
examples = {
@Example(file = "convert", tag = "toAggregateMetricDouble"),
@Example(description = "The expression also accepts multi-values", file = "convert", tag = "toAggregateMetricDoubleMv") },
appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.COMING, version = "9.1") }
appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.COMING) }
)
public ToAggregateMetricDouble(
Source source,
Expand Down
Loading
Loading