Take match_phrase out of snapshot and make tech preview (elastic#128925)

* Take match_phrase out of snapshot and make tech preview

* Update docs/changelog/128925.yaml

* PR feedback

* Adding regenerated test data

* Update docs/changelog/128925.yaml

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

* [CI] Auto commit changes from spotless

* Checkstyle

* Correct docs

* Hopefully fix docs build

* Found one more bad docs link - here's hoping this now fixes the doc build

* OMG bitten by - vs _

---------

Co-authored-by: Carlos Delgado <[email protected]>
Co-authored-by: elasticsearchmachine <[email protected]>
Co-authored-by: Aurélien FOUCRET <[email protected]>

Author: 4 people

docs/changelog/128925.yaml

@@ -0,0 +1,5 @@
+pr: 128925
+summary: ES|QL - Add `match_phrase` full text function (tech preview)
+area: ES|QL
+type: enhancement
+issues: []

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

@@ -9,5 +9,5 @@
 :   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.
+:   (Optional) MatchPhrase additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) for more information.
 

x-pack/plugin/esql/src/internalClusterTest/java/org/elasticsearch/xpack/esql/plugin/MatchPhraseFunctionIT.java

@@ -13,9 +13,6 @@
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.xpack.esql.VerificationException;
 import org.elasticsearch.xpack.esql.action.AbstractEsqlIntegTestCase;
-import org.elasticsearch.xpack.esql.action.EsqlCapabilities;
-import org.elasticsearch.xpack.esql.action.EsqlQueryRequest;
-import org.elasticsearch.xpack.esql.action.EsqlQueryResponse;
 import org.hamcrest.Matchers;
 import org.junit.Before;
 
@@ -34,12 +31,6 @@ public void setupIndex() {
         createAndPopulateIndex();
     }
 
-    @Override
-    protected EsqlQueryResponse run(EsqlQueryRequest request) {
-        assumeTrue("match_phrase function capability not available", EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled());
-        return super.run(request);
-    }
-
     public void testSimpleWhereMatchPhrase() {
         var query = """
             FROM test

x-pack/plugin/esql/src/internalClusterTest/java/org/elasticsearch/xpack/esql/plugin/ScoringIT.java

@@ -49,12 +49,10 @@ public static List<Object[]> params() {
         params.add(new Object[] { "content:\"fox\"" });
         params.add(new Object[] { "qstr(\"content: fox\")" });
         params.add(new Object[] { "kql(\"content*: fox\")" });
+        params.add(new Object[] { "match_phrase(content, \"fox\")" });
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             params.add(new Object[] { "term(content, \"fox\")" });
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            params.add(new Object[] { "match_phrase(content, \"fox\")" });
-        }
         return params;
     }
 

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

@@ -930,7 +930,7 @@ public enum Cap {
         /**
          * MATCH PHRASE function
          */
-        MATCH_PHRASE_FUNCTION(Build.current().isSnapshot());
+        MATCH_PHRASE_FUNCTION;
 
         private final boolean enabled;
 

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

@@ -24,15 +24,12 @@ public static List<NamedWriteableRegistry.Entry> getNamedWriteables() {
         entries.add(QueryString.ENTRY);
         entries.add(Match.ENTRY);
         entries.add(Kql.ENTRY);
+        entries.add(MatchPhrase.ENTRY);
 
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             entries.add(Term.ENTRY);
         }
 
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            entries.add(MatchPhrase.ENTRY);
-        }
-
         return Collections.unmodifiableList(entries);
     }
 }

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

@@ -94,7 +94,8 @@ public class MatchPhrase extends FullTextFunction implements OptionalArgument, P
         returnType = "boolean",
         preview = true,
         description = """
-            Use `MATCH_PHRASE` to perform a <<query-dsl-match-query-phrase,match_phrase query>> on the specified field.
+            Use `MATCH_PHRASE` to perform a [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) on the
+            specified field.
             Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL.
 
             MatchPhrase can be used on <<text, text>> fields, as well as other field types like keyword, boolean, or date types.
@@ -149,7 +150,7 @@ public MatchPhrase(
                     description = "Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0."
                 ) },
             description = "(Optional) MatchPhrase additional options as <<esql-function-named-params,function named parameters>>."
