org.eigenbase.rel
Interface RelNode

All Superinterfaces:

Cloneable

All Known Subinterfaces:

ConverterRel, FennelRel, JavaLoopRel, JavaRel, JavaSelfRel, RelStructuredTypeFlattener.SelfFlatteningRel, ResultSetRel

All Known Implementing Classes:

AbstractConverter, AbstractRelNode, AggregateRel, AggregateRelBase, CalcRel, CalcRelBase, CollectRel, ConverterRelImpl, CorrelatorRel, EmptyRel, FarragoIndexBuilderRel, FarragoJavaUdxRel, FennelAggRel, FennelBernoulliSamplingRel, FennelBufferRel, FennelCalcRel, FennelCartesianProductRel, FennelDoubleRel, FennelIdxWriteRel, FennelMergeRel, FennelMultipleRel, FennelMultiUseBufferRel, FennelNestedLoopJoinRel, FennelOptionalRel, FennelPullCollectRel, FennelPullCorrelatorRel, FennelPullUncollectRel, FennelRenameRel, FennelReshapeRel, FennelSingleRel, FennelSortRel, FennelTempIdxSearchRel, FennelToIteratorConverter, FennelValuesRel, FennelWindowRel, FilterRel, FilterRelBase, FlatFileFennelRel, FtrsIndexBuilderRel, FtrsIndexScanRel, FtrsIndexSearchRel, FtrsTableModificationRel, HepRelVertex, IntersectRel, IteratorToFennelConverter, IterCalcRel, IterConcatenateRel, IterOneRowRel, JdbcQuery, JoinRel, JoinRelBase, LcsIndexAggRel, LcsIndexBitOpRel, LcsIndexBuilderRel, LcsIndexIntersectRel, LcsIndexMergeRel, LcsIndexMinusRel, LcsIndexOnlyScanRel, LcsIndexSearchRel, LcsNormalizerRel, LcsRowScanRel, LcsRowScanRelBase, LcsSamplingRowScanRel, LcsTableAppendRel, LcsTableDeleteRel, LcsTableMergeRel, LhxAggRel, LhxJoinRel, MedAbstractFennelTableModRel, MedJdbcQueryRel, MedMdrClassExtentRel, MedMdrJoinRel, MedMockFennelRel, MedMockIterRel, MedMqlTableRel, MinusRel, MultiJoinRel, NoneConverterRel, OneRowRel, OneRowRelBase, ProjectRel, ProjectRelBase, RelSubset, ResultSetToFarragoIteratorConverter, SamplingRel, SemiJoinRel, SetOpRel, SingleRel, SortRel, TableAccessRel, TableAccessRelBase, TableFunctionRel, TableFunctionRelBase, TableModificationRel, TableModificationRelBase, UncollectRel, UnionRel, UnionRelBase, ValuesRel, ValuesRelBase, VolcanoPlannerTest.NoneLeafRel, VolcanoPlannerTest.NoneSingleRel, VolcanoPlannerTest.PhysLeafRel, VolcanoPlannerTest.PhysSingleRel, VolcanoPlannerTest.PhysToIteratorConverter, VolcanoPlannerTest.TestLeafRel, VolcanoPlannerTest.TestSingleRel, VolcanoPlannerTraitTest.AltTraitConverter, VolcanoPlannerTraitTest.IterSingleRel, VolcanoPlannerTraitTest.NoneLeafRel, VolcanoPlannerTraitTest.NoneSingleRel, VolcanoPlannerTraitTest.PhysLeafRel, VolcanoPlannerTraitTest.PhysToIteratorConverter, VolcanoPlannerTraitTest.TestLeafRel, VolcanoPlannerTraitTest.TestSingleRel, WindowedAggregateRel

public interface RelNode
extends Cloneable

A RelNode is a relational expression. It is NOT an Expression.

If this type of relational expression has some particular rules, it should implement the public static method AbstractRelNode.register(org.eigenbase.relopt.RelOptPlanner).

When a relational expression comes to be implemented, the system allocates a RelImplementor to manage the process. Every implementable relational expression has a RelTraitSet describing its physical attributes. The RelTraitSet always contains a CallingConvention describing how the expression passes data to its consuming relational expression, but may contain other traits, including some applied externally. Because traits can be applied externally, implementaitons of RelNode should never assume the size or contents of their trait set (beyond those traits configured by the RelNode itself).

For each calling-convention, there is a corresponding sub-interface of RelNode. For example, JavaRel has operations to manage the conversion to a graph of Java calling-convention, and it interacts with a JavaRelImplementor.

A relational expression is only required to implement its calling-convention's interface when it is actually implemented, that is, converted into a plan/program. This means that relational expressions which cannot be implemented, such as converters, are not required to implement their convention's interface.

Every relational expression must derive from AbstractRelNode. (Why have the RelNode interface, then? We need a root interface, because an interface can only derive from an interface.)

Since:

May 24, 2004

Version:

$Id: //open/dev/farrago/src/org/eigenbase/rel/RelNode.java#22 $

Author:

