Package org.apache.druid.math.expr

Interface Expr

All Superinterfaces:

Cacheable

All Known Subinterfaces:

ExprMacroTable.ExprMacroFunctionExpr

All Known Implementing Classes:

ExprMacroTable.BaseMacroFunctionExpr, ExprMacroTable.BaseScalarMacroFunctionExpr, 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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Expr.BindingAnalysis	Information about the context in which IdentifierExpr are used in a greater Expr, listing the 'free variables' (total set of required input columns or values) and distinguishing between which identifiers are used as scalar inputs and which are used as array inputs.
static interface	Expr.InputBindingInspector	Mechanism to supply input types for the bindings which will back IdentifierExpr, to use in the aid of inferring the output type of an expression with getOutputType(org.apache.druid.math.expr.Expr.InputBindingInspector).
static interface	Expr.ObjectBinding	Mechanism to supply values to back IdentifierExpr during expression evaluation
static interface	Expr.Shuttle	Mechanism to rewrite an Expr, implementing a Expr.Shuttle allows visiting all children of an Expr, and replacing them as desired.
static interface	Expr.VectorInputBinding	Mechanism to supply batches of input values to a ExprVectorProcessor for optimized processing.
static interface	Expr.VectorInputBindingInspector	Expr.InputBindingInspector + vectorizations stuff for asVectorProcessor(org.apache.druid.math.expr.Expr.VectorInputBindingInspector)

Field Summary

Fields

Modifier and Type	Field	Description
static com.google.common.base.Joiner	ARG_JOINER
static String	NULL_LITERAL

Method Summary

Modifier and Type	Method	Description
Expr.BindingAnalysis	analyzeInputs()	Examine the usage of IdentifierExpr children of an Expr, constructing a Expr.BindingAnalysis
default ColumnIndexSupplier	asColumnIndexSupplier(ColumnIndexSelector columnIndexSelector, ColumnType outputType)
default Expr	asSingleThreaded(Expr.InputBindingInspector inspector)	Possibly convert the Expr into an optimized, possibly not thread-safe Expr.
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.
default boolean	canVectorize(Expr.InputBindingInspector inspector)	Check if an expression can be 'vectorized', for a given set of inputs.
default void	decorateCacheKeyBuilder(CacheKeyBuilder builder)	Decorates the CacheKeyBuilder for the default implementation of getCacheKey().
ExprEval	eval(Expr.ObjectBinding bindings)	Evaluate the Expr with the bindings which supply IdentifierExpr with their values, producing an ExprEval with the result.
default String	getBindingIfIdentifier()	Returns the string key to use to get a value from Expr.ObjectBinding of an IdentifierExpr, else null.
default byte[]	getCacheKey()	Get a byte array used as a cache key.
default org.apache.druid.math.expr.IdentifierExpr	getIdentifierExprIfIdentifierExpr()	Returns an IdentifierExpr if it is one, else null
default String	getIdentifierIfIdentifier()	Returns the string identifier of an IdentifierExpr, else null.
default Object	getLiteralValue()	Returns the value of expr if expr is a literal, or throws an exception otherwise.
default ExpressionType	getOutputType(Expr.InputBindingInspector inspector)	Given an Expr.InputBindingInspector, compute what the output ExpressionType will be for this expression.
default boolean	isIdentifier()
default boolean	isLiteral()	Indicates expression is a constant whose literal value can be extracted by getLiteralValue(), making evaluating with arguments and bindings unecessary
default boolean	isNullLiteral()
static Expr	singleThreaded(Expr expr, Expr.InputBindingInspector inspector)	Returns the single-threaded version of the given expression tree.
String	stringify()	Convert the Expr back into parseable string that when parsed with Parser.parse(String, ExprMacroTable) will produce an equivalent Expr.
Expr	visit(Expr.Shuttle shuttle)	Programatically rewrite the Expr tree with a Expr.Shuttle.

Field Detail

NULL_LITERAL

static final String NULL_LITERAL

See Also:

Constant Field Values

ARG_JOINER

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

Method Detail

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).

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.

Parameters:

inspector -

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)

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:

a cache key

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.