Package org.apache.druid.math.expr

Interface Expr

All Superinterfaces:
Cacheable
All Known Subinterfaces:
ExprMacroTable.ExprMacroFunctionExpr
All Known Implementing Classes:
ExprMacroTable.BaseMacroFunctionExpr, ExprMacroTable.BaseScalarMacroFunctionExpr, LambdaExpr, TimestampExtractExprMacro.TimestampExtractDynamicExpr, TimestampExtractExprMacro.TimestampExtractExpr, TimestampFloorExprMacro.TimestampFloorDynamicExpr, TimestampFloorExprMacro.TimestampFloorExpr
@SubclassesMustOverrideEqualsAndHashCode public interface Expr extends Cacheable
Base interface of Druid expression language abstract syntax tree nodes. All Expr implementations are immutable.

  • Field Details

    • NULL_LITERAL

      static final String NULL_LITERAL
      See Also:

    • ARG_JOINER

      static final com.google.common.base.Joiner ARG_JOINER

  • Method Details

    • isLiteral

      default boolean isLiteral()
      Indicates expression is a constant whose literal value can be extracted by getLiteralValue(), making evaluating with arguments and bindings unecessary

    • isNullLiteral

      default boolean isNullLiteral()

    • isIdentifier

      default boolean isIdentifier()

    • getLiteralValue

      @Nullable default Object getLiteralValue()
      Returns the value of expr if expr is a literal, or throws an exception otherwise.
      Returns:
      ConstantExpr's literal value
      Throws:
      IllegalStateException - if expr is not a literal

    • getIdentifierExprIfIdentifierExpr

      @Nullable default org.apache.druid.math.expr.IdentifierExpr getIdentifierExprIfIdentifierExpr()
      Returns an IdentifierExpr if it is one, else null

    • getIdentifierIfIdentifier

      @Nullable default String getIdentifierIfIdentifier()
      Returns the string identifier of an IdentifierExpr, else null. Use this method to analyze an Expr tree when trying to distinguish between different IdentifierExpr with the same IdentifierExpr.binding. Do NOT use this method to analyze the input binding (e.g. backing column name), use getBindingIfIdentifier() instead.

    • getBindingIfIdentifier

      @Nullable default String getBindingIfIdentifier()
      Returns the string key to use to get a value from Expr.ObjectBinding of an IdentifierExpr, else null. Use this method to analyze the inputs required to an Expr tree (e.g. backing column name).

    • rewriteBindings

      default Expr rewriteBindings(Map<String,String> rewriteMap)
      Replaces IdentifierExpr whose IdentifierExpr.binding are present as a key in the supplied map with the map value.

    • eval

      ExprEval eval(Expr.ObjectBinding bindings)
      Evaluate the Expr with the bindings which supply IdentifierExpr with their values, producing an ExprEval with the result.

    • stringify

      String stringify()
      Convert the Expr back into parseable string that when parsed with Parser.parse(String, ExprMacroTable) will produce an equivalent Expr.

    • visit

      Expr visit(Expr.Shuttle shuttle)
      Programatically rewrite the Expr tree with a Expr.Shuttle. Each Expr is responsible for ensuring the Expr.Shuttle can visit all of its Expr children, as well as updating its children Expr with the results from the Expr.Shuttle, before finally visiting an updated form of itself. When this Expr is the result of ExprMacroTable.ExprMacro.apply(java.util.List<org.apache.druid.math.expr.Expr>), all of the original arguments to the macro must be visited, including arguments that may have been "baked in" to this Expr.

    • analyzeInputs

      Expr.BindingAnalysis analyzeInputs()
      Examine the usage of IdentifierExpr children of an Expr, constructing a Expr.BindingAnalysis

    • getOutputType

      @Nullable default ExpressionType getOutputType(Expr.InputBindingInspector inspector)
      Given an Expr.InputBindingInspector, compute what the output ExpressionType will be for this expression. In the vectorized expression engine, if canVectorize(InputBindingInspector) returns true, a return value of null MUST ONLY indicate that the expression has all null inputs (non-existent columns) or null constants for the entire expression. Otherwise, all vectorizable expressions must produce an output type to correctly operate with the vectorized engine. Outside the context of vectorized expressions, a return value of null can also indicate that the given type information was not enough to resolve the output type, so the expression must be evaluated using default eval(org.apache.druid.math.expr.Expr.ObjectBinding) handling where types are only known after evaluation, through ExprEval.type(), such as transform expressions at ingestion time

    • canVectorize

      default boolean canVectorize(Expr.InputBindingInspector inspector)
      Check if an expression can be 'vectorized', for a given set of inputs. If this method returns true, asVectorProcessor(org.apache.druid.math.expr.Expr.VectorInputBindingInspector) is expected to produce a ExprVectorProcessor which can evaluate values in batches to use with vectorized query engines.

      Note that this method is insufficient by itself for determining to use vector processors, as it only checks whether the expression tree itself supports vectorization, but ignores schema-level constraints that ExpressionPlanner enforces.

      Most callers should instead prefer to use ExpressionPlanner.plan(ColumnInspector, Expr) and check for ExpressionPlan.Trait.VECTORIZABLE on the resulting plan.

    • asSingleThreaded

      default Expr asSingleThreaded(Expr.InputBindingInspector inspector)
      Possibly convert the Expr into an optimized, possibly not thread-safe Expr. Does not convert child Expr. Most callers should use singleThreaded(Expr, InputBindingInspector) to convert an entire tree, which delegates to this method to translate individual nodes.

    • asVectorProcessor

      default <T> ExprVectorProcessor<T> asVectorProcessor(Expr.VectorInputBindingInspector inspector)
      Builds a 'vectorized' expression processor, that can operate on batches of input values for use in vectorized query engines.
      Parameters:
      inspector -

    • asColumnIndexSupplier

      @Nullable default ColumnIndexSupplier asColumnIndexSupplier(ColumnIndexSelector columnIndexSelector, @Nullable ColumnType outputType)
      Allows an Expr to provide an ColumnIndexSupplier given access to the underlying ColumnIndexSupplier and ColumnHolder of the base table.

      The default implementation provides an index supplier if there is a single input column, and that column can provide DictionaryEncodedValueIndex, then the expression can provide DruidPredicateIndexes that apply a predicate.

      This method has the same null contract as ColumnIndexSelector.getIndexSupplier(String), and should only return null if the column is completely null and the Expr produces a null constant in the missing column case. Otherwise, if no index supplier can be provided, this method should return NoIndexesColumnIndexSupplier.getInstance().

    • asBitmapColumnIndex

      @Nullable default BitmapColumnIndex asBitmapColumnIndex(ColumnIndexSelector selector)
      Allows an Expr to be computed into a BitmapColumnIndex. The supplied ColumnIndexSelector provides access to underlying ColumnIndexSupplier and even ColumnHolder. Coupled with asColumnIndexSupplier(ColumnIndexSelector, ColumnType), which allows Expr to provide indexes of their own, it allows for a system of composing additional indexes on top of any base column structures.

      For example, BinEqExpr where one argument is a constant, can use the ValueIndexes if present of the non-constant arguments' index supplier.

      If this method returns null, it means that an index could not be produced for this Expr.

    • decorateCacheKeyBuilder

      default void decorateCacheKeyBuilder(CacheKeyBuilder builder)
      Decorates the CacheKeyBuilder for the default implementation of getCacheKey(). The default cache key implementation includes the output of stringify() and then uses a Expr.Shuttle to call this method on all children. The stringified representation is sufficient for most expressions, but for any which rely on external state that might change, this method allows the cache key to change when the state does, even if the expression itself is otherwise the same.

    • getCacheKey

      default byte[] getCacheKey()
      Description copied from interface: Cacheable
      Get a byte array used as a cache key.
      Specified by:
      getCacheKey in interface Cacheable
      Returns:
      bytes to be used as cache key - or null if this object should not be cached.

    • singleThreaded

      static Expr singleThreaded(Expr expr, Expr.InputBindingInspector inspector)
      Returns the single-threaded version of the given expression tree. Nested expressions in the subtree are also optimized.