jhyde

Field Summary

static AbstractRelNode[]

emptyArray

Method Summary

void	childrenAccept(RelVisitor visitor) Interacts with the RelVisitor in a visitor pattern to traverse the tree of relational expressions.
RelNode	clone() Clones this RelNode.
void	collectVariablesSet(Set<String> variableSet) Collects variables set by this expression.
void	collectVariablesUsed(Set<String> variableSet) Collects variables known to be used by this expression or its descendants.
RelOptCost	computeSelfCost(RelOptPlanner planner) Returns the cost of this plan (not including children).
void	explain(RelOptPlanWriter pw)
RexNode[]	getChildExps() Returns an array of this relational expression's child expressions (not including the inputs returned by getInputs().
RelOptCluster	getCluster() Returns the cluster this relational expression belongs to.
List<RelCollation>	getCollationList() Returns a description of the physical ordering (or orderings) of this relational expression.
CallingConvention	getConvention() Return the CallingConvention trait from this RelNode's trait set.
String	getCorrelVariable() Returns the name of the variable which is to be implicitly set at runtime each time a row is returned from this relational expression; or null if there is no variable.
String	getDescription() Returns a string which describes the relational expression and, unlike getDigest(), also includes the identity.
String	getDigest() Returns a string which concisely describes the definition of this relational expression.
RelDataType	getExpectedInputRowType(int ordinalInParent) Returns the type of the rows expected for an input.
int	getId() Returns the ID of this relational expression, unique among all relational expressions created since the server was started.
RelNode	getInput(int i) Returns the ith input relational expression.
RelNode[]	getInputs() Returns an array of this relational expression's inputs.
String	getOrCreateCorrelVariable() Returns a variable with which to reference the current row of this relational expression as a correlating variable.
RelOptQuery	getQuery() Returns the sub-query this relational expression belongs to.
String	getRelTypeName() Returns the name of this relational expression's class, sans package name, for use in explain(org.eigenbase.relopt.RelOptPlanWriter).
double	getRows() Returns an estimate of the number of rows this relational expression will return.
RelDataType	getRowType() Returns the type of the rows returned by this relational expression.
RelOptTable	getTable() If this relational expression represents an access to a table, returns that table, otherwise returns null.
RelTraitSet	getTraits() Retrieves this RelNode's traits.
Set<String>	getVariablesStopped() Returns the names of variables which are set in this relational expression but also used and therefore not available to parents of this relational expression.
boolean	isAccessTo(RelOptTable table) Returns whether this relational expression is an access to table.
boolean	isDistinct() Returns whether the same value will not come out twice.
boolean	isValid(boolean fail) Returns whether this relational expression is valid.
void	onRegister(RelOptPlanner planner) Receives notification that this expression is about to be registered.
String	recomputeDigest() Computes the digest, assigns it, and returns it.
void	registerCorrelVariable(String correlVariable) Registers a correlation variable.
void	replaceInput(int ordinalInParent, RelNode p) Replaces the ordinalInParentth input.
void	setCorrelVariable(String correlVariable) Sets the name of the variable which is to be implicitly set at runtime each time a row is returned from this relational expression

Field Detail

emptyArray

static final AbstractRelNode[] emptyArray

Method Detail

isAccessTo

boolean isAccessTo(RelOptTable table)

Returns whether this relational expression is an access to table.

getChildExps

RexNode[] getChildExps()

Returns an array of this relational expression's child expressions (not including the inputs returned by getInputs(). If there are no child expressions, returns an empty array, not null.

getCluster

RelOptCluster getCluster()

Returns the cluster this relational expression belongs to.

Returns:

cluster

getConvention

CallingConvention getConvention()

Return the CallingConvention trait from this RelNode's trait set.

Returns:

this RelNode's CallingConvention

getTraits

RelTraitSet getTraits()

Retrieves this RelNode's traits. Note that although the RelTraitSet returned is modifiable, it must not be modified during optimization. It is legal to modify the traits of a RelNode before or after optimization, although doing so could render a tree of RelNodes unimplementable. If a RelNode's traits need to be modified during optimization, clone the RelNode and change the clone's traits.

Returns:

this RelNode's trait set

setCorrelVariable

void setCorrelVariable(String correlVariable)

Sets the name of the variable which is to be implicitly set at runtime each time a row is returned from this relational expression

Parameters:

correlVariable - Name of correlating variable

getCorrelVariable

String getCorrelVariable()

Returns the name of the variable which is to be implicitly set at runtime each time a row is returned from this relational expression; or null if there is no variable.

Returns:

Name of correlating variable, or null

isDistinct

boolean isDistinct()

Returns whether the same value will not come out twice. Default value is false, derived classes should override.

getId

int getId()

Returns the ID of this relational expression, unique among all relational expressions created since the server was started.

Returns:

Unique ID

getInput

RelNode getInput(int i)

Returns the i^th input relational expression.

Parameters:

i - Ordinal of input

Returns:

i^th input

getOrCreateCorrelVariable

String getOrCreateCorrelVariable()

