ES|QL: Add more examples for the match operator

docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md

@@ -1,6 +1,6 @@
 % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
 
-**Example**
+**Examples**
 
 ```esql
 FROM books
@@ -16,3 +16,37 @@ FROM books
 | 3293 | Danny Faulkner |
 
 
+This example illustrates how to do full-text search on a `text` field. Notice how the match operator handles multi-valued columns, if a single value matches the query string, the expression evaluates to `TRUE`
+
+```esql
+FROM employees
+| WHERE job_positions:"Internship"
+| KEEP emp_no, job_positions
+```
+
+| emp_no:integer | job_positions:keyword |
+| --- | --- |
+| 10008 | [Internship, Junior Developer, Purchase Manager, Senior Python Developer] |
+| 10009 | [Internship, Senior Python Developer] |
+| 10022 | [Data Scientist, Internship, Python Developer, Reporting Analyst] |
+
+
+This example illustrates how to use match operator with a `keyword` field to filter multi-values.
+
+```esql
+FROM books METADATA _score
+| WHERE semantic_title:"Shakespeare"
+| SORT _score DESC
+| KEEP _score, semantic_title
+```
+
+| _score:double | semantic_text_field:text |
+| --- | --- |
+| 9.5770 | Romeo and Juliet |
+| 9.6850 | Hamlet |
+| 8.232 | Othello |
+
+
+This example illustrates how to do semantic search using the match operator on `semantic_text` fields. By including the metadata field `_score` and sorting on `_score`, we can retrieve the most relevant results in order.
+
+

docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md

@@ -3,7 +3,7 @@
 stack: preview 9.0, ga 9.1
 ```
 
-The only search operator is match (`:`).
+Use the match operator (`:`) to perform full-text search and filter rows that match a given query string.
 
 **Syntax**
 
@@ -14,11 +14,10 @@ The only search operator is match (`:`).
 
 The match operator performs a [match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) on the specified field. Returns true if the provided query matches the row.
 
-The match operator is equivalent to the [match function](../../../functions-operators/search-functions.md#esql-match).
+The match operator is equivalent to the [match function](../../../functions-operators/search-functions.md#esql-match), which is the standard function for performing full-text search in ES|QL.
 
 For using the function syntax, or adding [match query parameters](/reference/query-languages/query-dsl/query-dsl-match-query.md#match-field-params), you can use the [match function](../../../functions-operators/search-functions.md#esql-match).
 
-
 :::{include} ../types/match_operator.md
 :::
 

x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-operator.csv-spec

@@ -5,23 +5,64 @@
 matchWithField
 required_capability: match_operator_colon
 
-// tag::match-with-field[]
+// tag::match-with-text-field[]
 FROM books 
 | WHERE author:"Faulkner"
-// end::match-with-field[]
+// end::match-with-text-field[]
 | KEEP book_no, author 
-| SORT book_no 
+| SORT book_no
 | LIMIT 5
 ;
 
-// tag::match-with-field-result[]
+// tag::match-with-text-field-result[]
 book_no:keyword | author:text
 2378            | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott]
 2713            | William Faulkner
 2847            | Colleen Faulkner
 2883            | William Faulkner
 3293            | Danny Faulkner
-// end::match-with-field-result[]
+// end::match-with-text-field-result[]
+;
+
+matchWithMultivaluedKeywordField
+required_capability: match_operator_colon
+
+// tag::match-with-keyword-field[]
+FROM employees
+| WHERE job_positions:"Internship"
+| KEEP emp_no, job_positions
+// end::match-with-keyword-field[]
+| SORT emp_no
+| LIMIT 3
+;
+
+// tag::match-with-keyword-field-result[]
+emp_no:integer | job_positions:keyword
+10008          | [Internship, Junior Developer, Purchase Manager, Senior Python Developer]
+10009          | [Internship, Senior Python Developer]
+10022          | [Data Scientist, Internship, Python Developer, Reporting Analyst]
+// end::match-with-keyword-field-result[]
+;
+
+# this is a docs example for semantic search, it's skipped because constructing a meaningful
+# example for semantic search is hard, when we don't use a real ML model to generate embeddings
+matchWithSemanticTextDocsExample-Ignore
+required_capability: match_operator_colon
+
+// tag::match-with-semantic-text-field[]
+FROM books METADATA _score
+| WHERE semantic_title:"Shakespeare"
+| SORT _score DESC
+| KEEP _score, semantic_title
+// end::match-with-semantic-text-field[]
+;
+
+// tag::match-with-semantic-text-field-result[]
+_score:double | semantic_text_field:text
+9.5770        | Romeo and Juliet
+9.6850        | Hamlet
+8.232         | Othello
+// end::match-with-semantic-text-field-result[]
 ;
 
 matchWithMultipleFunctions

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java

@@ -43,7 +43,27 @@ Use the match operator (`:`) to perform a <<query-dsl-match-query,match query>>
             <<esql-match,match function>>.
 
             `:` returns true if the provided query matches the row.""",
-        examples = { @Example(file = "match-operator", tag = "match-with-field") }
+        examples = {
+            @Example(
+                file = "match-operator",
+                tag = "match-with-text-field",
+                explanation = ""
+                    + "This example illustrates how to do full-text search on a `text` field. "
+                    + "Notice how the match operator handles multi-valued columns, if a single value matches the query string, "
+                    + "the expression evaluates to `TRUE`."
+            ),
+            @Example(
+                file = "match-operator",
+                tag = "match-with-keyword-field",
+                explanation = "" + "This example illustrates how to use match operator with a `keyword` field to filter multi-values."
+            ),
+            @Example(
+                file = "match-operator",
+                tag = "match-with-semantic-text-field",
+                explanation = ""
+                    + "This example illustrates how to do semantic search using the match operator on `semantic_text` fields. "
+                    + "By including the metadata field `_score` and sorting on `_score`, we can retrieve the most relevant results in order."
+            ), }
     )
     public MatchOperator(
         Source source,