org.eigenbase.rex
Class RexProgram

java.lang.Object
  org.eigenbase.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.

Since:

Aug 18, 2005

Version:

$Id: //open/dev/farrago/src/org/eigenbase/rex/RexProgram.java#23 $

Author:

jhyde

See Also:

RexProgramBuilder

Nested Class Summary

(package private) static class	RexProgram.Checker Visitor which walks over a program and checks validity.
private class	RexProgram.ConstantFinder Walks over an expression and determines whether it is constant.
private class	RexProgram.ExpansionShuttle A RexShuttle used in the implementation of expandLocalRef(org.eigenbase.rex.RexLocalRef).
private class	RexProgram.Marshaller Given an expression in a program, creates a clone of the expression with sub-expressions (represented by RexLocalRefs) fully expanded.
private class	RexProgram.ReferenceCounter Visitor which marks which expressions are used.

Field Summary

private boolean	aggs Whether this program contains aggregates.
private RexLocalRef	condition The optional condition.
private List<RexNode>	exprReadOnlyList
private RexNode[]	exprs First stage of expression evaluation.
private RelDataType	inputRowType
private RelDataType	outputRowType
private List<RexLocalRef>	projectReadOnlyList
private RexLocalRef[]	projects With condition, the second stage of expression evaluation.
private int[]	refCounts Reference counts for each expression, computed on demand.

Constructor Summary

RexProgram(RelDataType inputRowType, List<RexNode> exprList, List<RexLocalRef> projectRefList, RexLocalRef condition, RelDataType outputRowType)
Creates a program from lists of expressions.

RexProgram(RelDataType inputRowType, RexNode[] exprs, RexLocalRef[] projects, RexLocalRef condition, RelDataType outputRowType)
Creates a program.

Method Summary

static void	apply(RexVisitor<Void> visitor, RexNode[] exprs, RexNode expr) Applies a visitor to an array of expressions and, if specified, a single expression.
void	collectExplainTerms(String prefix, List<String> termList, List<Object> valueList)
void	collectExplainTerms(String prefix, List<String> termList, List<Object> valueList, 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
RexProgram	copy() Creates a copy of this program.
private static int	countTrivial(RexLocalRef[] refs) Returns the number of expressions at the front of an array which are simply projections of the same field.
static RexProgram	create(RelDataType inputRowType, 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 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).
void	explainCalc(RelNode rel, RelOptPlanWriter pw) Writes an explanation of the expressions in this program to a plan writer.
RexNode[]	flatten() Deprecated. Not used
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.
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	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.
void	setAggs(boolean aggs)
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

exprs

private final 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 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.

inputRowType

private final RelDataType inputRowType

aggs

private boolean aggs

Whether this program contains aggregates. TODO: obsolete this

outputRowType

private final RelDataType outputRowType

projectReadOnlyList

private final List<RexLocalRef> projectReadOnlyList

exprReadOnlyList

private final List<RexNode> exprReadOnlyList

refCounts

private int[] refCounts

Reference counts for each expression, computed on demand.

Constructor Detail

RexProgram

public RexProgram(RelDataType inputRowType,
                  RexNode[] exprs,
                  RexLocalRef[] projects,
                  RexLocalRef condition,
                  RelDataType outputRowType)

Creates a program.

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

"Precondition:"

!containCommonExprs(exprs), !containForwardRefs(exprs), !containNonTrivialAggs(exprs)

RexProgram

public RexProgram(RelDataType inputRowType,
                  List<RexNode> exprList,
                  List<RexLocalRef> projectRefList,
                  RexLocalRef condition,
                  RelDataType outputRowType)

Creates a program from lists of expressions.

Parameters:

inputRowType - Input row type

exprList - List of common expressions

projectRefList - List of projection expressions

condition - Condition expression. If null, calculator does not filter rows

outputRowType - Description of the row produced by the program

"Precondition:"

!containCommonExprs(exprList), !containForwardRefs(exprList), !containNonTrivialAggs(exprList)

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 subexpressions is possible.

"Postcondition:"

return != null, !containCommonExprs(exprs)

getProjectList

public List<RexLocalRef> getProjectList()

Returns an array of references to the expressions which this program is to project. Never null, may be empty.

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

flatten

public RexNode[] flatten()

Deprecated. Not used

Helper method for 'explain' functionality. Creates a list of all expressions (common, project, and condition)

toString

public String toString()

Overrides:

toString in class Object

explainCalc

public void explainCalc(RelNode rel,
                        RelOptPlanWriter pw)

Writes an explanation of the expressions in this program to a plan writer.

Parameters:

rel - Relational expression which owns this program

pw - Plan writer

collectExplainTerms

public void collectExplainTerms(String prefix,
                                List<String> termList,
                                List<Object> valueList)

collectExplainTerms

public void collectExplainTerms(String prefix,
                                List<String> termList,
                                List<Object> valueList,
                                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

termList - Output list of terms

valueList - Output list of expressions

countTrivial

private static int countTrivial(RexLocalRef[] refs)

Returns the number of expressions at the front of an array which are simply projections of the same field.

getExprCount

public int getExprCount()

Returns the number of expressions in this program.

copy

public RexProgram copy()

Creates a copy of this program.

createIdentity

public static RexProgram createIdentity(RelDataType rowType)

Creates the identity program.

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

setAggs

public void setAggs(boolean aggs)

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

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

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

Returns:

array of reference counts; the ith element in the returned array is the number of references to getExprList()[i]

apply

public static void apply(RexVisitor<Void> visitor,
                         RexNode[] exprs,
                         RexNode expr)

Applies a visitor to an array of expressions and, if specified, a single expression.

Parameters:

visitor - Visitor

exprs - Array of expressions

expr - Single expression, may be null

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