org.apache.calcite.rel

Interface RelNode

All Superinterfaces:

Cloneable, RelOptNode

All Known Subinterfaces:

BindableRel, Converter, EnumerableRel, InterpretableRel, JdbcRel, RelStructuredTypeFlattener.SelfFlatteningRel

All Known Implementing Classes:

AbstractConverter, AbstractRelNode, Aggregate, Bindables.BindableAggregate, Bindables.BindableFilter, Bindables.BindableJoin, Bindables.BindableProject, Bindables.BindableSort, Bindables.BindableTableScan, Bindables.BindableUnion, Bindables.BindableValues, Bindables.BindableWindow, BiRel, Calc, Chi, Collect, ConverterImpl, Correlate, Delta, EnumerableAggregate, EnumerableBindable, EnumerableCalc, EnumerableCollect, EnumerableCorrelate, EnumerableFilter, EnumerableInterpretable, EnumerableInterpreter, EnumerableIntersect, EnumerableJoin, EnumerableLimit, EnumerableMergeJoin, EnumerableMinus, EnumerableProject, EnumerableSemiJoin, EnumerableSort, EnumerableTableFunctionScan, EnumerableTableModify, EnumerableTableScan, EnumerableThetaJoin, EnumerableUncollect, EnumerableUnion, EnumerableValues, EnumerableWindow, EquiJoin, EquiJoin, Exchange, Filter, HepRelVertex, InterpretableConverter, Intersect, JdbcRules.JdbcAggregate, JdbcRules.JdbcCalc, JdbcRules.JdbcFilter, JdbcRules.JdbcIntersect, JdbcRules.JdbcJoin, JdbcRules.JdbcMinus, JdbcRules.JdbcProject, JdbcRules.JdbcSort, JdbcRules.JdbcTableModify, JdbcRules.JdbcUnion, JdbcRules.JdbcValues, JdbcTableScan, JdbcToEnumerableConverter, Join, LogicalAggregate, LogicalCalc, LogicalChi, LogicalCorrelate, LogicalDelta, LogicalExchange, LogicalFilter, LogicalIntersect, LogicalJoin, LogicalMinus, LogicalProject, LogicalSort, LogicalTableFunctionScan, LogicalTableModify, LogicalTableScan, LogicalUnion, LogicalValues, LogicalWindow, Minus, MultiJoin, NoneConverter, Project, RelSubset, Sample, SemiJoin, SetOp, SingleRel, Sort, SortExchange, StarTable.StarTableScan, TableFunctionScan, TableModify, TableScan, Uncollect, Union, Values, Window

public interface RelNode
extends RelOptNode, Cloneable

A RelNode is a relational expression.

Relational expressions process data, so their names are typically verbs: Sort, Join, Project, Filter, Scan, Sample.

A relational expression is not a scalar expression; see SqlNode and RexNode.

If this type of relational expression has some particular planner rules, it should implement the public static method AbstractRelNode.register(org.apache.calcite.plan.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 Convention 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, implementations 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, org.apache.calcite.adapter.enumerable.EnumerableRel has operations to manage the conversion to a graph of org.apache.calcite.adapter.enumerable.EnumerableConvention calling-convention, and it interacts with a EnumerableRelImplementor.

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

Method Summary

Methods

Modifier and Type	Method and Description
RelNode	accept(RelShuttle shuttle) Accepts a visit from a shuttle.
RelNode	accept(RexShuttle shuttle) Accepts a visit from a shuttle.
void	childrenAccept(RelVisitor visitor) Interacts with the RelVisitor in a visitor pattern to traverse the tree of relational expressions.
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).
RelNode	copy(RelTraitSet traitSet, List<RelNode> inputs) Creates a copy of this relational expression, perhaps changing traits and inputs.
void	explain(RelWriter pw) Describes the inputs and attributes of this relational expression.
List<RexNode>	getChildExps() Deprecated. use #accept(org.apache.calcite.rex.RexShuttle)
List<RelCollation>	getCollationList() Deprecated. Use RelMetadataQuery.distribution(RelNode)
Convention	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 the first input of this relational expression; or null if there is no variable.
RelDataType	getExpectedInputRowType(int ordinalInParent) Returns the type of the rows expected for an input.
RelNode	getInput(int i) Returns the ith input relational expression.
List<RelNode>	getInputs() Returns an array of this relational expression's inputs.
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.
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.
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	isDistinct() Returns whether the same value will not come out twice.
boolean	isKey(ImmutableBitSet columns) Returns whether the result of this relational expression is uniquely identified by this columns with the given ordinals.
boolean	isValid(boolean fail) Returns whether this relational expression is valid.
<M extends Metadata> M	metadata(Class<M> metadataClass) Returns a metadata interface.
RelNode	onRegister(RelOptPlanner planner) Receives notification that this expression is about to be registered.
String	recomputeDigest() Computes the digest, assigns it, and returns it.
void	register(RelOptPlanner planner) Registers any special rules specific to this kind of relational expression.
void	replaceInput(int ordinalInParent, RelNode p) Replaces the ordinalInParentth input.