-                + " See <<query-dsl-match-query-phrase,match_phrase query>> for more information.",
+                + " See [`match_phrase`](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) for more information.",
             optional = true
         ) Expression options
     ) {

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/VerifierTests.java

@@ -1226,14 +1226,13 @@ public void testFieldBasedFullTextFunctions() throws Exception {
         checkFieldBasedWithNonIndexedColumn(":", "text : \"cat\"", "operator");
         checkFieldBasedFunctionNotAllowedAfterCommands(":", "operator", "title : \"Meditation\"");
 
+        checkFieldBasedWithNonIndexedColumn("MatchPhrase", "match_phrase(text, \"cat\")", "function");
+        checkFieldBasedFunctionNotAllowedAfterCommands("MatchPhrase", "function", "match_phrase(title, \"Meditation\")");
+
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             checkFieldBasedWithNonIndexedColumn("Term", "term(text, \"cat\")", "function");
             checkFieldBasedFunctionNotAllowedAfterCommands("Term", "function", "term(title, \"Meditation\")");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkFieldBasedWithNonIndexedColumn("MatchPhrase", "match_phrase(text, \"cat\")", "function");
-            checkFieldBasedFunctionNotAllowedAfterCommands("MatchPhrase", "function", "match_phrase(title, \"Meditation\")");
-        }
     }
 
     private void checkFieldBasedFunctionNotAllowedAfterCommands(String functionName, String functionType, String functionInvocation) {
@@ -1357,12 +1356,10 @@ public void testFullTextFunctionsOnlyAllowedInWhere() throws Exception {
         checkFullTextFunctionsOnlyAllowedInWhere(":", "title:\"Meditation\"", "operator");
         checkFullTextFunctionsOnlyAllowedInWhere("QSTR", "qstr(\"Meditation\")", "function");
         checkFullTextFunctionsOnlyAllowedInWhere("KQL", "kql(\"Meditation\")", "function");
+        checkFullTextFunctionsOnlyAllowedInWhere("MatchPhrase", "match_phrase(title, \"Meditation\")", "function");
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             checkFullTextFunctionsOnlyAllowedInWhere("Term", "term(title, \"Meditation\")", "function");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkFullTextFunctionsOnlyAllowedInWhere("MatchPhrase", "match_phrase(title, \"Meditation\")", "function");
-        }
     }
 
     private void checkFullTextFunctionsOnlyAllowedInWhere(String functionName, String functionInvocation, String functionType)
