Package org.elasticsearch.xpack.esql.expression.function.fulltext

Class SingleFieldFullTextFunction

java.lang.Object
org.elasticsearch.xpack.esql.core.tree.Node<Expression>
org.elasticsearch.xpack.esql.core.expression.Expression
org.elasticsearch.xpack.esql.core.expression.function.Function
org.elasticsearch.xpack.esql.expression.function.fulltext.FullTextFunction
org.elasticsearch.xpack.esql.expression.function.fulltext.SingleFieldFullTextFunction
All Implemented Interfaces:
NamedWriteable, Writeable, PostAnalysisPlanVerificationAware, PostOptimizationPlanVerificationAware, PostOptimizationVerificationAware, RewriteableAware, TranslationAware, Resolvable, EvaluatorMapper, ExpressionScoreMapper
Direct Known Subclasses:
Knn, Match, MatchPhrase
public abstract class SingleFieldFullTextFunction extends FullTextFunction implements PostAnalysisPlanVerificationAware, PostOptimizationPlanVerificationAware
Base class for full-text functions that operate on a single field. This class extracts common functionality from Match and MatchPhrase including: - Field and options management - Type resolution for field and query parameters - Query value conversion - Field verification - Serialization patterns

  • Field Details

  • Constructor Details

  • Method Details

    • field

      public Expression field()

    • options

      public Expression options()

    • resolveParams

      protected Expression.TypeResolution resolveParams()
      Description copied from class: FullTextFunction
      Resolves the type for the function parameters, as part of the type resolution for the function
      Overrides:
      resolveParams in class FullTextFunction
      Returns:
      type resolution for the function parameters

    • resolveField

      protected Expression.TypeResolution resolveField()
      Resolves and validates the field parameter type.

    • resolveQuery

      protected Expression.TypeResolution resolveQuery()
      Resolves and validates the query parameter type.

    • resolveOptions

      protected Expression.TypeResolution resolveOptions()
      Resolves and validates the options parameter. Subclasses can override to add custom validation.

    • queryAsObject

      protected Object queryAsObject()
      Converts the query expression to an Object suitable for the Lucene query. Handles common conversions for BytesRef, UNSIGNED_LONG, DATETIME, and DATE_NANOS.

    • fieldAsFieldAttribute

      protected FieldAttribute fieldAsFieldAttribute()
      Returns the field as a FieldAttribute for use in query translation

    • foldable

      public boolean foldable()
      Overrides:
      foldable in class Expression

    • fold

      public Object fold(FoldContext ctx)
      Overrides:
      fold in class Expression

    • nullable

      public Nullability nullable()
      Overrides:
      nullable in class FullTextFunction

    • postAnalysisPlanVerification

      public BiConsumer<LogicalPlan,Failures> postAnalysisPlanVerification()
      Description copied from interface: PostAnalysisPlanVerificationAware
      Allows the implementer to return a consumer that will perform self-validation in the context of the tree structure the implementer is part of. This usually involves checking the type and configuration of the children or that of the parent.

      It is often more useful to perform the checks as extended as it makes sense, over stopping at the first failure. This will allow the author to progress faster to a correct query.

      Example: a GroupingFunction instance, which models a function to group documents to aggregate over, can only be used in the context of the STATS command, modeled by the Aggregate class. This is how this verification is performed: 

           
      @Override
      public BiConsumer<LogicalPlan, Failures> postAnalysisPlanVerification() {
          return (p, failures) -> {
              if (p instanceof Aggregate == false) {
                  p.forEachExpression(
                      GroupingFunction.class,
                      gf -> failures.add(fail(gf, "cannot use grouping function [{}] outside of a STATS command", gf.sourceText()))
                  );
              }
          };
      }
      Specified by:
      postAnalysisPlanVerification in interface PostAnalysisPlanVerificationAware
      Overrides:
      postAnalysisPlanVerification in class FullTextFunction
      Returns:
      a consumer that will receive a tree to check and an accumulator of failures found during inspection.

    • postOptimizationPlanVerification

      public BiConsumer<LogicalPlan,Failures> postOptimizationPlanVerification()
      Description copied from interface: PostOptimizationPlanVerificationAware
      Validates the implementing expression - discovered failures are reported to the given Failures class.

      Example: the SORT command, OrderBy, can only be executed currently if it can be associated with a LIMIT Limit and together transformed into a TopN (which is executable). The replacement of the LIMIT+SORT into a TopN is done at the end of the optimization phase. This means that any SORT still existing in the plan post optimization is an error. However, there can be a LIMIT in the plan, but separated from the SORT by an INLINE STATS; in this case, the LIMIT cannot be pushed down near the SORT. To inform the user how they need to modify the query so it can be run, we implement this: 

           

      @Override
      public BiConsumer<LogicalPlan, Failures> postOptimizationPlanVerification() {
          return (p, failures) -> {
              if (p instanceof InlineJoin inlineJoin) {
                  inlineJoin.forEachUp(OrderBy.class, orderBy -> {
                      failures.add(
                          fail(
                              inlineJoin,
                              "unbounded SORT [{}] not supported before INLINE STATS [{}], move the sort after the INLINE STATS",
                              orderBy.sourceText(),
                              inlineJoin.sourceText()
                          )
                      );
                  });
              } else if (p instanceof OrderBy) {
                  failures.add(fail(p, "Unbounded SORT not supported yet [{}] please add a LIMIT", p.sourceText()));
              }
          };
      }

      If we didn't need to check the structure of the plan, it would have sufficed to implement the PostOptimizationVerificationAware interface, which would simply check if there is an instance of OrderBy in the plan.

      Specified by:
      postOptimizationPlanVerification in interface PostOptimizationPlanVerificationAware
      Returns:
      a consumer that will receive a tree to check and an accumulator of failures found during inspection.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class FullTextFunction

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class FullTextFunction

    • getFieldDataTypes

      protected abstract Set<DataType> getFieldDataTypes()
      Returns the set of allowed data types for the field parameter. Each subclass defines which field types it supports.

    • getQueryDataTypes

      protected abstract Set<DataType> getQueryDataTypes()
      Returns the set of allowed data types for the query parameter. Each subclass defines which query types it supports.

    • getAllowedOptions

      protected abstract Map<String,DataType> getAllowedOptions()
      Returns the allowed options map for this function. Keys are option names, values are the expected data types.

    • expectedFieldTypesString

      protected String expectedFieldTypesString()
      Returns a human-readable string listing the expected field types. Used in error messages.

    • expectedQueryTypesString

      protected String expectedQueryTypesString()
      Returns a human-readable string listing the expected query types. Used in error messages.