org.apache.calcite.plan

Interface RelOptPlanner

All Known Implementing Classes:

AbstractRelOptPlanner, HepPlanner, VolcanoPlanner

public interface RelOptPlanner

A RelOptPlanner is a query optimizer: it transforms a relational expression into a semantically equivalent relational expression, according to a given set of rules and a cost model.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	RelOptPlanner.CannotPlanException Thrown by findBestExp().
static interface	RelOptPlanner.Executor Can reduce expressions, writing a literal for each into a list.

Field Summary

Fields

Modifier and Type	Field and Description
static Logger	LOGGER

Method Summary

Methods

Modifier and Type	Method and Description
void	addLattice(RelOptLattice lattice) Defines a lattice.
void	addListener(RelOptListener newListener) Adds a listener to this planner.
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.
RelOptPlanner	chooseDelegate() Negotiates an appropriate planner to deal with distributed queries.
void	clear() Removes all internal state, including all rules.
void	clearRelTraitDefs() Clear all the registered RelTraitDef.
RelTraitSet	emptyTraitSet() Creates an empty trait set.
RelNode	ensureRegistered(RelNode rel, RelNode equivRel) Registers a relational expression if it is not already registered.
RelNode	findBestExp() Finds the most efficient expression to implement this query.
Context	getContext() Provides the Context created when this planner was constructed.
RelOptCost	getCost(RelNode rel) Computes the cost of a RelNode.
RelOptCostFactory	getCostFactory() Returns the factory that creates RelOptCosts.
RelOptPlanner.Executor	getExecutor()
RelOptLattice	getLattice(RelOptTable table) Retrieves a lattice, given its star table.
long	getRelMetadataTimestamp(RelNode rel) Gets a timestamp for a given rel's metadata.
List<RelTraitDef>	getRelTraitDefs() Returns the list of active trait types.
RelNode	getRoot() Returns the root node of this query.
boolean	isRegistered(RelNode rel) Determines whether a relational expression has been registered.
void	onCopy(RelNode rel, RelNode newRel) Called when a relational expression is copied to a similar expression.
RelNode	register(RelNode rel, RelNode equivRel) Registers a relational expression in the expression bank.
void	registerClass(RelNode node) Registers a class of RelNode.
void	registerMetadataProviders(List<RelMetadataProvider> list) Gives this planner a chance to register one or more RelMetadataProviders in the chain which will be used to answer metadata queries.
void	registerSchema(RelOptSchema schema) Tells this planner that a schema exists.
boolean	removeRule(RelOptRule rule) Removes a rule.
void	setCancelFlag(CancelFlag cancelFlag) Installs the cancellation-checking flag for this planner.
void	setExecutor(RelOptPlanner.Executor executor) Sets the object that can execute scalar expressions.
void	setImportance(RelNode rel, double importance) Sets the importance of a relational expression.
void	setRoot(RelNode rel) Sets the root node of this query.
void	setRuleDescExclusionFilter(Pattern exclusionFilter) Sets the exclusion filter to use for this planner.

Field Detail

LOGGER

static final Logger LOGGER

Method Detail

setRoot

void setRoot(RelNode rel)

Sets the root node of this query.

Parameters:

rel - Relational expression

getRoot

RelNode getRoot()

Returns the root node of this query.

Returns:

Root node

addRelTraitDef

boolean addRelTraitDef(RelTraitDef relTraitDef)

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

Returns:

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

clearRelTraitDefs

void clearRelTraitDefs()

Clear all the registered RelTraitDef.

getRelTraitDefs

List<RelTraitDef> getRelTraitDefs()

Returns the list of active trait types.

clear

void clear()

Removes all internal state, including all rules.

addRule

boolean addRule(RelOptRule rule)

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.

Returns:

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

removeRule

boolean removeRule(RelOptRule rule)

Removes a rule.

Returns:

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

getContext

Context getContext()

Provides the Context created when this planner was constructed.

Returns:

Never null; either an externally defined context, or a dummy context that returns null for each requested interface

setRuleDescExclusionFilter

void setRuleDescExclusionFilter(Pattern exclusionFilter)

Sets the exclusion filter to use for this planner. Rules which match the given pattern will not be fired regardless of whether or when they are added to the planner.

Parameters:

exclusionFilter - pattern to match for exclusion; null to disable filtering

setCancelFlag

void setCancelFlag(CancelFlag cancelFlag)

Installs the cancellation-checking flag for this planner. The planner should periodically check this flag and terminate the planning process if it sees a cancellation request.

Parameters:

cancelFlag - flag which the planner should periodically check

changeTraits

RelNode changeTraits(RelNode rel,
                   RelTraitSet toTraits)

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

RelOptPlanner chooseDelegate()

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.

addMaterialization

void addMaterialization(RelOptMaterialization materialization)

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.

addLattice

void addLattice(RelOptLattice lattice)

Defines a lattice.

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

getLattice

RelOptLattice getLattice(RelOptTable table)

Retrieves a lattice, given its star table.

findBestExp

RelNode findBestExp()

Finds the most efficient expression to implement this query.

Throws:

RelOptPlanner.CannotPlanException - if cannot find a plan

getCostFactory

RelOptCostFactory getCostFactory()

Returns the factory that creates RelOptCosts.

getCost

RelOptCost getCost(RelNode rel)

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

Parameters:

rel - expression of interest

Returns:

estimated cost

register

RelNode register(RelNode rel,
               RelNode equivRel)

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

RelNode ensureRegistered(RelNode rel,
                       RelNode equivRel)

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

isRegistered

boolean isRegistered(RelNode rel)

Determines whether a relational expression has been registered.

Parameters:

rel - expression to test

Returns:

whether rel has been registered

registerSchema

void registerSchema(RelOptSchema schema)

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

addListener

void addListener(RelOptListener newListener)

Adds a listener to this planner.

Parameters:

newListener - new listener to be notified of events

registerMetadataProviders

void registerMetadataProviders(List<RelMetadataProvider> list)

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.

Parameters:

list - receives planner's custom providers, if any

getRelMetadataTimestamp

long getRelMetadataTimestamp(RelNode rel)

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

Parameters:

rel - rel of interest

Returns:

timestamp of last change which might affect metadata derivation

setImportance

void setImportance(RelNode rel,
                 double importance)

Sets the importance of a relational expression.

An important use of this method is when a RelOptRule has created a relational expression which is indisputably better than the original relational expression. The rule set the original relational expression's importance to zero, to reduce the search space. Pending rule calls are cancelled, and future rules will not fire.

Parameters:

rel - Relational expression

importance - Importance

registerClass

void registerClass(RelNode node)

Registers a class of RelNode. If this class of RelNode has been seen before, does nothing.

Parameters:

node - Relational expression

emptyTraitSet

RelTraitSet emptyTraitSet()

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.

Returns:

Empty trait set

setExecutor

void setExecutor(RelOptPlanner.Executor executor)

Sets the object that can execute scalar expressions.

getExecutor

RelOptPlanner.Executor getExecutor()

onCopy

void onCopy(RelNode rel,
          RelNode newRel)

Called when a relational expression is copied to a similar expression.