Add multi_match function #121525

docs/changelog/125062.yaml

@@ -2,4 +2,4 @@ pr: 125062
 summary: "Add `multi_match` function #121525"
 area: Search
 type: feature
-issues: []
+issues: [121525]

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

@@ -127,6 +127,60 @@ book_no:keyword | title:text                                            | author
 2847            | To Love A Dark Stranger (Lovegram Historical Romance) | Colleen Faulkner | 1.9662091732025146
 ;
 
+testMultiMatchWithScore1
+required_capability: multi_match_function
+required_capability: metadata_score
+
+from books metadata _score
+| where multi_match("Hobbit", description, title, {"type": "best_fields"})
+| sort book_no
+| eval _score = round(_score)
+| keep book_no, _score;
+ignoreOrder:true
+
+book_no:keyword | _score:double
+1463            | 2.0          
+2301            | 2.0          
+2675            | 2.0          
+2714            | 2.0          
+2936            | 1.0          
+4023            | 2.0          
+4289            | 3.0          
+5335            | 2.0          
+5996            | 2.0          
+6405            | 2.0          
+6760            | 2.0          
+7350            | 2.0          
+7480            | 3.0  
+;
+
+testMultiMatchWithScore2
+required_capability: multi_match_function
+required_capability: metadata_score
+
+from books metadata _score
+| where multi_match("Hobbit", description, title, {"type": "most_fields"})
+| sort book_no
+| eval _score = round(_score)
+| keep book_no, _score;
+ignoreOrder:true
+
+book_no:keyword | _score:double
+1463            | 2.0          
+2301            | 2.0          
+2675            | 2.0          
+2714            | 2.0          
+2936            | 1.0          
+4023            | 2.0          
+4289            | 6.0          
+5335            | 2.0          
+5996            | 2.0          
+6405            | 2.0          
+6760            | 2.0          
+7350            | 2.0          
+7480            | 3.0 
+;
+
 multipleWhereWithMatchScoringNoSort
 required_capability: metadata_score
 required_capability: match_operator_colon

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

