ESQL - Update WHERE command docs with MATCH and full text functions examples (#118987)

docs/reference/esql/esql-limitations.asciidoc

@@ -112,7 +112,7 @@ it is necessary to use the search function, like <<esql-match>>, in a <<esql-whe
 directly after the <<esql-from>> source command, or close enough to it.
 Otherwise, the query will fail with a validation error.
 Another limitation is that any <<esql-where>> 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 <<esql-limitations-text-fields,the way {esql} treats `text` values>>,
 any queries on `text` fields that do not explicitly use the full-text functions,
 <<esql-match>> or <<esql-qstr>>, will behave as if the fields are actually `keyword` fields:

docs/reference/esql/functions/description/match.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Performs a <<query-dsl-match-query,match query>> on the specified field. Returns true if the provided query matches the row.
+Use `MATCH` to perform a <<query-dsl-match-query,match query>> 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 <<esql-search-operators,match operator>> `:` operator instead of `MATCH`.  `MATCH` returns true if the provided query matches the row.

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 <<query-dsl-match-query,match query>> on the specified field. Returns true if the provided query matches the row.",
+  "description" : "Use `MATCH` to perform a <<query-dsl-match-query,match query>> 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 <<esql-search-operators,match operator>> `:` operator instead of `MATCH`.\n\n`MATCH` returns true if the provided query matches the row.",
   "signatures" : [
     {
       "params" : [

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 <<query-dsl-match-query,match query>> on the specified field. Returns true if the provided query matches the row.
+Use `MATCH` to perform a <<query-dsl-match-query,match query>> 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 <<esql-search-operators,match operator>> `:` operator instead of `MATCH`.
+
+`MATCH` returns true if the provided query matches the row.
 
 ```
 FROM books 

docs/reference/esql/functions/search-functions.asciidoc

@@ -6,11 +6,13 @@
 ++++
 
 Full text functions are used to search for text in fields.
-<<analysis, Text analysiss>> is used to analyze the query before it is searched.
+<<analysis, Text analysis>> is used to analyze the query before it is searched.
 
 Full text functions can be used to match <<esql-multivalued-fields,multivalued fields>>.
 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 <<esql-limitations-full-text-search,full text search limitations>> for information on the limitations of full text search.
 
 {esql} supports these full-text search functions:

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 <<esql-functions>>.
 
 include::../functions/predicates.asciidoc[tag=body]
 
+For matching text, you can use <<esql-search-functions,full text search functions>> like `MATCH`.
+
+Use <<esql-match,`MATCH`>> to perform a <<query-dsl-match-query,match query>> 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 <<esql-search-operators,match operator>> `:` instead of `MATCH`.
+====
+
 include::../functions/like.asciidoc[tag=body]
 
 include::../functions/rlike.asciidoc[tag=body]

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 <<query-dsl-match-query,match query>> on the specified field. "
-            + "Returns true if the provided query matches the row.",
+        description = """
+            Use `MATCH` to perform a <<query-dsl-match-query,match query>> 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 <<esql-search-operators,match operator>> `:` 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(