Package org.apache.calcite.rex

Class RexProgram

  • public class RexProgram
extends java.lang.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 StringBuffer has to String.

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

    See Also:
    RexProgramBuilder

    • Field Detail

      • exprs

        private final java.util.List<RexNode> exprs
        First stage of expression evaluation. The expressions in this array can refer to inputs (using input ordinal #0) or previous expressions in the array (using input ordinal #1).

      • projects

        private final java.util.List<RexLocalRef> projects
        With condition, the second stage of expression evaluation.

      • condition

        private final RexLocalRef condition
        The optional condition. If null, the calculator does not filter rows.

      • outputRowType

        private final RelDataType outputRowType

      • refCounts

        private int[] refCounts
        Reference counts for each expression, computed on demand.

    • Constructor Detail

      • RexProgram

        public RexProgram​(RelDataType inputRowType,
                  java.util.List<? extends RexNode> exprs,
                  java.util.List<RexLocalRef> projects,
                  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 Detail

      • getExprList

        public java.util.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 java.util.List<RexLocalRef> getProjectList()
        Returns an array of references to the expressions which this program is to project. Never null, may be empty.

      • getNamedProjects

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

      • getCondition

        public 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,
                                java.util.List<? extends RexNode> projectExprs,
                                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,
                                java.util.List<? extends RexNode> projectExprs,
                                RexNode conditionExpr,
                                java.util.List<java.lang.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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.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​(java.lang.String prefix,
                                     RelWriter pw)

      • collectExplainTerms

        public RelWriter collectExplainTerms​(java.lang.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

      • countTrivial

        private static int countTrivial​(java.util.List<RexLocalRef> refs)
        Returns the number of expressions at the front of an array which are simply projections of the same field.
        Parameters:
        refs - References

      • 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​(Litmus litmus,
                       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

      • 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 java.util.List<RelCollation> getCollations​(java.util.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​(java.util.List<RelCollation> outputCollations,
                                    int sourceCount,
                                    java.util.List<RexLocalRef> refs,
                                    java.util.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.

      • 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

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

      • getCorrelVariableNames

        public java.util.Set<java.lang.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,
                            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.