org.apache.calcite.plan.volcano

Class VolcanoPlanner

java.lang.Object

org.apache.calcite.plan.AbstractRelOptPlanner

org.apache.calcite.plan.volcano.VolcanoPlanner

All Implemented Interfaces:

RelOptPlanner

public class VolcanoPlanner
extends AbstractRelOptPlanner

VolcanoPlanner optimizes queries by transforming expressions selectively according to a dynamic programming algorithm.

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.calcite.plan.RelOptPlanner

RelOptPlanner.CannotPlanException, RelOptPlanner.Executor

Field Summary

Fields

Modifier and Type	Field and Description
protected @MonotonicNonNull RelSubset	root

Fields inherited from class org.apache.calcite.plan.AbstractRelOptPlanner

cancelFlag, context, costFactory, mapDescToRule

Fields inherited from interface org.apache.calcite.plan.RelOptPlanner

LOGGER

Constructor Summary

Constructors

Constructor and Description
VolcanoPlanner() Creates a uninitialized VolcanoPlanner.
VolcanoPlanner(Context externalContext) Creates a uninitialized VolcanoPlanner.
VolcanoPlanner(@Nullable RelOptCostFactory costFactory, @Nullable Context externalContext) Creates a VolcanoPlanner with a given cost factory.

Method Summary

Modifier and Type	Method and Description
void	addLattice(RelOptLattice lattice) Defines a lattice.
void	addMaterialization(RelOptMaterialization materialization) Defines a pair of relational expressions that are equivalent.
boolean	addRelTraitDef(RelTraitDef relTraitDef) Registers a rel trait definition.
boolean	addRule(RelOptRule rule) Registers a rule.
RelNode	changeTraits(RelNode rel, RelTraitSet toTraits) Changes a relational expression to an equivalent one with a different set of traits.
void	checkCancel() Checks to see whether cancellation has been requested, and if so, throws an exception.
RelOptPlanner	chooseDelegate() Negotiates an appropriate planner to deal with distributed queries.
void	clear() Removes all internal state, including all registered rules, materialized views, and lattices.
void	clearRelTraitDefs() Clear all the registered RelTraitDef.
void	dump(PrintWriter pw) Dumps the internal state of this VolcanoPlanner to a writer.
RelTraitSet	emptyTraitSet() Creates an empty trait set.
RelSubset	ensureRegistered(RelNode rel, @Nullable RelNode equivRel) Registers a relational expression if it is not already registered.
RelNode	findBestExp() Finds the most efficient expression to implement the query given via RelOptPlanner.setRoot(org.apache.calcite.rel.RelNode).
@Nullable RelOptCost	getCost(RelNode rel, RelMetadataQuery mq) Computes the cost of a RelNode.
@Nullable RelOptLattice	getLattice(RelOptTable table) Retrieves a lattice, given its star table.
protected RelOptCost	getLowerBound(RelNode rel) Gets the lower bound cost of a relational operator.
List<RelOptMaterialization>	getMaterializations() Returns the materializations that have been registered with the planner.
long	getRelMetadataTimestamp(RelNode rel) Deprecated.
List<RelTraitDef>	getRelTraitDefs() Returns the list of active trait types.
@Nullable RelNode	getRoot() Returns the root node of this query.
@Nullable org.apache.calcite.plan.volcano.RelSet	getSet(RelNode rel) Finds an expression's equivalence set.
@Nullable RelSubset	getSubset(RelNode rel) Returns the subset that a relational expression belongs to.
@Nullable RelSubset	getSubset(RelNode rel, RelTraitSet traits)
RelSubset	getSubsetNonNull(RelNode rel) Returns the subset that a relational expression belongs to.
boolean	isLogical(RelNode rel) Decide whether a rule is logical or not.
boolean	isRegistered(RelNode rel) Determines whether a relational expression has been registered.
protected boolean	isSubstituteRule(VolcanoRuleCall match) Checks whether a rule match is a substitution rule match.
protected boolean	isTransformationRule(VolcanoRuleCall match) Checks whether a rule match is a transformation rule match.
protected boolean	isValid(Litmus litmus) Checks internal consistency.
static @PolyNull String	normalizePlan(@PolyNull String plan) Normalizes references to subsets within the string representation of a plan.
protected void	onNewClass(RelNode node) Called when a new class of RelNode is seen.
void	prune(RelNode rel) Prunes a node from the planner.
RelSubset	register(RelNode rel, @Nullable RelNode equivRel) Registers a relational expression in the expression bank.
void	registerAbstractRelationalRules()
protected void	registerMaterializations()
void	registerMetadataProviders(List<RelMetadataProvider> list) Deprecated.
void	registerSchema(RelOptSchema schema) Tells this planner that a schema exists.
boolean	removeRule(RelOptRule rule) Removes a rule.
void	setLocked(boolean locked) Sets whether this planner is locked.
void	setNoneConventionHasInfiniteCost(boolean infinite) Sets whether this planner should consider rel nodes with Convention.NONE to have infinite cost or not.
void	setRoot(RelNode rel) Sets the root node of this query.
void	setTopDownOpt(boolean value) Enable or disable top-down optimization.
String	toDot()
protected RelOptCost	upperBoundForInputs(RelNode mExpr, RelOptCost upperBound) Gets the upper bound of its inputs.