Returns a variable with which to reference the current row of this relational expression as a correlating variable. Creates a variable if none exists.

getQuery

RelOptQuery getQuery()

Returns the sub-query this relational expression belongs to. A sub-query determines the scope for correlating variables (see setCorrelVariable(String)).

Returns:

Sub-query

getRowType

RelDataType getRowType()

Returns the type of the rows returned by this relational expression.

getExpectedInputRowType

RelDataType getExpectedInputRowType(int ordinalInParent)

Returns the type of the rows expected for an input. Defaults to getRowType().

Parameters:

ordinalInParent - input's 0-based ordinal with respect to this parent rel

Returns:

expected row type

getInputs

RelNode[] getInputs()

Returns an array of this relational expression's inputs. If there are no inputs, returns an empty array, not null.

getRows

double getRows()

Returns an estimate of the number of rows this relational expression will return.

NOTE jvs 29-Mar-2006: Don't call this method directly. Instead, use RelMetadataQuery.getRowCount(org.eigenbase.rel.RelNode), which gives plugins a chance to override the rel's default ideas about row count.

getVariablesStopped

Set<String> getVariablesStopped()

Returns the names of variables which are set in this relational expression but also used and therefore not available to parents of this relational expression.

By default, returns the empty set. Derived classes may override this method.

collectVariablesUsed

void collectVariablesUsed(Set<String> variableSet)

Collects variables known to be used by this expression or its descendants. By default, no such information is available and must be derived by analyzing sub-expressions, but some optimizer implementations may insert special expressions which remember such information.

Parameters:

variableSet - receives variables used

collectVariablesSet

void collectVariablesSet(Set<String> variableSet)

Collects variables set by this expression.

Parameters:

variableSet - receives variables known to be set by

childrenAccept

void childrenAccept(RelVisitor visitor)

Interacts with the RelVisitor in a visitor pattern to traverse the tree of relational expressions.

computeSelfCost

RelOptCost computeSelfCost(RelOptPlanner planner)

Returns the cost of this plan (not including children). The base implementation throws an error; derived classes should override.

NOTE jvs 29-Mar-2006: Don't call this method directly. Instead, use RelMetadataQuery.getNonCumulativeCost(org.eigenbase.rel.RelNode), which gives plugins a chance to override the rel's default ideas about cost.

explain

void explain(RelOptPlanWriter pw)

onRegister

void onRegister(RelOptPlanner planner)

Receives notification that this expression is about to be registered. The implementation of this method must at least register all child expressions.

recomputeDigest

String recomputeDigest()

Computes the digest, assigns it, and returns it. For planner use only.

registerCorrelVariable

void registerCorrelVariable(String correlVariable)

Registers a correlation variable.

See Also:

getVariablesStopped()

replaceInput

void replaceInput(int ordinalInParent,
                  RelNode p)

Replaces the ordinalInParent^th input. You must override this method if you override getInputs().

getTable

RelOptTable getTable()

If this relational expression represents an access to a table, returns that table, otherwise returns null.

getRelTypeName

String getRelTypeName()

Returns the name of this relational expression's class, sans package name, for use in explain(org.eigenbase.relopt.RelOptPlanWriter). For example, for a org.eigenbase.rel.ArrayRel.ArrayReader, this method returns "ArrayReader".

isValid

boolean isValid(boolean fail)

Returns whether this relational expression is valid.

If assertions are enabled, this method is typically called with fail = true, as follows:

assert rel.isValid(true)

This signals that the method can throw an AssertionError if it is not valid.

Parameters:

fail - Whether to fail if invalid

Returns:

Whether relational expression is valid

Throws:

AssertionError - if this relational expression is invalid and fail=true and assertions are enabled

getCollationList

List<RelCollation> getCollationList()

Returns a description of the physical ordering (or orderings) of this relational expression.

"Postcondition:"

return != null

getDigest

String getDigest()

Returns a string which concisely describes the definition of this relational expression. Two relational expressions are equivalent if and only if their digests are the same.

The digest does not contain the relational expression's identity -- that would prevent similar relational expressions from ever comparing equal -- but does include the identity of children (on the assumption that children have already been normalized).

If you want a descriptive string which contains the identity, call Object.toString(), which always returns "rel#{id}:{digest}".

getDescription

String getDescription()

Returns a string which describes the relational expression and, unlike getDigest(), also includes the identity. Typically returns "rel#{id}:{digest}".

clone

RelNode clone()

Clones this RelNode.

Traits of the RelNode must be explicitly cloned, using AbstractRelNode.inheritTraitsFrom(AbstractRelNode), as the RelNode may have traits of which it has no knowledge. Example implementation:

     public MyRelNode clone()
     {
         MyRelNode clone = new MyRelNode(...);
         clone.inheritTraitsFrom(this);
         return clone;
     }
 

N.B.: This method must be overridden whenever an existing, concrete RelNode is extended. Otherwise, calling clone() will produce a differently typed RelNode, resulting in invalid or incorrect query plans.

Returns:

a clone of this RelNode