Add specific docs for match operator using a separate class for holding documentation

Author: carlosdelest

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

@@ -14,13 +14,7 @@ The match operator is equivalent to the <<esql-match,match function>>.
 [.text-center]
 image::esql/functions/signature/match_operator.svg[Embedded,opts=inline]
 
-include::types/match.asciidoc[]
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/match-operator.csv-spec[tag=match-with-field]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/match-operator.csv-spec[tag=match-with-field-result]
-|===
+include::../parameters/match_operator.asciidoc[]
+include::../description/match_operator.asciidoc[]
+include::../types/match_operator.asciidoc[]
+include::../examples/match.asciidoc[]

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

@@ -25,6 +25,7 @@ public static List<NamedWriteableRegistry.Entry> getNamedWriteables() {
         entries.add(MultiMatchQueryPredicate.ENTRY);
         entries.add(QueryString.ENTRY);
         entries.add(Match.ENTRY);
+        entries.add(MatchOperator.ENTRY);
         entries.add(Kql.ENTRY);
 
         if (EsqlCapabilities.Cap.TERM_FUNCTION.isEnabled()) {

docs/reference/esql/functions/kibana/docs/match_operator.md

@@ -63,6 +63,8 @@
 
 /**
  * Full text function that performs a {@link QueryStringQuery} .
+ * Unlike other ESQL functions, Match is both a function and an operator. This class provides implementation for both,
+ * but the operator documentation is generated in {@link MatchOperator}.
  */
 public class Match extends FullTextFunction implements PostOptimizationVerificationAware {
 
@@ -101,7 +103,6 @@ public class Match extends FullTextFunction implements PostOptimizationVerificat
 
     @FunctionInfo(
         returnType = "boolean",
-        operator = ":",
         preview = true,
         description = """
             Use `MATCH` to perform a <<query-dsl-match-query,match query>> on the specified field.
@@ -136,7 +137,7 @@ public Match(Source source, Expression field, Expression matchQuery, QueryBuilde
         this.field = field;
     }
 
-    private static Match readFrom(StreamInput in) throws IOException {
+    protected 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);

docs/reference/esql/functions/search.asciidoc

@@ -0,0 +1,74 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.fulltext;
+
+import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+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.io.stream.PlanStreamInput;
+
+import java.io.IOException;
+
+/**
+ * This class exists to generate documentation for the match operator.
+ * Unlike other ESQL functions, Match is both a function and an operator. This class provides the documentation for the operator.
+ */
+public class MatchOperator extends Match {
+
+    public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "MatchOperator",
+        MatchOperator::readFrom);
+
+    @FunctionInfo(
+        returnType = "boolean",
+        operator = ":",
+        preview = true,
+        description = """
+            Use the match operator (`:`) to perform a <<query-dsl-match-query,match query>> on the specified field.
+            Using `:` is equivalent to using the `match` query in the Elasticsearch Query DSL.
+
+            The match operator is equivalent to the <<esql-match,match function>>.
+
+            For using the function syntax, or adding <<match-field-params,match query parameters>>, you can use the
+            <<esql-match,match function>>.
+
+            `:` returns true if the provided query matches the row.""",
+        examples = { @Example(file = "match-function", tag = "match-with-field") }
+    )
+    public MatchOperator(
+        Source source,
+        @Param(
+            name = "field",
+            type = { "keyword", "text", "boolean", "date", "date_nanos", "double", "integer", "ip", "long", "unsigned_long", "version" },
+            description = "Field that the query will target."
+        ) Expression field,
+        @Param(
+            name = "query",
+            type = { "keyword", "boolean", "date", "date_nanos", "double", "integer", "ip", "long", "unsigned_long", "version" },
+            description = "Value to find in the provided field."
+        ) Expression matchQuery
+    ) {
+        super(source, field, matchQuery);
+    }
+
+    protected 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);
+
+        return new MatchOperator(source, field, query);
+    }
+
+    @Override
+    public String getWriteableName() {
+        return ENTRY.name;
+    }
+}

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

@@ -45,6 +45,7 @@
 import org.elasticsearch.xpack.esql.evaluator.EvalMapper;
 import org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper;
 import org.elasticsearch.xpack.esql.expression.function.fulltext.Match;
+import org.elasticsearch.xpack.esql.expression.function.fulltext.MatchOperator;
 import org.elasticsearch.xpack.esql.expression.function.scalar.conditional.Greatest;
 import org.elasticsearch.xpack.esql.expression.function.scalar.nulls.Coalesce;
 import org.elasticsearch.xpack.esql.expression.function.scalar.string.RLike;
@@ -139,7 +140,7 @@ public abstract class AbstractFunctionTestCase extends ESTestCase {
         entry("is_null", IsNull.class),
         entry("is_not_null", IsNotNull.class),
         // Match operator is both a function and an operator
-        entry("match_operator", Match.class)
+        entry("match_operator", MatchOperator.class)
     );
 
     private static EsqlFunctionRegistry functionRegistry = new EsqlFunctionRegistry().snapshotRegistry();

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

@@ -10,9 +10,12 @@
 import com.carrotsearch.randomizedtesting.annotations.Name;
 import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
 
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.expression.function.FunctionName;
 import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
 
+import java.util.List;
 import java.util.function.Supplier;
 
 /**
@@ -29,4 +32,9 @@ public MatchOperatorTests(@Name("TestCase") Supplier<TestCaseSupplier.TestCase>
     public static Iterable<Object[]> parameters() {
         return MatchTests.parameters();
     }
+
+    @Override
+    protected Expression build(Source source, List<Expression> args) {
+        return new MatchOperator(source, args.get(0), args.get(1));
+    }
 }