From 1b4a458cde01fce89449c64a4fa9f8e094c48999 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 23 Jul 2025 17:45:21 +0200 Subject: [PATCH 1/8] Add applies to to ScalB function in https://github.com/elastic/elasticsearch/pull/127696 --- .../esql/_snippets/functions/layout/scalb.md | 3 +++ .../expression/function/scalar/math/Scalb.java | 17 ++++++++++++----- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/scalb.md b/docs/reference/query-languages/esql/_snippets/functions/layout/scalb.md index 19ff3246f4ca1..bae02950efa6c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/scalb.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/scalb.md @@ -1,6 +1,9 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. ## `SCALB` [esql-scalb] +```{applies_to} +stack: ga 9.1.0 +``` **Syntax** diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Scalb.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Scalb.java index b23b2323d0498..ff07e1c71a4c6 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Scalb.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Scalb.java @@ -20,6 +20,8 @@ import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.core.util.NumericUtils; 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.Param; import org.elasticsearch.xpack.esql.expression.function.scalar.EsqlScalarFunction; @@ -40,11 +42,16 @@ public class Scalb extends EsqlScalarFunction { private final Expression d; private final Expression scaleFactor; - @FunctionInfo(returnType = "double", description = """ - Returns the result of `d * 2 ^ scaleFactor`, - Similar to Java's `scalb` function. Result is rounded as if - performed by a single correctly rounded floating-point multiply - to a member of the double value set.""", examples = @Example(file = "floats", tag = "scalb")) + @FunctionInfo( + returnType = "double", + description = """ + Returns the result of `d * 2 ^ scaleFactor`, + Similar to Java's `scalb` function. Result is rounded as if + performed by a single correctly rounded floating-point multiply + to a member of the double value set.""", + examples = @Example(file = "floats", tag = "scalb"), + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1.0") } + ) public Scalb( Source source, From 4adffb98e336d0d5517c38b6446b7494670b9ed3 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 23 Jul 2025 17:46:47 +0200 Subject: [PATCH 2/8] Add applies_to to categorize, follow up to https://github.com/elastic/elasticsearch/pull/129398/ --- .../_snippets/functions/functionNamedParams/categorize.md | 4 ++-- .../esql/_snippets/functions/layout/categorize.md | 3 +++ .../esql/expression/function/grouping/Categorize.java | 7 ++++++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md index acd2064002b44..00f6558c1cb5d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md @@ -3,10 +3,10 @@ **Supported function named parameters** `output_format` -: (boolean) The output format of the categories. Defaults to regex. +: (keyword) The output format of the categories. Defaults to regex. `similarity_threshold` -: (boolean) The minimum percentage of token weight that must match for text to be added to the category bucket. Must be between 1 and 100. The larger the value the narrower the categories. Larger values will increase memory usage and create narrower categories. Defaults to 70. +: (integer) The minimum percentage of token weight that must match for text to be added to the category bucket. Must be between 1 and 100. The larger the value the narrower the categories. Larger values will increase memory usage and create narrower categories. Defaults to 70. `analyzer` : (keyword) Analyzer used to convert the field into tokens for text categorization. diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md index 2e331187665f4..4d39f03ae394c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md @@ -1,6 +1,9 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. ## `CATEGORIZE` [esql-categorize] +```{applies_to} +stack: preview 9.0, ga 9.1 +``` **Syntax** diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java index 75918091f9ecd..5bad716cc9e87 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java @@ -24,6 +24,8 @@ 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.MapParam; @@ -93,7 +95,10 @@ public class Categorize extends GroupingFunction.NonEvaluatableGroupingFunction tag = "docsCategorize", description = "This example categorizes server logs messages into categories and aggregates their counts. " ) }, - type = FunctionType.GROUPING + type = FunctionType.GROUPING, + appliesTo = { + @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.0"), + @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1") } ) public Categorize( Source source, From 7c3dc70625eac9f1edffbb5dd77eb33399b995cb Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 23 Jul 2025 18:18:15 +0200 Subject: [PATCH 3/8] Add version info, following https://github.com/elastic/elasticsearch/pull/127629 --- .../esql/_snippets/functions/layout/sample.md | 3 +++ .../xpack/esql/expression/function/aggregate/Sample.java | 6 +++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md b/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md index 05d8cef498116..365202524de12 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md @@ -1,6 +1,9 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. ## `SAMPLE` [esql-sample] +```{applies_to} +stack: preview 9.1.0 +``` **Syntax** diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java index 781f9ad67c05c..2dedaff5ac0b2 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java @@ -23,6 +23,8 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo; import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.core.type.DataType; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.Example; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.FunctionType; @@ -59,7 +61,9 @@ public class Sample extends AggregateFunction implements ToAggregator { "version" }, description = "Collects sample values for a field.", type = FunctionType.AGGREGATE, - examples = @Example(file = "stats_sample", tag = "doc") + examples = @Example(file = "stats_sample", tag = "doc"), + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.1.0") } + ) public Sample( Source source, From 49783f11f760808746dcde69463e4fd51d1b54eb Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 24 Jul 2025 08:51:26 +0200 Subject: [PATCH 4/8] SAMPLE is new + GA in 9.1 https://github.com/elastic/elasticsearch/pull/127629 --- .../query-languages/esql/_snippets/functions/layout/sample.md | 2 +- .../xpack/esql/expression/function/aggregate/Sample.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md b/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md index 365202524de12..9fd348abe8cd9 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/sample.md @@ -2,7 +2,7 @@ ## `SAMPLE` [esql-sample] ```{applies_to} -stack: preview 9.1.0 +stack: ga 9.1.0 ``` **Syntax** diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java index 2dedaff5ac0b2..c68f8b4c46689 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java @@ -62,7 +62,7 @@ public class Sample extends AggregateFunction implements ToAggregator { description = "Collects sample values for a field.", type = FunctionType.AGGREGATE, examples = @Example(file = "stats_sample", tag = "doc"), - appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.1.0") } + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1.0") } ) public Sample( From c7e87d4418ab5976f84f2b4984e1355a18a32106 Mon Sep 17 00:00:00 2001 From: elasticsearchmachine Date: Thu, 24 Jul 2025 07:46:58 +0000 Subject: [PATCH 5/8] [CI] Auto commit changes from spotless --- .../xpack/esql/expression/function/aggregate/Sample.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java index c68f8b4c46689..030b4c08f8c15 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sample.java @@ -23,9 +23,9 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo; 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.Example; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.FunctionType; import org.elasticsearch.xpack.esql.expression.function.Param; From 310bf8697ec18f9d832e716b42185532b378f7ae Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 24 Jul 2025 11:49:15 +0200 Subject: [PATCH 6/8] add applies to for 9.2 option --- .../esql/_snippets/functions/functionNamedParams/categorize.md | 2 +- .../xpack/esql/expression/function/grouping/Categorize.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md index 00f6558c1cb5d..ddad7f21a757e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md @@ -3,7 +3,7 @@ **Supported function named parameters** `output_format` -: (keyword) The output format of the categories. Defaults to regex. +: (keyword) The output format of the categories. Defaults to regex. {applies_to}`stack: ga 9.2`} `similarity_threshold` : (integer) The minimum percentage of token weight that must match for text to be added to the category bucket. Must be between 1 and 100. The larger the value the narrower the categories. Larger values will increase memory usage and create narrower categories. Defaults to 70. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java index 5bad716cc9e87..4875530be123a 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java @@ -117,7 +117,7 @@ public Categorize( name = OUTPUT_FORMAT, type = "keyword", valueHint = { "regex", "tokens" }, - description = "The output format of the categories. Defaults to regex." + description = "The output format of the categories. Defaults to regex. {applies_to}`stack: ga 9.2`}" ), @MapParam.MapParamEntry( name = SIMILARITY_THRESHOLD, From a36cd8fc73da6c4681a25486dc8d3e841d6afac7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 24 Jul 2025 12:32:03 +0200 Subject: [PATCH 7/8] fix it --- .../_snippets/functions/functionNamedParams/categorize.md | 2 +- .../esql/_snippets/functions/parameters/categorize.md | 2 +- .../xpack/esql/expression/function/grouping/Categorize.java | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md index ddad7f21a757e..00f6558c1cb5d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/categorize.md @@ -3,7 +3,7 @@ **Supported function named parameters** `output_format` -: (keyword) The output format of the categories. Defaults to regex. {applies_to}`stack: ga 9.2`} +: (keyword) The output format of the categories. Defaults to regex. `similarity_threshold` : (integer) The minimum percentage of token weight that must match for text to be added to the category bucket. Must be between 1 and 100. The larger the value the narrower the categories. Larger values will increase memory usage and create narrower categories. Defaults to 70. diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/categorize.md index c013b67375a3d..77acd0393d0c7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/categorize.md @@ -6,5 +6,5 @@ : Expression to categorize `options` -: (Optional) Categorize additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). +: (Optional) Categorize additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). {applies_to}`stack: ga 9.2`} diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java index 4875530be123a..b41d356580b71 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java @@ -105,7 +105,7 @@ public Categorize( @Param(name = "field", type = { "text", "keyword" }, description = "Expression to categorize") Expression field, @MapParam( name = "options", - description = "(Optional) Categorize additional options as <>.", + description = "(Optional) Categorize additional options as <>. {applies_to}`stack: ga 9.2`}", params = { @MapParam.MapParamEntry( name = ANALYZER, @@ -117,7 +117,7 @@ public Categorize( name = OUTPUT_FORMAT, type = "keyword", valueHint = { "regex", "tokens" }, - description = "The output format of the categories. Defaults to regex. {applies_to}`stack: ga 9.2`}" + description = "The output format of the categories. Defaults to regex." ), @MapParam.MapParamEntry( name = SIMILARITY_THRESHOLD, From f1ca06e206cc13735ef1e1f21b251e26cbf46202 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 24 Jul 2025 15:06:26 +0200 Subject: [PATCH 8/8] fix checkstyle violations --- .../xpack/esql/expression/function/grouping/Categorize.java | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java index b41d356580b71..b9785624ff512 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java @@ -105,7 +105,9 @@ public Categorize( @Param(name = "field", type = { "text", "keyword" }, description = "Expression to categorize") Expression field, @MapParam( name = "options", - description = "(Optional) Categorize additional options as <>. {applies_to}`stack: ga 9.2`}", + description = "(Optional) Categorize additional options as " + + "<>. " + + "{applies_to}`stack: ga 9.2`}", params = { @MapParam.MapParamEntry( name = ANALYZER,