Methods inherited from class org.apache.calcite.plan.AbstractRelOptPlanner

addListener, dumpRuleAttemptsInfo, fireRule, getContext, getCost, getCostFactory, getExecutor, getListener, getRuleByDescription, getRules, isRuleExcluded, notifyChosen, notifyDiscard, notifyEquivalence, notifyTransformation, onCopy, registerClass, setCancelFlag, setExecutor, setRuleDescExclusionFilter, subClasses

Methods inherited from class java.lang.Object

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

Field Detail

root

protected @MonotonicNonNull RelSubset root

Constructor Detail

VolcanoPlanner

public VolcanoPlanner()

Creates a uninitialized VolcanoPlanner. To fully initialize it, the caller must register the desired set of relations, rules, and calling conventions.

VolcanoPlanner

public VolcanoPlanner(Context externalContext)

Creates a uninitialized VolcanoPlanner. To fully initialize it, the caller must register the desired set of relations, rules, and calling conventions.

VolcanoPlanner

public VolcanoPlanner(@Nullable RelOptCostFactory costFactory,
                      @Nullable Context externalContext)

Creates a VolcanoPlanner with a given cost factory.

Method Detail

setTopDownOpt

public void setTopDownOpt(boolean value)

Enable or disable top-down optimization.

Note: Enabling top-down optimization will automatically enable top-down trait propagation.

isRegistered

public boolean isRegistered(RelNode rel)

Description copied from interface: RelOptPlanner

Determines whether a relational expression has been registered.

Parameters:

rel - expression to test

Returns:

whether rel has been registered

setRoot

public void setRoot(RelNode rel)

Description copied from interface: RelOptPlanner

Sets the root node of this query.

Parameters:

rel - Relational expression

getRoot

@Pure
public @Nullable RelNode getRoot()

Description copied from interface: RelOptPlanner

Returns the root node of this query.

Returns:

Root node

getMaterializations

public List<RelOptMaterialization> getMaterializations()

Description copied from interface: RelOptPlanner

Returns the materializations that have been registered with the planner.

Specified by:

getMaterializations in interface RelOptPlanner

Overrides:

getMaterializations in class AbstractRelOptPlanner

addMaterialization

public void addMaterialization(RelOptMaterialization materialization)

Description copied from interface: RelOptPlanner

Defines a pair of relational expressions that are equivalent.

Typically tableRel is a LogicalTableScan representing a table that is a materialized view and queryRel is the SQL expression that populates that view. The intention is that tableRel is cheaper to evaluate and therefore if the query being optimized uses (or can be rewritten to use) queryRel as a sub-expression then it can be optimized by using tableRel instead.

Specified by:

addMaterialization in interface RelOptPlanner

Overrides:

addMaterialization in class AbstractRelOptPlanner

addLattice

public void addLattice(RelOptLattice lattice)

Description copied from interface: RelOptPlanner

Defines a lattice.

The lattice may have materializations; it is not necessary to call RelOptPlanner.addMaterialization(org.apache.calcite.plan.RelOptMaterialization) for these; they are registered implicitly.

