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

Class Categorize

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.grouping.GroupingFunction
org.elasticsearch.xpack.esql.expression.function.grouping.GroupingFunction.NonEvaluatableGroupingFunction
org.elasticsearch.xpack.esql.expression.function.grouping.Categorize
All Implemented Interfaces:
NamedWriteable, Writeable, PostAnalysisPlanVerificationAware, Resolvable, OptionalArgument, LicenseAware
public class Categorize extends GroupingFunction.NonEvaluatableGroupingFunction implements OptionalArgument, LicenseAware
Categorizes text messages.

This function has no evaluators, as it works like an aggregation (Accumulates values, stores intermediate states, etc).

For the implementation, see CategorizeBlockHash

  • Field Details

  • Constructor Details

  • Method Details

    • writeTo

      public void writeTo(StreamOutput out) throws IOException
      Specified by:
      writeTo in interface Writeable
      Throws:
      IOException

    • getWriteableName

      public String getWriteableName()
      Specified by:
      getWriteableName in interface NamedWriteable

    • foldable

      public boolean foldable()
      Description copied from class: Expression
      Whether the expression can be evaluated statically, aka "folded", or not.
      Overrides:
      foldable in class Expression

    • nullable

      public Nullability nullable()
      Overrides:
      nullable in class Function

    • resolveType

      protected Expression.TypeResolution resolveType()
      Description copied from class: Expression
      The implementation of Expression.typeResolved(), which is just a caching wrapper around this method. See it's javadoc for what this method should return.

      Implementations will rarely interact with the Expression.TypeResolution class directly, instead usually calling the utility methods on TypeResolutions.

      Implementations should fail if Expression.childrenResolved() returns false.

      Overrides:
      resolveType in class Expression

    • categorizeDef

      public BlockHash.CategorizeDef categorizeDef()

    • dataType

      public DataType dataType()
      Description copied from class: Expression
      The DataType returned by executing the tree rooted at this expression. If Expression.typeResolved() returns an error then the behavior of this method is undefined. It may return a valid type. Or it may throw an exception. Or it may return a totally nonsensical type.
      Specified by:
      dataType in class Expression

    • replaceChildren

      public Categorize replaceChildren(List<Expression> newChildren)
      Specified by:
      replaceChildren in class Node<Expression>

    • info

      protected NodeInfo<? extends Expression> info()
      Description copied from class: Node
      Normally, you want to use one of the static create methods to implement this.

      For QueryPlans, it is very important that the properties contain all of the expressions and references relevant to this node, and that all the properties are used in the provided constructor; otherwise query plan transformations like QueryPlan#transformExpressionsOnly(Function) will not have an effect.

      Specified by:
      info in class Node<Expression>

    • field

      public Expression field()

    • toString

      public String toString()
      Overrides:
      toString in class Expression

    • licenseCheck

      public boolean licenseCheck(XPackLicenseState state)
      Description copied from interface: LicenseAware
      Return true if the implementer can be executed under the provided XPackLicenseState, otherwise false.
      Specified by:
      licenseCheck in interface LicenseAware

    • 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 GroupingFunction
      Returns:
      a consumer that will receive a tree to check and an accumulator of failures found during inspection.