ESQL: Add javadoc for PushDownAndCombineFilters (#132484)

Author: alex-spies

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/optimizer/rules/logical/PushDownAndCombineFilters.java

@@ -34,6 +34,17 @@
 import java.util.function.Function;
 import java.util.function.Predicate;
 
+/**
+ * Perform filters as early as possible in the logical plan by pushing them past certain plan nodes (like {@link Eval},
+ * {@link RegexExtract}, {@link Enrich}, {@link Project}, {@link OrderBy} and left {@link Join}s) where possible.
+ * Ideally, the filter ends up all the way down at the data source and can be turned into a Lucene query.
+ * When pushing down past nodes, only conditions that do not depend on fields created by those nodes are pushed down; if the condition
+ * consists of {@code AND}s, we split out the parts that do not depend on the previous node.
+ * For joins, it splits the filter condition into parts that can be applied to the left or right side of the join and only pushes down
+ * the left hand side filters to the left child.
+ *
+ * Also combines adjacent filters using a logical {@code AND}.
+ */
 public final class PushDownAndCombineFilters extends OptimizerRules.OptimizerRule<Filter> {
     @Override
     protected LogicalPlan rule(Filter filter) {
@@ -73,7 +84,7 @@ protected LogicalPlan rule(Filter filter) {
             var attributes = AttributeSet.of(Expressions.asAttributes(re.extractedFields()));
             plan = maybePushDownPastUnary(filter, re, attributes::contains, NO_OP);
         } else if (child instanceof InferencePlan<?> inferencePlan) {
-            // Push down filters that do not rely on attributes created by Cpmpletion
+            // Push down filters that do not rely on attributes created by Completion
             var attributes = AttributeSet.of(inferencePlan.generatedAttributes());
             plan = maybePushDownPastUnary(filter, inferencePlan, attributes::contains, NO_OP);
         } else if (child instanceof Enrich enrich) {