[ES|QL] Add MATCH_PHRASE (elastic#127661)

* Initial commit of match_phrase

* Add MatchPhraseQueryTests

* First pass at CSV specs

* Update docs/changelog/127661.yaml

* Refactor so MatchPhrase doesn't use all fulltext test cases, just text only

* Fix tests

* Add some CSV test cases

* Fix test

* Update changelog

* Update tests

* Comment out MATCH_PHRASE in search-functions Markdown

* Minor PR feedback

* PR feedback - refactor/consolidate code

* Add some more tests

* Fix some tests

* [CI] Auto commit changes from spotless

* Fix tests

* PR feedback - add tests, support boost and numeric data

* Revert "PR feedback - add tests, support boost and numeric data"

This reverts commit 4e7a699.

* Apply testing/PR feedback outside numeric support only

* Regenerate docs

* Add negative test

* Update x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-phrase-function.csv-spec

Co-authored-by: Carlos Delgado <[email protected]>

* Update x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-phrase-function.csv-spec

Co-authored-by: Carlos Delgado <[email protected]>

* Update x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-phrase-function.csv-spec

Co-authored-by: Carlos Delgado <[email protected]>

* PR feedback

* Fix auto-commit error

* Regenerate docs

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

Co-authored-by: Liam Thompson <[email protected]>

* Remove non text field types

* Fake test data

* Remove tests that no longer should pass without ip/date/version support

* Put real data in score tests now that I was able to engineer a failure

* Realized the scoring test might be flakey because how it was written, updated

* PR feedback

* PR feedback

* [CI] Auto commit changes from spotless

* Add check to MatchPhrase tests

* Fix merge errors

* [CI] Auto commit changes from spotless

* Test generated docs

* Add additional verifier tests

---------

Co-authored-by: elasticsearchmachine <[email protected]>
Co-authored-by: Carlos Delgado <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
(cherry picked from commit eee423a)

# Conflicts:
#	docs/reference/esql/functions/description/match_phrase.md
#	docs/reference/esql/functions/examples/match_phrase.md
#	docs/reference/esql/functions/kibana/definition/match_phrase.json
#	docs/reference/esql/functions/kibana/docs/match_phrase.md
#	docs/reference/query-languages/esql/_snippets/lists/search-functions.md
#	docs/reference/query-languages/esql/functions-operators/search-functions.md
#	x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java
#	x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/EsqlFunctionRegistry.java
#	x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/FullTextFunction.java
#	x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java
#	x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java
#	x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/VerifierTests.java

Author: kderusso

docs/changelog/127661.yaml

@@ -0,0 +1,5 @@
+pr: 127661
+summary: Add MATCH_PHRASE
+area: ES|QL
+type: enhancement
+issues: []

docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match_phrase.md

@@ -0,0 +1,16 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+**Supported function named parameters**
+
+`zero_terms_query`
+:   (keyword) Indicates whether all documents or none are returned if the analyzer removes all tokens, such as when using a stop filter. Defaults to none.
+
+`boost`
+:   (float) Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0.
+
+`analyzer`
+:   (keyword) Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the field. If no analyzer is mapped, the index’s default analyzer is used.
+
+`slop`
+:   (integer) Maximum number of positions allowed between matching tokens. Defaults to 0. Transposed terms have a slop of 2.
+

docs/reference/query-languages/esql/_snippets/functions/layout/match_phrase.md

@@ -0,0 +1,36 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+## `MATCH_PHRASE` [esql-match_phrase]
+:::{warning}
+Do not use on production environments. This functionality is in technical preview and
+may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview
+are not subject to the support SLA of official GA features.
+:::
+
+:::{note}
+###### Serverless: GA, Elastic Stack: COMING
+Support for optional named parameters is only available in serverless, or in a future {{es}} release
+:::
+
+**Syntax**
+
+:::{image} ../../../images/functions/match_phrase.svg
+:alt: Embedded
+:class: text-center
+:::
+
+
+:::{include} ../parameters/match_phrase.md
+:::
+
+:::{include} ../description/match_phrase.md
+:::
+
+:::{include} ../types/match_phrase.md
+:::
+
+:::{include} ../functionNamedParams/match_phrase.md
+:::
+
+:::{include} ../examples/match_phrase.md
+:::

docs/reference/query-languages/esql/_snippets/functions/parameters/match_phrase.md

@@ -0,0 +1,13 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+**Parameters**
+
+`field`
+:   Field that the query will target.
+
+`query`
+:   Value to find in the provided field.
+
+`options`
+:   (Optional) MatchPhrase additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [match_phrase query](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-match-query-phrase) for more information.
+

docs/reference/query-languages/esql/_snippets/functions/types/match_phrase.md

@@ -0,0 +1,9 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+**Supported types**
+
+| field | query | options | result |
+| --- | --- | --- | --- |
+| keyword | keyword | named parameters | boolean |
+| text | keyword | named parameters | boolean |
+

docs/reference/query-languages/esql/images/functions/match_phrase.svg

@@ -129,6 +129,11 @@ public MatchPhraseQueryBuilder zeroTermsQuery(ZeroTermsQueryOption zeroTermsQuer
         return this;
     }
 
+    public MatchPhraseQueryBuilder zeroTermsQuery(String zeroTermsQueryString) {
+        ZeroTermsQueryOption zeroTermsQueryOption = ZeroTermsQueryOption.readFromString(zeroTermsQueryString);
+        return zeroTermsQuery(zeroTermsQueryOption);
+    }
+
     public ZeroTermsQueryOption zeroTermsQuery() {
         return this.zeroTermsQuery;
     }

server/src/main/java/org/elasticsearch/index/query/MatchPhraseQueryBuilder.java

@@ -55,6 +55,15 @@ public static ZeroTermsQueryOption readFromStream(StreamInput in) throws IOExcep
         throw new ElasticsearchException("unknown serialized type [" + ord + "]");
     }
 
+    public static ZeroTermsQueryOption readFromString(String input) {
+        for (ZeroTermsQueryOption zeroTermsQuery : ZeroTermsQueryOption.values()) {
+            if (zeroTermsQuery.name().equalsIgnoreCase(input)) {
+                return zeroTermsQuery;
+            }
+        }
+        throw new ElasticsearchException("unknown serialized type [" + input + "]");
+    }
+
     @Override
     public void writeTo(StreamOutput out) throws IOException {
         out.writeVInt(this.ordinal);