From 6a70587d4db471bc4980438a7b1788a1504f1b5a Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 24 Jun 2025 09:08:18 +0200 Subject: [PATCH 1/3] [DOCS][8.19] Promote ESQL search functions to GA in the docs - removed `preview = true` from java function annotations for full-text search functions - generated updates to asciidoc and kibana docs - 8.x equivalent of https://github.com/elastic/elasticsearch/pull/129786 --- docs/reference/esql/esql-limitations.asciidoc | 3 +-- docs/reference/esql/functions/kibana/definition/kql.json | 2 +- .../reference/esql/functions/kibana/definition/match.json | 2 +- .../esql/functions/kibana/definition/match_phrase.json | 2 +- docs/reference/esql/functions/kibana/definition/qstr.json | 2 +- docs/reference/esql/functions/layout/kql.asciidoc | 2 -- docs/reference/esql/functions/layout/match.asciidoc | 2 -- .../reference/esql/functions/layout/match_phrase.asciidoc | 2 -- docs/reference/esql/functions/layout/qstr.asciidoc | 2 -- docs/reference/esql/functions/operators.asciidoc | 2 +- docs/reference/esql/functions/search-functions.asciidoc | 8 +++++--- docs/reference/esql/functions/search.asciidoc | 2 -- .../xpack/esql/expression/function/fulltext/Kql.java | 1 - .../xpack/esql/expression/function/fulltext/Match.java | 1 - .../esql/expression/function/fulltext/MatchOperator.java | 1 - .../esql/expression/function/fulltext/MatchPhrase.java | 1 - .../esql/expression/function/fulltext/QueryString.java | 1 - 17 files changed, 11 insertions(+), 25 deletions(-) diff --git a/docs/reference/esql/esql-limitations.asciidoc b/docs/reference/esql/esql-limitations.asciidoc index ddf0bf63a7dbd..65aafe2d7a706 100644 --- a/docs/reference/esql/esql-limitations.asciidoc +++ b/docs/reference/esql/esql-limitations.asciidoc @@ -106,8 +106,7 @@ is currently experimental. [[esql-limitations-full-text-search]] === Full-text search -experimental:[] {esql}'s support for <> -is currently in Technical Preview. One limitation of full-text search is that +One limitation of <> is that it is necessary to use the search function, like <>, in a <> command directly after the <> source command, or close enough to it. Otherwise, the query will fail with a validation error. diff --git a/docs/reference/esql/functions/kibana/definition/kql.json b/docs/reference/esql/functions/kibana/definition/kql.json index 40ace20dea562..1cd1a1436d95d 100644 --- a/docs/reference/esql/functions/kibana/definition/kql.json +++ b/docs/reference/esql/functions/kibana/definition/kql.json @@ -32,6 +32,6 @@ "examples" : [ "FROM books \n| WHERE KQL(\"author: Faulkner\")\n| KEEP book_no, author \n| SORT book_no " ], - "preview" : true, + "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/esql/functions/kibana/definition/match.json b/docs/reference/esql/functions/kibana/definition/match.json index 439ac6d30111f..8a3062a6b0561 100644 --- a/docs/reference/esql/functions/kibana/definition/match.json +++ b/docs/reference/esql/functions/kibana/definition/match.json @@ -734,6 +734,6 @@ "FROM books \n| WHERE MATCH(author, \"Faulkner\")", "FROM books \n| WHERE MATCH(title, \"Hobbit Back Again\", {\"operator\": \"AND\"})\n| KEEP title;" ], - "preview" : true, + "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/esql/functions/kibana/definition/match_phrase.json b/docs/reference/esql/functions/kibana/definition/match_phrase.json index 3796d7e21ec4e..699ddaa46b988 100644 --- a/docs/reference/esql/functions/kibana/definition/match_phrase.json +++ b/docs/reference/esql/functions/kibana/definition/match_phrase.json @@ -58,6 +58,6 @@ "examples" : [ "FROM books\n| WHERE MATCH_PHRASE(author, \"William Faulkner\")" ], - "preview" : true, + "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/esql/functions/kibana/definition/qstr.json b/docs/reference/esql/functions/kibana/definition/qstr.json index 4ee25bb7e83c9..bf0824c6d52e1 100644 --- a/docs/reference/esql/functions/kibana/definition/qstr.json +++ b/docs/reference/esql/functions/kibana/definition/qstr.json @@ -47,6 +47,6 @@ "FROM books \n| WHERE QSTR(\"author: Faulkner\")", "FROM books \n| WHERE QSTR(\"title: Hobbjt~\", {\"fuzziness\": 2})" ], - "preview" : true, + "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/esql/functions/layout/kql.asciidoc b/docs/reference/esql/functions/layout/kql.asciidoc index 8cf2687b240c1..4f598527f4e27 100644 --- a/docs/reference/esql/functions/layout/kql.asciidoc +++ b/docs/reference/esql/functions/layout/kql.asciidoc @@ -4,8 +4,6 @@ [[esql-kql]] === `KQL` -preview::["Do not use on production environments. 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."] - *Syntax* [.text-center] diff --git a/docs/reference/esql/functions/layout/match.asciidoc b/docs/reference/esql/functions/layout/match.asciidoc index 7765cc707e390..e560b3965142b 100644 --- a/docs/reference/esql/functions/layout/match.asciidoc +++ b/docs/reference/esql/functions/layout/match.asciidoc @@ -4,8 +4,6 @@ [[esql-match]] === `MATCH` -preview::["Do not use on production environments. 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."] - *Syntax* [.text-center] diff --git a/docs/reference/esql/functions/layout/match_phrase.asciidoc b/docs/reference/esql/functions/layout/match_phrase.asciidoc index 9567e83a1e98b..07145db52ca53 100644 --- a/docs/reference/esql/functions/layout/match_phrase.asciidoc +++ b/docs/reference/esql/functions/layout/match_phrase.asciidoc @@ -4,8 +4,6 @@ [[esql-match_phrase]] === `MATCH_PHRASE` -preview::["Do not use on production environments. 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."] - *Syntax* [.text-center] diff --git a/docs/reference/esql/functions/layout/qstr.asciidoc b/docs/reference/esql/functions/layout/qstr.asciidoc index 6731962350b3b..15c8b509d8088 100644 --- a/docs/reference/esql/functions/layout/qstr.asciidoc +++ b/docs/reference/esql/functions/layout/qstr.asciidoc @@ -4,8 +4,6 @@ [[esql-qstr]] === `QSTR` -preview::["Do not use on production environments. 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."] - *Syntax* [.text-center] diff --git a/docs/reference/esql/functions/operators.asciidoc b/docs/reference/esql/functions/operators.asciidoc index a1a2226335e9b..7d531ccab758f 100644 --- a/docs/reference/esql/functions/operators.asciidoc +++ b/docs/reference/esql/functions/operators.asciidoc @@ -16,7 +16,7 @@ Boolean operators for comparing against one or multiple expressions. * <> * <> * <> -* experimental:[] <> +* <> // end::op_list[] include::binary.asciidoc[] diff --git a/docs/reference/esql/functions/search-functions.asciidoc b/docs/reference/esql/functions/search-functions.asciidoc index b8891bd8b9150..45757a6bb3947 100644 --- a/docs/reference/esql/functions/search-functions.asciidoc +++ b/docs/reference/esql/functions/search-functions.asciidoc @@ -16,11 +16,13 @@ See <> for infor {esql} supports these full-text search functions: // tag::search_list[] -* experimental:[] <> -* experimental:[] <> -* experimental:[] <> +* <> +* <> +* <> +* <> // end::search_list[] include::layout/kql.asciidoc[] include::layout/match.asciidoc[] +include::layout/match_phrase.asciidoc[] include::layout/qstr.asciidoc[] diff --git a/docs/reference/esql/functions/search.asciidoc b/docs/reference/esql/functions/search.asciidoc index 1be4dee58e234..eef3e68e42b4c 100644 --- a/docs/reference/esql/functions/search.asciidoc +++ b/docs/reference/esql/functions/search.asciidoc @@ -4,8 +4,6 @@ The only search operator is match (`:`). -preview::["Do not use on production environments. 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."] - The match operator performs a <> on the specified field. Returns true if the provided query matches the row. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Kql.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Kql.java index 12dd7a7a5e904..99d6333ce39cc 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Kql.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Kql.java @@ -35,7 +35,6 @@ public class Kql extends FullTextFunction { @FunctionInfo( returnType = "boolean", - preview = true, description = "Performs a KQL query. Returns true if the provided KQL query string matches the row.", examples = { @Example(file = "kql-function", tag = "kql-with-field") } ) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java index e6a6a730e9734..cf6ad74d9d2c9 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java @@ -133,7 +133,6 @@ public class Match extends FullTextFunction implements OptionalArgument, PostAna @FunctionInfo( returnType = "boolean", - preview = true, description = """ Use `MATCH` to perform a <> on the specified field. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java index 38b5022b34351..f0c65b4089be9 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java @@ -28,7 +28,6 @@ public class MatchOperator extends Match { @FunctionInfo( returnType = "boolean", operator = ":", - preview = true, description = """ Use the match operator (`:`) to perform a <> on the specified field. Using `:` is equivalent to using the `match` query in the Elasticsearch Query DSL. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java index 49d5d8ed2929f..d3f33e9d55550 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java @@ -90,7 +90,6 @@ public class MatchPhrase extends FullTextFunction implements OptionalArgument, P @FunctionInfo( returnType = "boolean", - preview = true, description = """ Use `MATCH_PHRASE` to perform a [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) on the specified field. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java index ec87103163661..40a8362de580a 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java @@ -108,7 +108,6 @@ public class QueryString extends FullTextFunction implements OptionalArgument { @FunctionInfo( returnType = "boolean", - preview = true, description = "Performs a <>. " + "Returns true if the provided query string matches the row.", examples = { From cdd969c0742a79440d54069217b8de79f8ea0253 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 24 Jun 2025 10:28:52 +0200 Subject: [PATCH 2/3] Fix match_phrase docs to use asciidoc because 8.x --- .../esql/functions/description/match_phrase.asciidoc | 2 +- .../esql/functions/kibana/definition/match_phrase.json | 2 +- docs/reference/esql/functions/kibana/docs/match_phrase.md | 4 ++-- .../xpack/esql/expression/function/fulltext/MatchPhrase.java | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/esql/functions/description/match_phrase.asciidoc b/docs/reference/esql/functions/description/match_phrase.asciidoc index 673ecdbfc9595..d6f137a9dbdc3 100644 --- a/docs/reference/esql/functions/description/match_phrase.asciidoc +++ b/docs/reference/esql/functions/description/match_phrase.asciidoc @@ -2,4 +2,4 @@ *Description* -Use `MATCH_PHRASE` to perform a [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) on the specified field. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL. MatchPhrase can be used on <> fields, as well as other field types like keyword, boolean, or date types. MatchPhrase is not supported for <> or numeric types. MatchPhrase can use <> to specify additional options for the match_phrase query. All [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) query parameters are supported. `MATCH_PHRASE` returns true if the provided query matches the row. +Use `MATCH_PHRASE` to perform a <> on the specified field. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL. MatchPhrase can be used on <> fields, as well as other field types like keyword, boolean, or date types. MatchPhrase is not supported for <> or numeric types. MatchPhrase can use <> to specify additional options for the match_phrase query. All <> query parameters are supported. `MATCH_PHRASE` returns true if the provided query matches the row. diff --git a/docs/reference/esql/functions/kibana/definition/match_phrase.json b/docs/reference/esql/functions/kibana/definition/match_phrase.json index 699ddaa46b988..18be37d3f2ff3 100644 --- a/docs/reference/esql/functions/kibana/definition/match_phrase.json +++ b/docs/reference/esql/functions/kibana/definition/match_phrase.json @@ -2,7 +2,7 @@ "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "eval", "name" : "match_phrase", - "description" : "Use `MATCH_PHRASE` to perform a [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) on the\nspecified field.\nUsing `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL.\n\nMatchPhrase can be used on <> fields, as well as other field types like keyword, boolean, or date types.\nMatchPhrase is not supported for <> or numeric types.\n\nMatchPhrase can use <> to specify additional options for the\nmatch_phrase query.\nAll [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) query parameters are supported.\n\n`MATCH_PHRASE` returns true if the provided query matches the row.", + "description" : "Use `MATCH_PHRASE` to perform a <> on the\nspecified field.\nUsing `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL.\n\nMatchPhrase can be used on <> fields, as well as other field types like keyword, boolean, or date types.\nMatchPhrase is not supported for <> or numeric types.\n\nMatchPhrase can use <> to specify additional options for the\nmatch_phrase query.\nAll <> query parameters are supported.\n\n`MATCH_PHRASE` returns true if the provided query matches the row.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/docs/match_phrase.md b/docs/reference/esql/functions/kibana/docs/match_phrase.md index 7d7c05cfb1ae0..de2e2d3d08772 100644 --- a/docs/reference/esql/functions/kibana/docs/match_phrase.md +++ b/docs/reference/esql/functions/kibana/docs/match_phrase.md @@ -3,7 +3,7 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ --> ### MATCH_PHRASE -Use `MATCH_PHRASE` to perform a [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) on the +Use `MATCH_PHRASE` to perform a <> on the specified field. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL. @@ -12,7 +12,7 @@ MatchPhrase is not supported for <> or numeric typ MatchPhrase can use <> to specify additional options for the match_phrase query. -All [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) query parameters are supported. +All <> query parameters are supported. `MATCH_PHRASE` returns true if the provided query matches the row. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java index d3f33e9d55550..686b222fcc436 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java @@ -91,7 +91,7 @@ public class MatchPhrase extends FullTextFunction implements OptionalArgument, P @FunctionInfo( returnType = "boolean", description = """ - Use `MATCH_PHRASE` to perform a [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) on the + Use `MATCH_PHRASE` to perform a <> on the specified field. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL. @@ -100,7 +100,7 @@ public class MatchPhrase extends FullTextFunction implements OptionalArgument, P MatchPhrase can use <> to specify additional options for the match_phrase query. - All [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) query parameters are supported. + All <> query parameters are supported. `MATCH_PHRASE` returns true if the provided query matches the row.""", examples = { @Example(file = "match-phrase-function", tag = "match-phrase-with-field") } From 18b039ed4a078e2dbdbf2c7e3be135b4e5c7a5c7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 24 Jun 2025 10:29:08 +0200 Subject: [PATCH 3/3] Update match operator kibana --- .../esql/functions/kibana/definition/match_operator.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/esql/functions/kibana/definition/match_operator.json b/docs/reference/esql/functions/kibana/definition/match_operator.json index 7153c50c8c18a..3250812b3d496 100644 --- a/docs/reference/esql/functions/kibana/definition/match_operator.json +++ b/docs/reference/esql/functions/kibana/definition/match_operator.json @@ -531,6 +531,6 @@ "examples" : [ "FROM books \n| WHERE MATCH(author, \"Faulkner\")" ], - "preview" : true, + "preview" : false, "snapshot_only" : false }