Package org.apache.calcite.rex

Class RexProgram

java.lang.Object
org.apache.calcite.rex.RexProgram
public class RexProgram extends Object
A collection of expressions which read inputs, compute output expressions, and optionally use a condition to filter rows.

Programs are immutable. It may help to use a RexProgramBuilder, which has the same relationship to RexProgram as StringBuilder has to String.

A program can contain aggregate functions. If it does, the arguments to each aggregate function must be an RexInputRef.

See Also:

  • Constructor Details

    • RexProgram

      public RexProgram(RelDataType inputRowType, List<? extends RexNode> exprs, List<RexLocalRef> projects, @Nullable RexLocalRef condition, RelDataType outputRowType)
      Creates a program.

      The expressions must be valid: they must not contain common expressions, forward references, or non-trivial aggregates.

      Parameters:
      inputRowType - Input row type
      exprs - Common expressions
      projects - Projection expressions
      condition - Condition expression. If null, calculator does not filter rows
      outputRowType - Description of the row produced by the program

  • Method Details

    • getExprList

      public List<RexNode> getExprList()
      Returns the common sub-expressions of this program.

      The list is never null but may be empty; each the expression in the list is not null; and no further reduction into smaller common sub-expressions is possible.

    • getProjectList

      public List<RexLocalRef> getProjectList()
      Returns an array of references to the expressions which this program is to project. Never null, may be empty.

    • getNamedProjects

      public List<Pair<RexLocalRef,String>> getNamedProjects()
      Returns a list of project expressions and their field names.

    • getCondition

      @Pure public @Nullable RexLocalRef getCondition()
      Returns the field reference of this program's filter condition, or null if there is no condition.

    • create

      public static RexProgram create(RelDataType inputRowType, List<? extends RexNode> projectExprs, @Nullable RexNode conditionExpr, RelDataType outputRowType, RexBuilder rexBuilder)
      Creates a program which calculates projections and filters rows based upon a condition. Does not attempt to eliminate common sub-expressions.
      Parameters:
      projectExprs - Project expressions
      conditionExpr - Condition on which to filter rows, or null if rows are not to be filtered
      outputRowType - Output row type
      rexBuilder - Builder of rex expressions
      Returns:
      A program

    • create

      public static RexProgram create(RelDataType inputRowType, List<? extends RexNode> projectExprs, @Nullable RexNode conditionExpr, @Nullable List<? extends @Nullable String> fieldNames, RexBuilder rexBuilder)
      Creates a program which calculates projections and filters rows based upon a condition. Does not attempt to eliminate common sub-expressions.
      Parameters:
      projectExprs - Project expressions
      conditionExpr - Condition on which to filter rows, or null if rows are not to be filtered
      fieldNames - Names of projected fields
      rexBuilder - Builder of rex expressions
      Returns:
      A program

    • create

      public static RexProgram create(RelInput input)
      Create a program from serialized output. In this case, the input is mainly from the output json string of RelJsonWriter

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • explainCalc

      public RelWriter explainCalc(RelWriter pw)
      Writes an explanation of the expressions in this program to a plan writer.
      Parameters:
      pw - Plan writer

    • collectExplainTerms

      public RelWriter collectExplainTerms(String prefix, RelWriter pw)

    • collectExplainTerms

      public RelWriter collectExplainTerms(String prefix, RelWriter pw, SqlExplainLevel level)
      Collects the expressions in this program into a list of terms and values.
      Parameters:
      prefix - Prefix for term names, usually the empty string, but useful if a relational expression contains more than one program
      pw - Plan writer

    • getExprCount

      public int getExprCount()
      Returns the number of expressions in this program.

    • createIdentity

      public static RexProgram createIdentity(RelDataType rowType)
      Creates the identity program.

    • createIdentity

      public static RexProgram createIdentity(RelDataType rowType, RelDataType outputRowType)
      Creates a program that projects its input fields but with possibly different names for the output fields.

    • getInputRowType

      public RelDataType getInputRowType()
      Returns the type of the input row to the program.
      Returns:
      input row type

    • containsAggs

      public boolean containsAggs()
      Returns whether this program contains windowed aggregate functions.
      Returns:
      whether this program contains windowed aggregate functions

    • getOutputRowType

      public RelDataType getOutputRowType()
      Returns the type of the output row from this program.
      Returns:
      output row type

    • isValid

      public boolean isValid(@UnknownInitialization RexProgram this, Litmus litmus, @Nullable RelNode.Context context)
      Checks that this program is valid.

      If fail is true, executes assert false, so will throw an AssertionError if assertions are enabled. If fail is false, merely returns whether the program is valid.

      Parameters:
      litmus - What to do if an error is detected
      context - Context of enclosing RelNode, for validity checking, or null if not known
      Returns:
      Whether the program is valid

    • isNull

      public boolean isNull(RexNode expr)
      Returns whether an expression always evaluates to null.

      Like RexUtil.isNull(RexNode), null literals are null, and casts of null literals are null. But this method also regards references to null expressions as null.

      Parameters:
      expr - Expression
      Returns:
      Whether expression always evaluates to null

    • expandLocalRef

      public RexNode expandLocalRef(RexLocalRef ref)
      Fully expands a RexLocalRef back into a pure RexNode tree containing no RexLocalRefs (reversing the effect of common subexpression elimination). For example, program.expandLocalRef(program.getCondition()) will return the expansion of a program's condition.
      Parameters:
      ref - a RexLocalRef from this program
      Returns:
      expanded form

    • expandList

      public List<RexNode> expandList(List<? extends RexNode> nodes)
      Expands a list of expressions that may contain RexLocalRefs.

    • split

      public Pair<com.google.common.collect.ImmutableList<RexNode>,com.google.common.collect.ImmutableList<RexNode>> split()
      Splits this program into a list of project expressions and a list of filter expressions.

      Neither list is null. The filters are evaluated first.

    • getCollations

      public List<RelCollation> getCollations(List<RelCollation> inputCollations)
      Given a list of collations which hold for the input to this program, returns a list of collations which hold for its output. The result is mutable and sorted.

    • deduceCollations

      public static void deduceCollations(List<RelCollation> outputCollations, int sourceCount, List<RexLocalRef> refs, List<RelCollation> inputCollations)
      Given a list of expressions and a description of which are ordered, populates a list of collations, sorted in natural order.

    • projectsIdentity

      public boolean projectsIdentity(boolean fail)
      Returns whether the fields on the leading edge of the project list are the input fields.
      Parameters:
      fail - Whether to throw an assert failure if does not project identity

    • projectsOnlyIdentity

      public boolean projectsOnlyIdentity()
      Returns whether this program projects precisely its input fields. It may or may not apply a condition.

    • isTrivial

      public boolean isTrivial()
      Returns whether this program returns its input exactly.

      This is a stronger condition than projectsIdentity(boolean).

    • getReferenceCounts

      public int[] getReferenceCounts()
      Gets reference counts for each expression in the program, where the references are detected from later expressions in the same program, as well as the project list and condition. Expressions with references counts greater than 1 are true common sub-expressions.
      Returns:
      array of reference counts; the ith element in the returned array is the number of references to getExprList()[i]

    • isConstant

      public boolean isConstant(RexNode ref)
      Returns whether an expression is constant.

    • gatherExpr

      public @Nullable RexNode gatherExpr(RexNode expr)

    • getSourceField

      public int getSourceField(int outputOrdinal)
      Returns the input field that an output field is populated from, or -1 if it is populated from an expression.

    • isPermutation

      public boolean isPermutation()
      Returns whether this program is a permutation of its inputs.

    • getPermutation

      @CheckReturnValue public @Nullable Permutation getPermutation()
      Returns a permutation, if this program is a permutation, otherwise null.

    • getCorrelVariableNames

      public Set<String> getCorrelVariableNames()
      Returns the set of correlation variables used (read) by this program.
      Returns:
      set of correlation variable names

    • isNormalized

      public boolean isNormalized(Litmus litmus, RexBuilder rexBuilder)
      Returns whether this program is in canonical form.
      Parameters:
      litmus - What to do if an error is detected (program is not in canonical form)
      rexBuilder - Rex builder
      Returns:
      whether in canonical form

    • normalize

      public RexProgram normalize(RexBuilder rexBuilder, @Nullable RexSimplify simplify)
      Creates a simplified/normalized copy of this program.
      Parameters:
      rexBuilder - Rex builder
      simplify - Simplifier to simplify (in addition to normalizing), or null to not simplify
      Returns:
      Normalized program

    • normalize

      @Deprecated public RexProgram normalize(RexBuilder rexBuilder, boolean simplify)
      Deprecated.

    • getPartialMapping

      public Mappings.TargetMapping getPartialMapping(int inputFieldCount)
      Returns a partial mapping of a set of project expressions.

      The mapping is an inverse function. Every target has a source field, but a source might have 0, 1 or more targets. Project expressions that do not consist of a mapping are ignored.

      Parameters:
      inputFieldCount - Number of input fields
      Returns:
      Mapping of a set of project expressions, never null