Methods inherited from interface org.apache.calcite.plan.RelOptNode

getCluster, getDescription, getDigest, getId, getTraitSet

Method Detail

getChildExps

@Deprecated
List<RexNode> getChildExps()

Deprecated. use #accept(org.apache.calcite.rex.RexShuttle)

Returns a list of this relational expression's child expressions. (These are scalar expressions, and so do not include the relational inputs that are returned by getInputs().

The caller should treat the list as unmodifiable; typical implementations will return an immutable list. If there are no child expressions, returns an empty list, not null.

Returns:

List of this relational expression's child expressions

See Also:

accept(org.apache.calcite.rex.RexShuttle)

getConvention

Convention getConvention()

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

Returns:

this RelNode's CallingConvention

getCorrelVariable

String getCorrelVariable()

Returns the name of the variable which is to be implicitly set at runtime each time a row is returned from the first input of 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.

Returns:

Whether the same value will not come out twice

getInput

RelNode getInput(int i)

Returns the i^th input relational expression.

Parameters:

i - Ordinal of input

Returns:

i^th input

getQuery

RelOptQuery getQuery()

Returns the sub-query this relational expression belongs to.

Returns:

Sub-query

getRowType

RelDataType getRowType()

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

Specified by:

getRowType in interface RelOptNode

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

List<RelNode> getInputs()

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

Specified by:

getInputs in interface RelOptNode

Returns:

Array of this relational expression's inputs

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.apache.calcite.rel.RelNode), which gives plugins a chance to override the rel's default ideas about row count.

Returns:

Estimate of the number of rows this relational expression will return

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.

Note: only Correlate should set variables

Returns:

Names of variables which are set in this relational expression

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. TODO: is this required?

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.

Parameters:

visitor - Visitor that will 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.apache.calcite.rel.RelNode), which gives plugins a chance to override the rel's default ideas about cost.

Parameters:

planner - Planner for cost calculation

Returns:

Cost of this plan (not including children)

metadata

<M extends Metadata> M metadata(Class<M> metadataClass)

Returns a metadata interface.

Type Parameters:

M - Type of metadata being requested

Parameters:

metadataClass - Metadata interface

Returns:

Metadata object that supplies the desired metadata (never null, although if the information is not present the metadata object may return null from all methods)

explain

void explain(RelWriter pw)

Describes the inputs and attributes of this relational expression. Each node should call super.explain, then call the RelWriterImpl.input(String, RelNode) and RelWriterImpl.item(String, Object) methods for each input and attribute.

Parameters:

pw - Plan writer

onRegister

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

Parameters:

planner - Planner that plans this relational node

Returns:

Relational expression that should be used by the planner

recomputeDigest

String recomputeDigest()

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

Returns:

Digest of this relational expression

replaceInput

void replaceInput(int ordinalInParent,
                RelNode p)

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

Parameters:

ordinalInParent - Position of the child input, 0 is the first

p - New node that should be put at position ordinalInParent

getTable

RelOptTable getTable()

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

Returns:

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. For example, for a org.apache.calcite.rel.ArrayRel.ArrayReader, this method returns "ArrayReader".

Returns:

Name of this relational expression's class, sans package name, for use in explain

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

@Deprecated
List<RelCollation> getCollationList()

Deprecated. Use RelMetadataQuery.distribution(RelNode)

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

Returns:

Description of the physical ordering (or orderings) of this relational expression. Never null

copy

RelNode copy(RelTraitSet traitSet,
           List<RelNode> inputs)

Creates a copy of this relational expression, perhaps changing traits and inputs.

Sub-classes with other important attributes are encouraged to create variants of this method with more parameters.

Parameters:

traitSet - Trait set

inputs - Inputs

Returns:

Copy of this relational expression, substituting traits and inputs

register

void register(RelOptPlanner planner)

Registers any special rules specific to this kind of relational expression.

The planner calls this method this first time that it sees a relational expression of this class. The derived class should call RelOptPlanner.addRule(org.apache.calcite.plan.RelOptRule) for each rule, and then call super.register.

Parameters:

planner - Planner to be used to register additional relational expressions

isKey

boolean isKey(ImmutableBitSet columns)

Returns whether the result of this relational expression is uniquely identified by this columns with the given ordinals.

For example, if this relational expression is a LogicalTableScan to T(A, B, C, D) whose key is (A, B), then isKey([0, 1]) yields true, and isKey([0]) and isKey([0, 2]) yields false.

Parameters:

columns - Ordinals of key columns

Returns:

Whether the given columns are a key or a superset of a key

accept

RelNode accept(RelShuttle shuttle)

Accepts a visit from a shuttle.

Parameters:

shuttle - Shuttle

Returns:

A copy of this node incorporating changes made by the shuttle to this node's children

accept

RelNode accept(RexShuttle shuttle)

Accepts a visit from a shuttle. If the shuttle updates expression, then a copy of the relation should be created.

Parameters:

shuttle - Shuttle

Returns:

A copy of this node incorporating changes made by the shuttle to this node's children