Add optional params to Match - fuzziness and boost

Author: carlosdelest

docs/reference/esql/functions/kibana/definition/match.json

@@ -65,6 +65,10 @@ public TypeResolution and(TypeResolution other) {
             return failed ? this : other;
         }
 
+        public TypeResolution or(TypeResolution other) {
+            return resolved() ? this : other;
+        }
+
         public TypeResolution and(Supplier<TypeResolution> other) {
             return failed ? this : other.get();
         }

docs/reference/esql/functions/parameters/match.asciidoc

@@ -105,4 +105,13 @@ protected TypeResolutions.ParamOrdinal queryParamOrdinal() {
     public Nullability nullable() {
         return Nullability.FALSE;
     }
+
+    /**
+     * Used to differentiate error messages between functions and operators
+     *
+     * @return function type for error messages
+     */
+    public String functionType() {
+        return "function";
+    }
 }

docs/reference/esql/functions/signature/match.svg

@@ -7,9 +7,12 @@
 
 package org.elasticsearch.xpack.esql.expression.function.fulltext;
 
+import org.elasticsearch.ElasticsearchParseException;
+import org.elasticsearch.TransportVersions;
 import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
+import org.elasticsearch.common.unit.Fuzziness;
 import org.elasticsearch.xpack.esql.capabilities.Validatable;
 import org.elasticsearch.xpack.esql.common.Failure;
 import org.elasticsearch.xpack.esql.common.Failures;
@@ -19,27 +22,38 @@
 import org.elasticsearch.xpack.esql.core.querydsl.query.QueryStringQuery;
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.core.type.DataType;
 import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
+import org.elasticsearch.xpack.esql.expression.function.TwoOptionalArguments;
 import org.elasticsearch.xpack.esql.io.stream.PlanStreamInput;
 
 import java.io.IOException;
+import java.util.ArrayList;
 import java.util.List;
 
 import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.FIRST;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.FOURTH;
 import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.SECOND;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.THIRD;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isFoldable;
 import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isNotNull;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isNumeric;
 import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isString;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isType;
 
 /**
  * Full text function that performs a {@link QueryStringQuery} .
  */
-public class Match extends FullTextFunction implements Validatable {
+public class Match extends FullTextFunction implements Validatable, TwoOptionalArguments {
 
-    public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "Match", Match::new);
+    public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "Match", Match::readFrom);
 
     private final Expression field;
+    private final Expression boost;
+    private final Expression fuzziness;
+    private final boolean isOperator;
 
     @FunctionInfo(
         returnType = "boolean",
@@ -54,21 +68,68 @@ public Match(
             name = "query",
             type = { "keyword", "text" },
             description = "Text you wish to find in the provided field."
-        ) Expression matchQuery
+        ) Expression matchQuery,
+        @Param(
+            optional = true,
+            name = "boost",
+            type = { "integer", "double" },
+            description = "Boost value for the query."
+        ) Expression boost,
+        @Param(optional = true, name = "boost", type = { "integer", "keyword" }, description = "Query fuzziness") Expression fuzziness
     ) {
-        super(source, matchQuery, List.of(field, matchQuery));
+        this(source, field, matchQuery, boost, fuzziness, false);
+    }
+
+    private Match(Source source, Expression field, Expression matchQuery, Expression boost, Expression fuzziness, boolean isOperator) {
+        super(source, matchQuery, expressionList(field, matchQuery, boost, fuzziness));
         this.field = field;
+        this.boost = boost;
+        this.fuzziness = fuzziness;
+        this.isOperator = isOperator;
+    }
+
+    private static List<Expression> expressionList(Expression field, Expression matchQuery, Expression boost, Expression fuzziness) {
+        List<Expression> list = new ArrayList<>(4);
+        list.add(field);
+        list.add(matchQuery);
+        if (boost != null) {
+            list.add(boost);
+        }
+        if (fuzziness != null) {
+            list.add(fuzziness);
+        }
+        return list;
     }
 
