diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md b/docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md index 12c90e21a25b8..6beb7605cab5b 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md +++ b/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. + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md b/docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md index 2a303e0ba07b0..59783da9bcfbe 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md +++ b/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 ::: diff --git a/docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json b/docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json index 44307d2807023..c42b59c49ddcb 100644 --- a/docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json @@ -529,7 +529,9 @@ } ], "examples" : [ - "FROM books\n| WHERE author:\"Faulkner\"" + "FROM books\n| WHERE author:\"Faulkner\"", + "FROM employees\n| WHERE job_positions:\"Internship\"\n| KEEP emp_no, job_positions", + "FROM books METADATA _score\n| WHERE semantic_title:\"Shakespeare\"\n| SORT _score DESC\n| KEEP _score, semantic_title" ], "preview" : false, "snapshot_only" : false diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-operator.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-operator.csv-spec index b617b85949d7f..53b085e9316ab 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-operator.csv-spec +++ b/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 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 64dcc1dcd150e..735901aa5b694 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 @@ -43,7 +43,27 @@ Use the match operator (`:`) to perform a <> <>. `:` 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,