Add comments and javadocs

Author: carlosdelest

x-pack/plugin/esql/compute/src/main/java/org/elasticsearch/compute/lucene/LuceneQueryExpressionEvaluator.java

@@ -149,7 +149,7 @@ private Vector evalSlow(DocVector docs) throws IOException {
                 prevSegment = segment;
             }
             if (segmentState.noMatch) {
-                docScorerVectorProvider.scoreNoHit();
+                docScorerVectorProvider.addNoMatchingDoc();
             } else {
                 segmentState.scoreSingleDocWithScorer(docs.docs().getInt(map[i]));
             }
@@ -291,14 +291,14 @@ private void initScorer(int minDocId) throws IOException {
 
         private void scoreSingleDocWithScorer(int doc) throws IOException {
             if (scorer.iterator().docID() == doc) {
-                docScorerVectorProvider.scoreHit(scorer);
+                docScorerVectorProvider.addNatchingDoc(scorer);
             } else if (scorer.iterator().docID() > doc) {
-                docScorerVectorProvider.scoreNoHit();
+                docScorerVectorProvider.addNoMatchingDoc();
             } else {
                 if (scorer.iterator().advance(doc) == doc) {
-                    docScorerVectorProvider.scoreHit(scorer);
+                    docScorerVectorProvider.addNatchingDoc(scorer);
                 } else {
-                    docScorerVectorProvider.scoreNoHit();
+                    docScorerVectorProvider.addNoMatchingDoc();
                 }
             }
         }
@@ -334,9 +334,9 @@ public void setScorer(Scorable scorable) {
         @Override
         public void collect(int doc) throws IOException {
             while (next++ < doc) {
-                docScorerVectorProvider.scoreNoHit();
+                docScorerVectorProvider.addNoMatchingDoc();
             }
-            docScorerVectorProvider.scoreHit(scorable);
+            docScorerVectorProvider.addNatchingDoc(scorable);
         }
 
         public Vector build() {
@@ -346,7 +346,7 @@ public Vector build() {
         @Override
         public void finish() {
             while (next++ <= max) {
-                docScorerVectorProvider.scoreNoHit();
+                docScorerVectorProvider.addNoMatchingDoc();
             }
         }
 
@@ -356,18 +356,40 @@ public void close() {
         }
     }
 
+    /**
+     * Encapsulates the logic for scoring documents, depending on whether we need a boolean vector for filtering
+     * or a double vector for scoring
+     */
     private interface DocScorerVectorProvider extends Releasable {
 
+        /**
+         * Returns the vector to use when no documents match the query
+         */
         Vector noMatchVector(int docs);
 
+        /**
+         * Initializes the vector to build. Needed to be called before scoring any documents
+         */
         void init(int numDocs);
 
-        void scoreHit(Scorable scorable) throws IOException;
+        /**
+         * Adds a document that matches the query
+         */
+        void addNatchingDoc(Scorable scorable) throws IOException;
 
-        void scoreNoHit();
+        /**
+         * Adds a document that does not match the query
+         */
+        void addNoMatchingDoc();
 
+        /**
+         * Builds the resulting vector after adding all docs
+         */
         Vector build();
 
+        /**
+         * Retrieves the score mode for the query
+         */
         ScoreMode scoreMode();
     }
 
@@ -396,13 +418,13 @@ public void init(int numDocs) {
         }
 
         @Override
-        public void scoreHit(Scorable scorable) {
+        public void addNatchingDoc(Scorable scorable) {
             assert builder != null : "init must be called before scoring";
             builder.appendBoolean(true);
         }
 
         @Override
-        public void scoreNoHit() {
+        public void addNoMatchingDoc() {
             assert builder != null : "init must be called before scoring";
             builder.appendBoolean(false);
         }
@@ -444,13 +466,13 @@ public void init(int numDocs) {
         }
 
         @Override
-        public void scoreHit(Scorable scorable) throws IOException {
+        public void addNatchingDoc(Scorable scorable) throws IOException {
             assert builder != null : "init must be called before scoring";
             builder.appendDouble(scorable.score());
         }
 
         @Override
-        public void scoreNoHit() {
+        public void addNoMatchingDoc() {
             assert builder != null : "init must be called before scoring";
             builder.appendDouble(SCORE_FOR_FALSE);
         }

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/evaluator/mapper/BooleanToScoringExpressionEvaluator.java

@@ -17,6 +17,11 @@
 
 import static org.elasticsearch.compute.lucene.LuceneQueryExpressionEvaluator.SCORE_FOR_FALSE;
 
+/**
+ * Converts a {@link BooleanBlock} to a {@link DoubleBlock} if needed. This is needed to convert boolean expressions
+ * into scores that can be mixed together with other scoring expressions, or just for boolean expressions to be scored.
+ * Scores are converted using 1.0 for true and {* @link LuceneQueryExpressionEvaluator#SCORE_FOR_FALSE} for false.
+ */
 public class BooleanToScoringExpressionEvaluator implements EvalOperator.ExpressionEvaluator {
 
     private final EvalOperator.ExpressionEvaluator inner;

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/evaluator/predicate/operator/logical/NotScoringEvaluator.java

@@ -20,8 +20,8 @@
 import static org.elasticsearch.compute.lucene.LuceneQueryExpressionEvaluator.SCORE_FOR_FALSE;
 
 /**
- * {@link EvalOperator.ExpressionEvaluator} implementation for {@link Not}.
- * This class is generated. Do not edit it.
+ * {@link EvalOperator.ExpressionEvaluator} implementation for {@link Not} when scores are used.
+ * It returns 0.0 for false and {@link org.elasticsearch.compute.lucene.LuceneQueryExpressionEvaluator#SCORE_FOR_FALSE} for true.
  */
 public final class NotScoringEvaluator implements EvalOperator.ExpressionEvaluator {
     private final Source source;

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

@@ -23,11 +23,9 @@
 import org.elasticsearch.xpack.esql.core.querydsl.query.Query;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
-import org.elasticsearch.xpack.esql.core.util.Holder;
 import org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper;
 import org.elasticsearch.xpack.esql.expression.predicate.logical.BinaryLogic;
 import org.elasticsearch.xpack.esql.expression.predicate.logical.Not;
-import org.elasticsearch.xpack.esql.expression.predicate.logical.Or;
 import org.elasticsearch.xpack.esql.optimizer.rules.physical.local.LucenePushdownPredicates;
 import org.elasticsearch.xpack.esql.plan.logical.Aggregate;
 import org.elasticsearch.xpack.esql.plan.logical.EsRelation;
@@ -214,65 +212,6 @@ private static void checkFullTextQueryFunctions(LogicalPlan plan, Failures failu
         }
     }
 
-    /**
-     * Checks whether a condition contains a disjunction with a full text search.
-     * If it does, check that every element of the disjunction is a full text search or combinations (AND, OR, NOT) of them.
-     * If not, add a failure to the failures collection.
-     *
-     * @param condition        condition to check for disjunctions of full text searches
-     * @param failures         failures collection to add to
-     */
-    private static void checkFullTextSearchDisjunctions(Expression condition, Failures failures) {
-        Holder<Boolean> isInvalid = new Holder<>(false);
-        condition.forEachDown(Or.class, or -> {
-            if (isInvalid.get()) {
-                // Exit early if we already have a failures
-                return;
-            }
-            if (checkDisjunctionPushable(or) == false) {
-                isInvalid.set(true);
-                failures.add(
-                    fail(
-                        or,
-                        "Invalid condition when using METADATA _score [{}]. Full text functions can be used in an OR condition, "
-                            + "but only if just full text functions are used in the OR condition",
-                        or.sourceText()
-                    )
-                );
-            }
-        });
-    }
-
-    /**
-     * Checks if a disjunction is pushable from the point of view of FullTextFunctions. Either it has no FullTextFunctions disjunction
-     * all it contains are FullTextFunctions.
-     *
-     * @param disjunction disjunction to check
-     * @return true if the disjunction is pushable, false otherwise
-     */
-    public static boolean checkDisjunctionPushable(Expression disjunction) {
-        boolean hasFullText = disjunction.anyMatch(FullTextFunction.class::isInstance);
-        return hasFullText == false || onlyFullTextFunctionsInExpression(disjunction);
-    }
-
-    /**
-     * Checks whether an expression contains just full text functions or negations (NOT) and combinations (AND, OR) of full text functions
-     *
-     * @param expression expression to check
-     * @return true if all children are full text functions or negations of full text functions, false otherwise
-     */
-    private static boolean onlyFullTextFunctionsInExpression(Expression expression) {
-        if (expression instanceof FullTextFunction) {
-            return true;
-        } else if (expression instanceof Not) {
-            return onlyFullTextFunctionsInExpression(expression.children().get(0));
-        } else if (expression instanceof BinaryLogic binaryLogic) {
-            return onlyFullTextFunctionsInExpression(binaryLogic.left()) && onlyFullTextFunctionsInExpression(binaryLogic.right());
-        }
-
-        return false;
-    }
-
     /**
      * Checks all commands that exist before a specific type satisfy conditions.
      *

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/logical/BinaryLogic.java

@@ -34,6 +34,7 @@
 
 public abstract class BinaryLogic extends BinaryOperator<Boolean, Boolean, Boolean, BinaryLogicOperation> implements TranslationAware {
 
+    // Provides a way to score the result of the logical operation in case scoring is used
     private final BinaryScoringLogicOperation scoringFunction;
 
     protected BinaryLogic(

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/logical/BinaryScoringLogicOperation.java

@@ -13,6 +13,9 @@
 
 import static org.elasticsearch.compute.lucene.LuceneQueryExpressionEvaluator.SCORE_FOR_FALSE;
 
+/**
+ * Implementation of binary logic operations when scores are used
+ */
 public enum BinaryScoringLogicOperation implements PredicateBiFunction<Double, Double, Double> {
 
     AND((l, r) -> {

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/logical/BooleanLogicExpressionEvaluator.java

@@ -18,6 +18,9 @@
 
 import java.util.Objects;
 
+/**
+ * Expression evaluator for boolean logic operations. To be used when scoring is not used
+ */
 public class BooleanLogicExpressionEvaluator implements EvalOperator.ExpressionEvaluator {
     private final BinaryLogicOperation bl;
     private final EvalOperator.ExpressionEvaluator leftEval;

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/logical/BooleanScoringLogicExpressionEvaluator.java

@@ -19,6 +19,10 @@
 
 import java.util.Objects;
 
+/**
+ * Expression evaluator for boolean logic operations when scoring is used
+ * TODO May merge with {@link BooleanLogicExpressionEvaluator} instead of separating into a new class
+ */
 public class BooleanScoringLogicExpressionEvaluator implements EvalOperator.ExpressionEvaluator {
     private final BinaryScoringLogicOperation bsl;
     private final EvalOperator.ExpressionEvaluator leftEval;