@@ -1392,12 +1389,13 @@ public void testFullTextFunctionsDisjunctions() {
         checkWithFullTextFunctionsDisjunctions("title : \"Meditation\"");
         checkWithFullTextFunctionsDisjunctions("qstr(\"title: Meditation\")");
         checkWithFullTextFunctionsDisjunctions("kql(\"title: Meditation\")");
+        checkWithFullTextFunctionsDisjunctions("match_phrase(title, \"Meditation\")");
+        if (EsqlCapabilities.Cap.MULTI_MATCH_FUNCTION.isEnabled()) {
+            checkWithFullTextFunctionsDisjunctions("multi_match(\"Meditation\", title, body)");
+        }
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             checkWithFullTextFunctionsDisjunctions("term(title, \"Meditation\")");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkWithFullTextFunctionsDisjunctions("match_phrase(title, \"Meditation\")");
-        }
     }
 
     private void checkWithFullTextFunctionsDisjunctions(String functionInvocation) {
@@ -1453,12 +1451,10 @@ public void testFullTextFunctionsWithNonBooleanFunctions() {
         checkFullTextFunctionsWithNonBooleanFunctions(":", "title:\"Meditation\"", "operator");
         checkFullTextFunctionsWithNonBooleanFunctions("QSTR", "qstr(\"title: Meditation\")", "function");
         checkFullTextFunctionsWithNonBooleanFunctions("KQL", "kql(\"title: Meditation\")", "function");
+        checkFullTextFunctionsWithNonBooleanFunctions("MatchPhrase", "match_phrase(title, \"Meditation\")", "function");
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             checkFullTextFunctionsWithNonBooleanFunctions("Term", "term(title, \"Meditation\")", "function");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkFullTextFunctionsWithNonBooleanFunctions("MatchPhrase", "match_phrase(title, \"Meditation\")", "function");
-        }
     }
 
     private void checkFullTextFunctionsWithNonBooleanFunctions(String functionName, String functionInvocation, String functionType) {
@@ -1520,12 +1516,10 @@ private void checkFullTextFunctionsWithNonBooleanFunctions(String functionName,
     public void testFullTextFunctionsTargetsExistingField() throws Exception {
         testFullTextFunctionTargetsExistingField("match(title, \"Meditation\")");
         testFullTextFunctionTargetsExistingField("title : \"Meditation\"");
+        testFullTextFunctionTargetsExistingField("match_phrase(title, \"Meditation\")");
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             testFullTextFunctionTargetsExistingField("term(fist_name, \"Meditation\")");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            testFullTextFunctionTargetsExistingField("match_phrase(title, \"Meditation\")");
-        }
     }
 
     private void testFullTextFunctionTargetsExistingField(String functionInvocation) throws Exception {
@@ -2044,9 +2038,7 @@ public void testLookupJoinDataTypeMismatch() {
     public void testFullTextFunctionOptions() {
         checkOptionDataTypes(Match.ALLOWED_OPTIONS, "FROM test | WHERE match(title, \"Jean\", {\"%s\": %s})");
         checkOptionDataTypes(QueryString.ALLOWED_OPTIONS, "FROM test | WHERE QSTR(\"title: Jean\", {\"%s\": %s})");
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkOptionDataTypes(MatchPhrase.ALLOWED_OPTIONS, "FROM test | WHERE MATCH_PHRASE(title, \"Jean\", {\"%s\": %s})");
-        }
+        checkOptionDataTypes(MatchPhrase.ALLOWED_OPTIONS, "FROM test | WHERE MATCH_PHRASE(title, \"Jean\", {\"%s\": %s})");
     }
 
     /**
@@ -2101,12 +2093,10 @@ private static String exampleValueForType(DataType currentType) {
     public void testFullTextFunctionCurrentlyUnsupportedBehaviour() throws Exception {
         testFullTextFunctionsCurrentlyUnsupportedBehaviour("match(title, \"Meditation\")");
         testFullTextFunctionsCurrentlyUnsupportedBehaviour("title : \"Meditation\"");
+        testFullTextFunctionsCurrentlyUnsupportedBehaviour("match_phrase(title, \"Meditation\")");
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             testFullTextFunctionsCurrentlyUnsupportedBehaviour("term(title, \"Meditation\")");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            testFullTextFunctionsCurrentlyUnsupportedBehaviour("match_phrase(title, \"Meditation\")");
-        }
     }
 
     private void testFullTextFunctionsCurrentlyUnsupportedBehaviour(String functionInvocation) throws Exception {
@@ -2121,14 +2111,16 @@ public void testFullTextFunctionsNullArgs() throws Exception {
         checkFullTextFunctionNullArgs("match(title, null)", "second");
         checkFullTextFunctionNullArgs("qstr(null)", "");
         checkFullTextFunctionNullArgs("kql(null)", "");
+        checkFullTextFunctionNullArgs("match_phrase(null, \"query\")", "first");
+        checkFullTextFunctionNullArgs("match_phrase(title, null)", "second");
+        if (EsqlCapabilities.Cap.MULTI_MATCH_FUNCTION.isEnabled()) {
+            checkFullTextFunctionNullArgs("multi_match(null, title)", "first");
+            checkFullTextFunctionNullArgs("multi_match(\"query\", null)", "second");
+        }
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             checkFullTextFunctionNullArgs("term(null, \"query\")", "first");
             checkFullTextFunctionNullArgs("term(title, null)", "second");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkFullTextFunctionNullArgs("match_phrase(null, \"query\")", "first");
-            checkFullTextFunctionNullArgs("match_phrase(title, null)", "second");
-        }
     }
 
     private void checkFullTextFunctionNullArgs(String functionInvocation, String argOrdinal) throws Exception {
@@ -2142,12 +2134,10 @@ public void testFullTextFunctionsConstantQuery() throws Exception {
         checkFullTextFunctionsConstantQuery("match(title, category)", "second");
         checkFullTextFunctionsConstantQuery("qstr(title)", "");
         checkFullTextFunctionsConstantQuery("kql(title)", "");
+        checkFullTextFunctionsConstantQuery("match_phrase(title, tags)", "second");
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {
             checkFullTextFunctionsConstantQuery("term(title, tags)", "second");
         }
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkFullTextFunctionsConstantQuery("match_phrase(title, tags)", "second");
-        }
     }
 
     private void checkFullTextFunctionsConstantQuery(String functionInvocation, String argOrdinal) throws Exception {
@@ -2162,9 +2152,7 @@ public void testFullTextFunctionsInStats() {
         checkFullTextFunctionsInStats("title : \"Meditation\"");
         checkFullTextFunctionsInStats("qstr(\"title: Meditation\")");
         checkFullTextFunctionsInStats("kql(\"title: Meditation\")");
-        if (EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled()) {
-            checkFullTextFunctionsInStats("match_phrase(title, \"Meditation\")");
-        }
+        checkFullTextFunctionsInStats("match_phrase(title, \"Meditation\")");
     }
 
     private void checkFullTextFunctionsInStats(String functionInvocation) {

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhraseTests.java

@@ -11,7 +11,6 @@
 import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
 
 import org.elasticsearch.index.query.QueryBuilder;
-import org.elasticsearch.xpack.esql.action.EsqlCapabilities;
 import org.elasticsearch.xpack.esql.core.expression.Expression;
 import org.elasticsearch.xpack.esql.core.expression.FieldAttribute;
 import org.elasticsearch.xpack.esql.core.expression.Literal;
@@ -23,7 +22,6 @@
 import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
 import org.elasticsearch.xpack.esql.io.stream.PlanStreamOutput;
 import org.elasticsearch.xpack.esql.optimizer.rules.physical.local.LucenePushdownPredicates;
-import org.junit.Before;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -41,11 +39,6 @@
 @FunctionName("match_phrase")
 public class MatchPhraseTests extends AbstractFunctionTestCase {
 
-    @Before
-    public void checkCapability() {
-        assumeTrue("MatchPhrase is not supported in this version of ESQL", EsqlCapabilities.Cap.MATCH_PHRASE_FUNCTION.isEnabled());
-    }
-
     public MatchPhraseTests(@Name("TestCase") Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
         this.testCase = testCaseSupplier.get();
     }

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/60_usage.yml

@@ -101,7 +101,7 @@ setup:
   - gt: {esql.functions.to_long: $functions_to_long}
   - match: {esql.functions.coalesce: $functions_coalesce}
   # Testing for the entire function set isn't feasible, so we just check that we return the correct count as an approximation.
-  - length: {esql.functions: 145} # check the "sister" test below for a likely update to the same esql.functions length check
+  - length: {esql.functions: 157} # check the "sister" test below for a likely update to the same esql.functions length check
 
 ---
 "Basic ESQL usage output (telemetry) non-snapshot version":