RexProgram (Calcite Core 1.2.0-incubating 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 StringBuffer does 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, RexLocalRef condition, RelDataType outputRowType)` Creates a program.

Method Summary

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, RexNode conditionExpr, List<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, RexNode conditionExpr, RelDataType outputRowType, RexBuilder rexBuilder)` Creates a program which calculates projections and filters rows based upon a condition.
`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, computes a list of collations.
`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.
`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.
`RexLocalRef`	`getCondition()` Returns the field reference of this program's filter condition, or null if there is no condition.
`HashSet<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.
`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(boolean fail, 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(boolean fail)` Checks that this program is valid.
`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,
          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
```
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,
                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,
                List<? extends RexNode> projectExprs,
                RexNode conditionExpr,
                List<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 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(boolean fail)
```
    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:
    fail - Whether to fail
    
    Returns:
    Whether the program is valid
    
    Throws:
    
    AssertionError - if program is invalid and fail is true and assertions are enabled
  - 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 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.
  - 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, computes a list of collations. The result is mutable.
  - 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 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
```
public Permutation getPermutation()
```
    Returns a permutation, if this program is a permutation, otherwise null.
  - getCorrelVariableNames
```
public HashSet<String> getCorrelVariableNames()
```
    Returns the set of correlation variables used (read) by this program.
    
    Returns:
    set of correlation variable names
  - isNormalized
```
public boolean isNormalized(boolean fail,
                   RexBuilder rexBuilder)
```
    Returns whether this program is in canonical form.
    
    Parameters:
    fail - Whether to throw an assertion error if not in canonical form
    rexBuilder - Rex builder
    
    Returns:
    whether in canonical form

Class RexProgram

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RexProgram

Method Detail

getExprList

getProjectList

getNamedProjects

getCondition

create

create

toString

explainCalc

collectExplainTerms

collectExplainTerms

getExprCount

createIdentity

createIdentity

getInputRowType

containsAggs

getOutputRowType

isValid

isNull

expandLocalRef

split

getCollations

deduceCollations

projectsIdentity

projectsOnlyIdentity

isTrivial

getReferenceCounts

isConstant

gatherExpr

getSourceField

isPermutation

getPermutation

getCorrelVariableNames

isNormalized