From 58c1c70bc8ca2d3e643b3cbd2748d1ba9f58abd2 Mon Sep 17 00:00:00 2001 From: carlosdelest Date: Wed, 18 Dec 2024 14:20:33 +0100 Subject: [PATCH 1/4] WIP - initial rewording --- docs/reference/esql/esql-limitations.asciidoc | 11 ++++++++++- .../esql/functions/search-functions.asciidoc | 4 +++- .../esql/processing-commands/where.asciidoc | 6 +++++- .../esql/expression/function/fulltext/Match.java | 12 +++++++++--- 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/reference/esql/esql-limitations.asciidoc b/docs/reference/esql/esql-limitations.asciidoc index c2849e4889f98..962fcef4bc077 100644 --- a/docs/reference/esql/esql-limitations.asciidoc +++ b/docs/reference/esql/esql-limitations.asciidoc @@ -112,7 +112,7 @@ it is necessary to use the search function, like <>, in a <> source command, or close enough to it. Otherwise, the query will fail with a validation error. Another limitation is that any <> command containing a full-text search function -cannot also use disjunctions (`OR`). +cannot also use disjunctions (`OR`) unless all functions used in the OR clauses are full-text functions themselves. For example, this query is valid: @@ -139,6 +139,15 @@ FROM books | WHERE MATCH(author, "Faulkner") OR author LIKE "Hemingway" ---- +but this one will succeed, as it uses full text functions on both OR clauses: + +[source,esql] +---- +FROM books +| WHERE MATCH(author, "Faulkner") OR QSTR("author: Hemingway") +---- + + Note that, because of <>, any queries on `text` fields that do not explicitly use the full-text functions, <> or <>, will behave as if the fields are actually `keyword` fields: diff --git a/docs/reference/esql/functions/search-functions.asciidoc b/docs/reference/esql/functions/search-functions.asciidoc index 238813c382c8c..a47db8f0f8c91 100644 --- a/docs/reference/esql/functions/search-functions.asciidoc +++ b/docs/reference/esql/functions/search-functions.asciidoc @@ -6,11 +6,13 @@ ++++ Full text functions are used to search for text in fields. -<> is used to analyze the query before it is searched. +<> is used to analyze the query before it is searched. Full text functions can be used to match <>. A multivalued field that contains a value that matches a full text query is considered to match the query. +Full text functions are more performant for text search use cases than using pattern matching or regular expressions with `LIKE` or `RLIKE`. + See <> for information on the limitations of full text search. {esql} supports these full-text search functions: diff --git a/docs/reference/esql/processing-commands/where.asciidoc b/docs/reference/esql/processing-commands/where.asciidoc index 1d6fc1e90d595..1674693688660 100644 --- a/docs/reference/esql/processing-commands/where.asciidoc +++ b/docs/reference/esql/processing-commands/where.asciidoc @@ -7,7 +7,7 @@ the input table for which the provided condition evaluates to `true`. [TIP] ==== -In case of value exclusions, fields with `null` values will be excluded from search results. +In case of value exclusions, fields with `null` values will be excluded from search results. In this context a `null` means either there is an explicit `null` value in the document or there is no value at all. For example: `WHERE field != "value"` will be interpreted as `WHERE field != "value" AND field IS NOT NULL`. ==== @@ -58,6 +58,10 @@ For a complete list of all functions, refer to <>. include::../functions/predicates.asciidoc[tag=body] +For matching text, you can use <> like `MATCH`. + +include::../functions/match.asciidoc[tag=body] + include::../functions/like.asciidoc[tag=body] include::../functions/rlike.asciidoc[tag=body] 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 0b2268fe1b022..58a71ed24640a 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 @@ -96,9 +96,15 @@ public class Match extends FullTextFunction implements Validatable { @FunctionInfo( returnType = "boolean", preview = true, - description = "Performs a <> on the specified field. " - + "Returns true if the provided query matches the row.", - examples = { @Example(file = "match-function", tag = "match-with-field") } + description = """ + Use `MATCH` to perform a <> on the specified field. + Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. + + Match can be used on text fields, as well as other field types like boolean, dates, and numeric types. + + For a simplified syntax, you can use the <> `:` operator instead of `MATCH`. + `MATCH` returns true if the provided query matches the row. + """, examples = { @Example(file = "match-function", tag = "match-with-field") } ) public Match( Source source, From 7279a502c3c121647036af2cc5e60771acfc41a1 Mon Sep 17 00:00:00 2001 From: carlosdelest Date: Wed, 18 Dec 2024 17:21:22 +0100 Subject: [PATCH 2/4] Regenerate docs, minor adjustments --- .../esql/functions/description/match.asciidoc | 2 +- .../esql/functions/kibana/definition/match.json | 2 +- .../esql/functions/kibana/docs/match.md | 9 ++++++++- .../esql/processing-commands/where.asciidoc | 17 +++++++++++++++-- .../expression/function/fulltext/Match.java | 5 +++-- 5 files changed, 28 insertions(+), 7 deletions(-) diff --git a/docs/reference/esql/functions/description/match.asciidoc b/docs/reference/esql/functions/description/match.asciidoc index 25f0571878d47..931fd5eb2f94a 100644 --- a/docs/reference/esql/functions/description/match.asciidoc +++ b/docs/reference/esql/functions/description/match.asciidoc @@ -2,4 +2,4 @@ *Description* -Performs a <> on the specified field. Returns true if the provided query matches the row. +Use `MATCH` to perform a <> on the specified field. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. Match can be used on text fields, as well as other field types like boolean, dates, and numeric types. For a simplified syntax, you can use the <> `:` operator instead of `MATCH`. `MATCH` returns true if the provided query matches the row. diff --git a/docs/reference/esql/functions/kibana/definition/match.json b/docs/reference/esql/functions/kibana/definition/match.json index 7f2a8239cc0d0..d61534da81a6d 100644 --- a/docs/reference/esql/functions/kibana/definition/match.json +++ b/docs/reference/esql/functions/kibana/definition/match.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", - "description" : "Performs a <> on the specified field. Returns true if the provided query matches the row.", + "description" : "Use `MATCH` to perform a <> on the specified field.\nUsing `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL.\n\nMatch can be used on text fields, as well as other field types like boolean, dates, and numeric types.\n\nFor a simplified syntax, you can use the <> `:` operator instead of `MATCH`.\n\n`MATCH` returns true if the provided query matches the row.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/docs/match.md b/docs/reference/esql/functions/kibana/docs/match.md index adf6de91c90f1..72258a1682936 100644 --- a/docs/reference/esql/functions/kibana/docs/match.md +++ b/docs/reference/esql/functions/kibana/docs/match.md @@ -3,7 +3,14 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ --> ### MATCH -Performs a <> on the specified field. Returns true if the provided query matches the row. +Use `MATCH` to perform a <> on the specified field. +Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. + +Match can be used on text fields, as well as other field types like boolean, dates, and numeric types. + +For a simplified syntax, you can use the <> `:` operator instead of `MATCH`. + +`MATCH` returns true if the provided query matches the row. ``` FROM books diff --git a/docs/reference/esql/processing-commands/where.asciidoc b/docs/reference/esql/processing-commands/where.asciidoc index 1674693688660..aaf503802848e 100644 --- a/docs/reference/esql/processing-commands/where.asciidoc +++ b/docs/reference/esql/processing-commands/where.asciidoc @@ -58,9 +58,22 @@ For a complete list of all functions, refer to <>. include::../functions/predicates.asciidoc[tag=body] -For matching text, you can use <> like `MATCH`. +For matching text, you can use <> like `MATCH`. -include::../functions/match.asciidoc[tag=body] +Use <> to perform a <> on a specified field. + +Match can be used on text fields, as well as other field types like boolean, dates, and numeric types. + +[source.merge.styled,esql] +---- +include::{esql-specs}/match-function.csv-spec[tag=match-with-field] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/match-function.csv-spec[tag=match-with-field-result] +|=== + +For a simplified syntax, you can use the <> `:` instead of `MATCH`. include::../functions/like.asciidoc[tag=body] 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 58a71ed24640a..22a3fe26fb9ca 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 @@ -103,8 +103,9 @@ public class Match extends FullTextFunction implements Validatable { Match can be used on text fields, as well as other field types like boolean, dates, and numeric types. For a simplified syntax, you can use the <> `:` operator instead of `MATCH`. - `MATCH` returns true if the provided query matches the row. - """, examples = { @Example(file = "match-function", tag = "match-with-field") } + + `MATCH` returns true if the provided query matches the row.""", + examples = { @Example(file = "match-function", tag = "match-with-field") } ) public Match( Source source, From 69fee785d276c1e4a25db66822a496987b3a0384 Mon Sep 17 00:00:00 2001 From: carlosdelest Date: Thu, 19 Dec 2024 08:38:51 +0100 Subject: [PATCH 3/4] Code review suggestions --- docs/reference/esql/functions/search-functions.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/esql/functions/search-functions.asciidoc b/docs/reference/esql/functions/search-functions.asciidoc index a47db8f0f8c91..bfdd288542782 100644 --- a/docs/reference/esql/functions/search-functions.asciidoc +++ b/docs/reference/esql/functions/search-functions.asciidoc @@ -11,7 +11,7 @@ Full text functions are used to search for text in fields. Full text functions can be used to match <>. A multivalued field that contains a value that matches a full text query is considered to match the query. -Full text functions are more performant for text search use cases than using pattern matching or regular expressions with `LIKE` or `RLIKE`. +Full text functions are significantly more performant for text search use cases on large data sets than using pattern matching or regular expressions with `LIKE` or `RLIKE` See <> for information on the limitations of full text search. From 6d2f1e0767cfdfb48dbc97317388d9fc5c92437d Mon Sep 17 00:00:00 2001 From: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com> Date: Thu, 19 Dec 2024 11:55:16 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/reference/esql/esql-limitations.asciidoc | 2 +- docs/reference/esql/processing-commands/where.asciidoc | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/reference/esql/esql-limitations.asciidoc b/docs/reference/esql/esql-limitations.asciidoc index 962fcef4bc077..0710acf3749d2 100644 --- a/docs/reference/esql/esql-limitations.asciidoc +++ b/docs/reference/esql/esql-limitations.asciidoc @@ -139,7 +139,7 @@ FROM books | WHERE MATCH(author, "Faulkner") OR author LIKE "Hemingway" ---- -but this one will succeed, as it uses full text functions on both OR clauses: +However this query will succeed because it uses full text functions on both `OR` clauses: [source,esql] ---- diff --git a/docs/reference/esql/processing-commands/where.asciidoc b/docs/reference/esql/processing-commands/where.asciidoc index aaf503802848e..68336d5358eaf 100644 --- a/docs/reference/esql/processing-commands/where.asciidoc +++ b/docs/reference/esql/processing-commands/where.asciidoc @@ -73,7 +73,10 @@ include::{esql-specs}/match-function.csv-spec[tag=match-with-field] include::{esql-specs}/match-function.csv-spec[tag=match-with-field-result] |=== -For a simplified syntax, you can use the <> `:` instead of `MATCH`. +[TIP] +==== +You can also use the shorthand <> `:` instead of `MATCH`. +==== include::../functions/like.asciidoc[tag=body]