Specified by:

addLattice in interface RelOptPlanner

Overrides:

addLattice in class AbstractRelOptPlanner

getLattice

public @Nullable RelOptLattice getLattice(RelOptTable table)

Description copied from interface: RelOptPlanner

Retrieves a lattice, given its star table.

Specified by:

getLattice in interface RelOptPlanner

Overrides:

getLattice in class AbstractRelOptPlanner

registerMaterializations

protected void registerMaterializations()

getSet

public @Nullable org.apache.calcite.plan.volcano.RelSet getSet(RelNode rel)

Finds an expression's equivalence set. If the expression is not registered, returns null.

Parameters:

rel - Relational expression

Returns:

Equivalence set that expression belongs to, or null if it is not registered

addRelTraitDef

public boolean addRelTraitDef(RelTraitDef relTraitDef)

Description copied from interface: RelOptPlanner

Registers a rel trait definition. If the RelTraitDef has already been registered, does nothing.

Specified by:

addRelTraitDef in interface RelOptPlanner

Overrides:

addRelTraitDef in class AbstractRelOptPlanner

Returns:

whether the RelTraitDef was added, as per Collection.add(E)

clearRelTraitDefs

public void clearRelTraitDefs()

Description copied from interface: RelOptPlanner

Clear all the registered RelTraitDef.

Specified by:

clearRelTraitDefs in interface RelOptPlanner

Overrides:

clearRelTraitDefs in class AbstractRelOptPlanner

getRelTraitDefs

public List<RelTraitDef> getRelTraitDefs()

Description copied from interface: RelOptPlanner

Returns the list of active trait types.

Specified by:

getRelTraitDefs in interface RelOptPlanner

Overrides:

getRelTraitDefs in class AbstractRelOptPlanner

emptyTraitSet

public RelTraitSet emptyTraitSet()

Description copied from interface: RelOptPlanner

Creates an empty trait set. It contains all registered traits, and the default values of any traits that have them.

The empty trait set acts as the prototype (a kind of factory) for all subsequently created trait sets.

Specified by:

emptyTraitSet in interface RelOptPlanner

Overrides:

emptyTraitSet in class AbstractRelOptPlanner

Returns:

Empty trait set

clear

public void clear()

Description copied from interface: RelOptPlanner

Removes all internal state, including all registered rules, materialized views, and lattices.

Specified by:

clear in interface RelOptPlanner

Overrides:

clear in class AbstractRelOptPlanner

addRule

public boolean addRule(RelOptRule rule)

Description copied from interface: RelOptPlanner

Registers a rule.

If the rule has already been registered, does nothing. This method determines if the given rule is a ConverterRule and pass the ConverterRule to all registered RelTraitDef instances.

Specified by:

addRule in interface RelOptPlanner

Overrides:

addRule in class AbstractRelOptPlanner

Returns:

whether the rule was added, as per Collection.add(E)

removeRule

public boolean removeRule(RelOptRule rule)

Description copied from interface: RelOptPlanner

Removes a rule.

Specified by:

removeRule in interface RelOptPlanner

Overrides:

removeRule in class AbstractRelOptPlanner

Returns:

true if the rule was present, as per Collection.remove(Object)

onNewClass

protected void onNewClass(RelNode node)

Description copied from class: AbstractRelOptPlanner

Called when a new class of RelNode is seen.

Overrides:

onNewClass in class AbstractRelOptPlanner

changeTraits

public RelNode changeTraits(RelNode rel,
                            RelTraitSet toTraits)

Description copied from interface: RelOptPlanner

Changes a relational expression to an equivalent one with a different set of traits.

Parameters:

rel - Relational expression (may or may not have been registered; must not have the desired traits)

toTraits - Trait set to convert the relational expression to

Returns:

Relational expression with desired traits. Never null, but may be abstract

chooseDelegate

public RelOptPlanner chooseDelegate()

Description copied from interface: RelOptPlanner

Negotiates an appropriate planner to deal with distributed queries. The idea is that the schemas decide among themselves which has the most knowledge. Right now, the local planner retains control.

Specified by:

chooseDelegate in interface RelOptPlanner

Overrides:

chooseDelegate in class AbstractRelOptPlanner

findBestExp

