diff --git a/docs/reference/esql/esql-limitations.asciidoc b/docs/reference/esql/esql-limitations.asciidoc index c2849e4889f98..0710acf3749d2 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" ---- +However this query will succeed because 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/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/functions/search-functions.asciidoc b/docs/reference/esql/functions/search-functions.asciidoc index 238813c382c8c..bfdd288542782 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 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. {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..68336d5358eaf 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,26 @@ For a complete list of all functions, refer to <>. include::../functions/predicates.asciidoc[tag=body] +For matching text, you can use <> like `MATCH`. + +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] +|=== + +[TIP] +==== +You can also use the shorthand <> `:` instead of `MATCH`. +==== + 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 e695a94198dab..fb9f8cff1b8b0 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 @@ -98,8 +98,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.", + 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(