RexProgram (Apache Calcite API)

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:

RexProgramBuilder

Constructor Summary

Constructors
Constructor and Description
`RexProgram(RelDataType inputRowType, List<? extends RexNode> exprs, List<RexLocalRef> projects, @Nullable RexLocalRef condition, RelDataType outputRowType)` Creates a program.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`RelWriter`	`collectExplainTerms(String prefix, RelWriter pw)`
`RelWriter`	`collectExplainTerms(String prefix, RelWriter pw, SqlExplainLevel level)` Collects the expressions in this program into a list of terms and values.
`boolean`	`containsAggs()` Returns whether this program contains windowed aggregate functions.
`static RexProgram`	`create(RelDataType inputRowType, List<? extends RexNode> projectExprs, @Nullable RexNode conditionExpr, @Nullable List<? extends String> fieldNames, RexBuilder rexBuilder)` Creates a program which calculates projections and filters rows based upon a condition.
`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.
`static RexProgram`	`create(RelInput input)` Create a program from serialized output.
`static RexProgram`	`createIdentity(RelDataType rowType)` Creates the identity program.
`static RexProgram`	`createIdentity(RelDataType rowType, RelDataType outputRowType)` Creates a program that projects its input fields but with possibly different names for the output fields.
`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.
`List<RexNode>`	`expandList(List<? extends RexNode> nodes)` Expands a list of expressions that may contain `RexLocalRef`s.
`RexNode`	`expandLocalRef(RexLocalRef ref)` Fully expands a RexLocalRef back into a pure RexNode tree containing no RexLocalRefs (reversing the effect of common subexpression elimination).
`RelWriter`	`explainCalc(RelWriter pw)` Writes an explanation of the expressions in this program to a plan writer.
`@Nullable RexNode`	`gatherExpr(RexNode expr)`
`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.
`@Nullable RexLocalRef`	`getCondition()` Returns the field reference of this program's filter condition, or null if there is no condition.
`Set<String>`	`getCorrelVariableNames()` Returns the set of correlation variables used (read) by this program.
`int`	`getExprCount()` Returns the number of expressions in this program.
`List<RexNode>`	`getExprList()` Returns the common sub-expressions of this program.
`RelDataType`	`getInputRowType()` Returns the type of the input row to the program.
`List<Pair<RexLocalRef,String>>`	`getNamedProjects()` Returns a list of project expressions and their field names.
`RelDataType`	`getOutputRowType()` Returns the type of the output row from this program.
`Mappings.TargetMapping`	`getPartialMapping(int inputFieldCount)` Returns a partial mapping of a set of project expressions.
`@Nullable Permutation`	`getPermutation()` Returns a permutation, if this program is a permutation, otherwise null.
`List<RexLocalRef>`	`getProjectList()` Returns an array of references to the expressions which this program is to project.
`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.
`int`	`getSourceField(int outputOrdinal)` Returns the input field that an output field is populated from, or -1 if it is populated from an expression.
`boolean`	`isConstant(RexNode ref)` Returns whether an expression is constant.
`boolean`	`isNormalized(Litmus litmus, RexBuilder rexBuilder)` Returns whether this program is in canonical form.
`boolean`	`isNull(RexNode expr)` Returns whether an expression always evaluates to null.
`boolean`	`isPermutation()` Returns whether this program is a permutation of its inputs.
`boolean`	`isTrivial()` Returns whether this program returns its input exactly.
`boolean`	`isValid(Litmus litmus, RelNode.Context context)` Checks that this program is valid.
`RexProgram`	`normalize(RexBuilder rexBuilder, boolean simplify)` Deprecated.
`RexProgram`	`normalize(RexBuilder rexBuilder, @Nullable RexSimplify simplify)` Creates a simplified/normalized copy of this program.
`boolean`	`projectsIdentity(boolean fail)` Returns whether the fields on the leading edge of the project list are the input fields.
`boolean`	`projectsOnlyIdentity()` Returns whether this program projects precisely its input fields.
`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.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - 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 Detail
  - 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 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,
                       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

Class RexProgram

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RexProgram

Method Detail

getExprList

getProjectList

getNamedProjects

getCondition

create

create

create

toString

explainCalc

collectExplainTerms

collectExplainTerms

getExprCount

createIdentity

createIdentity

getInputRowType

containsAggs

getOutputRowType

isValid

isNull

expandLocalRef

expandList

split

getCollations

deduceCollations

projectsIdentity

projectsOnlyIdentity

isTrivial

getReferenceCounts

isConstant

gatherExpr

getSourceField

isPermutation

getPermutation

getCorrelVariableNames

isNormalized

normalize

normalize

getPartialMapping