public RelNode findBestExp()

Finds the most efficient expression to implement the query given via RelOptPlanner.setRoot(org.apache.calcite.rel.RelNode).

Returns:

the most efficient RelNode tree found for implementing the given query

checkCancel

public void checkCancel()

Description copied from class: AbstractRelOptPlanner

Checks to see whether cancellation has been requested, and if so, throws an exception.

Overrides:

checkCancel in class AbstractRelOptPlanner

register

public RelSubset register(RelNode rel,
                          @Nullable RelNode equivRel)

Description copied from interface: RelOptPlanner

Registers a relational expression in the expression bank.

After it has been registered, you may not modify it.

The expression must not already have been registered. If you are not sure whether it has been registered, call RelOptPlanner.ensureRegistered(RelNode, RelNode).

Parameters:

rel - Relational expression to register (must not already be registered)

equivRel - Relational expression it is equivalent to (may be null)

Returns:

the same expression, or an equivalent existing expression

ensureRegistered

public RelSubset ensureRegistered(RelNode rel,
                                  @Nullable RelNode equivRel)

Description copied from interface: RelOptPlanner

Registers a relational expression if it is not already registered.

If equivRel is specified, rel is placed in the same equivalence set. It is OK if equivRel has different traits; rel will end up in a different subset of the same set.

It is OK if rel is a subset.

Parameters:

rel - Relational expression to register

equivRel - Relational expression it is equivalent to (may be null)

Returns:

Registered relational expression

isValid

protected boolean isValid(Litmus litmus)

Checks internal consistency.

registerAbstractRelationalRules

public void registerAbstractRelationalRules()

registerSchema

public void registerSchema(RelOptSchema schema)

Description copied from interface: RelOptPlanner

Tells this planner that a schema exists. This is the schema's chance to tell the planner about all of the special transformation rules.

Specified by:

registerSchema in interface RelOptPlanner

Overrides:

registerSchema in class AbstractRelOptPlanner

setNoneConventionHasInfiniteCost

public void setNoneConventionHasInfiniteCost(boolean infinite)

Sets whether this planner should consider rel nodes with Convention.NONE to have infinite cost or not.

Parameters:

infinite - Whether to make none convention rel nodes infinite cost

getCost

public @Nullable RelOptCost getCost(RelNode rel,
                                    RelMetadataQuery mq)

Description copied from interface: RelOptPlanner

Computes the cost of a RelNode. In most cases, this just dispatches to RelMetadataQuery.getCumulativeCost(org.apache.calcite.rel.RelNode).

Specified by:

getCost in interface RelOptPlanner

Overrides:

getCost in class AbstractRelOptPlanner

Parameters:

rel - Relational expression of interest

mq - Metadata query

Returns:

estimated cost

getSubset

public @Nullable RelSubset getSubset(RelNode rel)

Returns the subset that a relational expression belongs to.

Parameters:

rel - Relational expression

Returns:

Subset it belongs to, or null if it is not registered

getSubsetNonNull

@API(since="1.26",
     status=EXPERIMENTAL)
public RelSubset getSubsetNonNull(RelNode rel)

Returns the subset that a relational expression belongs to.

Parameters:

rel - Relational expression

Returns:

Subset it belongs to, or null if it is not registered

Throws:

AssertionError - in case subset is not found

getSubset

public @Nullable RelSubset getSubset(RelNode rel,
                                     RelTraitSet traits)

prune

public void prune(RelNode rel)

Description copied from interface: RelOptPlanner

Prunes a node from the planner.

When a node is pruned, the related pending rule calls are cancelled, and future rules will not fire. This can be used to reduce the search space.

Specified by:

prune in interface RelOptPlanner

Overrides:

prune in class AbstractRelOptPlanner

Parameters:

rel - the node to prune.

dump

public void dump(PrintWriter pw)

Dumps the internal state of this VolcanoPlanner to a writer.

Parameters:

pw - Print writer

See Also:

normalizePlan(String)

toDot

public String toDot()

registerMetadataProviders

@Deprecated
public void registerMetadataProviders(List<RelMetadataProvider> list)

Deprecated.

Description copied from interface: RelOptPlanner