-    private Match(StreamInput in) throws IOException {
-        this(Source.readFrom((PlanStreamInput) in), in.readNamedWriteable(Expression.class), in.readNamedWriteable(Expression.class));
+    public static Match operator(Source source, Expression field, Expression matchQuery, Expression boost, Expression fuzziness) {
+        return new Match(source, field, matchQuery, boost, fuzziness, true);
+    }
+
+    private static Match readFrom(StreamInput in) throws IOException {
+        Source source = Source.readFrom((PlanStreamInput) in);
+        Expression field = in.readNamedWriteable(Expression.class);
+        Expression query = in.readNamedWriteable(Expression.class);
+        boolean isOperator = false;
+        Expression boost = null;
+        Expression fuzziness = null;
+        if (in.getTransportVersion().onOrAfter(TransportVersions.MATCH_OPERATOR_FUZZINESS_BOOSTING)) {
+            boost = in.readOptionalNamedWriteable(Expression.class);
+            fuzziness = in.readOptionalNamedWriteable(Expression.class);
+            isOperator = in.readBoolean();
+        }
+        return new Match(source, field, query, boost, fuzziness, isOperator);
     }
 
     @Override
     public void writeTo(StreamOutput out) throws IOException {
         source().writeTo(out);
-        out.writeNamedWriteable(field);
+        out.writeNamedWriteable(field());
         out.writeNamedWriteable(query());
+        if (out.getTransportVersion().onOrAfter(TransportVersions.MATCH_OPERATOR_FUZZINESS_BOOSTING)) {
+            out.writeOptionalNamedWriteable(boost);
+            out.writeOptionalNamedWriteable(fuzziness);
+            out.writeBoolean(isOperator);
+        }
     }
 
     @Override
@@ -78,7 +139,23 @@ public String getWriteableName() {
 
     @Override
     protected TypeResolution resolveNonQueryParamTypes() {
-        return isNotNull(field, sourceText(), FIRST).and(isString(field, sourceText(), FIRST)).and(super.resolveNonQueryParamTypes());
+        TypeResolution typeResolution = isNotNull(field, sourceText(), FIRST).and(isString(field, sourceText(), FIRST))
+            .and(super.resolveNonQueryParamTypes());
+        if (boost != null) {
+            typeResolution = typeResolution.and(
+                isNotNull(boost, sourceText(), THIRD).and(isNumeric(field, sourceText(), THIRD).and(isFoldable(field, sourceText(), THIRD)))
+            );
+        }
+        if (fuzziness != null) {
+            typeResolution = typeResolution.and(
+                isNotNull(fuzziness, sourceText(), FOURTH).and(
+                    isType(fuzziness, dt -> dt == DataType.INTEGER, sourceText(), FOURTH, "integer,keyword").or(
+                        isString(fuzziness, sourceText(), FOURTH).and(isFoldable(fuzziness, sourceText(), FOURTH))
+                    )
+                )
+            );
+        }
+        return typeResolution;
     }
 
     @Override
@@ -87,23 +164,34 @@ public void validate(Failures failures) {
             failures.add(
                 Failure.fail(
                     field,
-                    "[{}] cannot operate on [{}], which is not a field from an index mapping",
+                    "[{}] {} cannot operate on [{}], which is not a field from an index mapping",
                     functionName(),
+                    functionType(),
                     field.sourceText()
                 )
             );
         }
+        if (fuzziness != null) {
+            try {
+                fuzziness();
+            } catch (IllegalArgumentException | ElasticsearchParseException e) {
+                failures.add(
+                    Failure.fail(field, "Invalid fuzziness value [{}] for [{}] {}", fuzziness.sourceText(), functionName(), functionType())
+                );
+            }
+        }
     }
 
     @Override
     public Expression replaceChildren(List<Expression> newChildren) {
-        // Query is the first child, field is the second child
-        return new Match(source(), newChildren.get(0), newChildren.get(1));
+        Expression boost = newChildren.size() > 2 ? newChildren.get(2) : null;
+        Expression fuzziness = newChildren.size() > 3 ? newChildren.get(3) : null;
+        return new Match(source(), newChildren.get(0), newChildren.get(1), boost, fuzziness, isOperator);
     }
 
     @Override
     protected NodeInfo<? extends Expression> info() {
-        return NodeInfo.create(this, Match::new, field, query());
+        return NodeInfo.create(this, Match::new, field, query(), boost, fuzziness);
     }
 
     protected TypeResolutions.ParamOrdinal queryParamOrdinal() {
@@ -113,4 +201,28 @@ protected TypeResolutions.ParamOrdinal queryParamOrdinal() {
     public Expression field() {
         return field;
     }
+
+    public Double boost() {
+        if (boost == null) {
+            return null;
+        }
+        return (Double) boost.fold();
+    }
+
+    public Fuzziness fuzziness() {
+        if (fuzziness == null) {
+            return null;
+        }
+        return Fuzziness.fromString(fuzziness.fold().toString());
+    }
+
+    @Override
+    public String functionType() {
+        return isOperator ? "operator" : super.functionType();
+    }
+
+    @Override
+    public String functionName() {
+        return isOperator ? ":" : super.functionName();
+    }
 }