@@ -902,7 +902,7 @@ public enum Cap {
         /**
          * Support for multi-match function.
          */
-        MULTI_MATCH_FUNCTION,
+        MULTI_MATCH_FUNCTION(Build.current().isSnapshot()),
 
         /**
          * Do {@code TO_LOWER} and {@code TO_UPPER} process all field values?

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

@@ -12,6 +12,7 @@
 import org.elasticsearch.common.util.FeatureFlag;
 import org.elasticsearch.xpack.esql.core.QlIllegalArgumentException;
 import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.expression.MapExpression;
 import org.elasticsearch.xpack.esql.core.expression.function.Function;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
@@ -1025,7 +1026,12 @@ protected static <T extends Function> FunctionDefinition def(
             } else if (hasMinimumOne == false && children.size() < 2) {
                 throw new QlIllegalArgumentException("expects at least two arguments");
             }
-            return ctorRef.build(source, children.get(0), children.subList(1, children.size() - 1), children.getLast());
+            Expression options = children.getLast();
+            if (options instanceof MapExpression) {
+                return ctorRef.build(source, children.get(0), children.subList(1, children.size() - 1), options);
+            }
+
+            return ctorRef.build(source, children.get(0), children.subList(1, children.size()), null);
         };
         return def(function, builder, names);
     }

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

@@ -200,6 +200,14 @@ private static void checkFullTextQueryFunctions(LogicalPlan plan, Failures failu
                 m -> "[" + m.functionName() + "] " + m.functionType(),
                 failures
             );
+            checkCommandsBeforeExpression(
+                plan,
+                condition,
+                MultiMatch.class,
+                lp -> (lp instanceof Limit == false) && (lp instanceof Aggregate == false),
+                m -> "[" + m.functionName() + "] " + m.functionType(),
+                failures
+            );
             checkCommandsBeforeExpression(
                 plan,
                 condition,

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

@@ -24,6 +24,7 @@
 import org.elasticsearch.xpack.esql.core.expression.FoldContext;
 import org.elasticsearch.xpack.esql.core.expression.Literal;
 import org.elasticsearch.xpack.esql.core.expression.MapExpression;
+import org.elasticsearch.xpack.esql.core.expression.TypeResolutions;
 import org.elasticsearch.xpack.esql.core.querydsl.query.Query;
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
@@ -373,20 +374,19 @@ private TypeResolution resolveOptions() {
         return TypeResolution.TYPE_RESOLVED;
     }
 
-    private Map<String, Object> matchQueryOptions() throws InvalidArgumentException {
-
-        if (options() == null) {
-            return Map.of(LENIENT_FIELD.getPreferredName(), true);
-        }
-
-        Map<String, Object> matchOptions = new HashMap<>();
-        // Match is lenient by default to avoid failing on incompatible types
-        matchOptions.put(LENIENT_FIELD.getPreferredName(), true);
-
-        for (EntryExpression entry : ((MapExpression) options()).entryExpressions()) {
+    public static void populateOptionsMap(
+        final MapExpression options,
+        final Map<String, Object> optionsMap,
+        final TypeResolutions.ParamOrdinal paramOrdinal,
+        final String sourceText,
+        final Map<String, DataType> allowedOptions
+    ) throws InvalidArgumentException {
+        for (EntryExpression entry : options.entryExpressions()) {
             Expression optionExpr = entry.key();
             Expression valueExpr = entry.value();
-            TypeResolution resolution = isFoldable(optionExpr, sourceText(), SECOND).and(isFoldable(valueExpr, sourceText(), SECOND));
+            TypeResolution resolution = isFoldable(optionExpr, sourceText, paramOrdinal).and(
+                isFoldable(valueExpr, sourceText, paramOrdinal)
+            );
             if (resolution.unresolved()) {
                 throw new InvalidArgumentException(resolution.message());
             }
@@ -395,21 +395,30 @@ private Map<String, Object> matchQueryOptions() throws InvalidArgumentException
             String optionName = optionExprLiteral instanceof BytesRef br ? br.utf8ToString() : optionExprLiteral.toString();
             String optionValue = valueExprLiteral instanceof BytesRef br ? br.utf8ToString() : valueExprLiteral.toString();
             // validate the optionExpr is supported
-            DataType dataType = ALLOWED_OPTIONS.get(optionName);
+            DataType dataType = allowedOptions.get(optionName);
             if (dataType == null) {
                 throw new InvalidArgumentException(
-                    format(null, "Invalid option [{}] in [{}], expected one of {}", optionName, sourceText(), ALLOWED_OPTIONS.keySet())
+                    format(null, "Invalid option [{}] in [{}], expected one of {}", optionName, sourceText, allowedOptions.keySet())
                 );
             }
             try {
-                matchOptions.put(optionName, DataTypeConverter.convert(optionValue, dataType));
+                optionsMap.put(optionName, DataTypeConverter.convert(optionValue, dataType));
             } catch (InvalidArgumentException e) {
-                throw new InvalidArgumentException(
-                    format(null, "Invalid option [{}] in [{}], {}", optionName, sourceText(), e.getMessage())
-                );
+                throw new InvalidArgumentException(format(null, "Invalid option [{}] in [{}], {}", optionName, sourceText, e.getMessage()));
             }
         }
+    }
+
+    private Map<String, Object> matchQueryOptions() throws InvalidArgumentException {
+        if (options() == null) {
+            return Map.of(LENIENT_FIELD.getPreferredName(), true);
+        }
+
+        Map<String, Object> matchOptions = new HashMap<>();
+        // Match is lenient by default to avoid failing on incompatible types
+        matchOptions.put(LENIENT_FIELD.getPreferredName(), true);
 
+        populateOptionsMap((MapExpression) options(), matchOptions, SECOND, sourceText(), ALLOWED_OPTIONS);
         return matchOptions;
     }