Gives this planner a chance to register one or more RelMetadataProviders in the chain which will be used to answer metadata queries.

Planners which use their own relational expressions internally to represent concepts such as equivalence classes will generally need to supply corresponding metadata providers.

Specified by:

registerMetadataProviders in interface RelOptPlanner

Overrides:

registerMetadataProviders in class AbstractRelOptPlanner

Parameters:

list - receives planner's custom providers, if any

getRelMetadataTimestamp

@Deprecated
public long getRelMetadataTimestamp(RelNode rel)

Deprecated.

Description copied from interface: RelOptPlanner

Gets a timestamp for a given rel's metadata. This timestamp is used by CachingRelMetadataProvider to decide whether cached metadata has gone stale.

Specified by:

getRelMetadataTimestamp in interface RelOptPlanner

Overrides:

getRelMetadataTimestamp in class AbstractRelOptPlanner

Parameters:

rel - rel of interest

Returns:

timestamp of last change which might affect metadata derivation

normalizePlan

public static @PolyNull String normalizePlan(@PolyNull String plan)

Normalizes references to subsets within the string representation of a plan.

This is useful when writing tests: it helps to ensure that tests don't break when an extra rule is introduced that generates a new subset and causes subsequent subset numbers to be off by one.

For example,

FennelAggRel.FENNEL_EXEC(child=Subset#17.FENNEL_EXEC,groupCount=1, EXPR$1=COUNT())
FennelSortRel.FENNEL_EXEC(child=Subset#2.FENNEL_EXEC, key=[0], discardDuplicates=false)
FennelCalcRel.FENNEL_EXEC( child=Subset#4.FENNEL_EXEC, expr#0..8={inputs}, expr#9=3456, DEPTNO=$t7, $f0=$t9)
MockTableImplRel.FENNEL_EXEC( table=[CATALOG, SALES, EMP])

becomes

FennelAggRel.FENNEL_EXEC(child=Subset#{0}.FENNEL_EXEC, groupCount=1, EXPR$1=COUNT())
FennelSortRel.FENNEL_EXEC(child=Subset#{1}.FENNEL_EXEC, key=[0], discardDuplicates=false)
FennelCalcRel.FENNEL_EXEC( child=Subset#{2}.FENNEL_EXEC,expr#0..8={inputs},expr#9=3456,DEPTNO=$t7, $f0=$t9)
MockTableImplRel.FENNEL_EXEC( table=[CATALOG, SALES, EMP])

Returns null if and only if plan is null.

Parameters:

plan - Plan

Returns:

Normalized plan

setLocked

public void setLocked(boolean locked)

Sets whether this planner is locked. A locked planner does not accept new rules. addRule(org.apache.calcite.plan.RelOptRule) will do nothing and return false.

Parameters:

locked - Whether planner is locked

isLogical

@API(since="1.24",
     status=EXPERIMENTAL)
public boolean isLogical(RelNode rel)

Decide whether a rule is logical or not.

Parameters:

rel - The specific rel node

Returns:

True if the relnode is a logical node

isSubstituteRule

@API(since="1.24",
     status=EXPERIMENTAL)
protected boolean isSubstituteRule(VolcanoRuleCall match)

Checks whether a rule match is a substitution rule match.

Parameters:

match - The rule match to check

Returns:

True if the rule match is a substitution rule match

isTransformationRule

@API(since="1.24",
     status=EXPERIMENTAL)
protected boolean isTransformationRule(VolcanoRuleCall match)

Checks whether a rule match is a transformation rule match.

Parameters:

match - The rule match to check

Returns:

True if the rule match is a transformation rule match

getLowerBound

@API(since="1.24",
     status=EXPERIMENTAL)
protected RelOptCost getLowerBound(RelNode rel)

Gets the lower bound cost of a relational operator.

Parameters:

rel - The rel node

Returns:

The lower bound cost of the given rel. The value is ensured NOT NULL.

upperBoundForInputs

@API(since="1.24",
     status=EXPERIMENTAL)
protected RelOptCost upperBoundForInputs(RelNode mExpr,
                                                                                      RelOptCost upperBound)

Gets the upper bound of its inputs. Allow users to overwrite this method as some implementations may have different cost model on some RelNodes, like Spool.